Stata manual for -ml- does not explain what -gtol()- refers to

[Hewan Belayneh]

Dear Statalisters,

I have seen commands in -ml- that use as an option -gtol()-. For example, in this past post: https://www.stata.com/statalist/arch.../msg01091.html the following command is used:
ml maximize, tech(nr bhhh dfp bfgs) tol(1e-12) gtol(1e-12) force Another example is here: https://www.statalist.org/forums/for...ction-frontier which uses:

ml max, difficult gtol(1e-5) nrtol(1e-5)

There are many other examples.

But searching the stata manual, https://www.stata.com/manuals13/rml.pdf I don't find any explanation about gtol. I also didn't find gtol anywhere mentioned in the full (2,997 page) stata manual. Please let me know why this may be, and where I can learn more about what this ml option does.

Thanks,
Hewan

[FernandoRios]

I think you are simply not looking at the helpfile carefully enough
check help ml, search for tolerance.
This will direct you to "help maximize"
HTH

[William Lisowski]

Welcome to Statalist.

I was fascinated by this. By any chance, are you attempting to do stochastic frontier analysis following the techniques in the book A Practitioner's Guide To Stochastic Frontier Analysis In Stata by Kumbhakar and Wang (2015)? A search of Statalist for "gtol" only turns it up in reference to Stochastic Frontier Analysis, and when a reference is given, that book seems to be the go-to.

Here is what I have found.

The output of help whatsnew8 tells us that on 5 November 2003 an update to Stata release 8 added the nltolerance() option for maximization commands as an improvement on the previous gtolerance() option. And I note in the documentation for ml maximize that nltolerance() is indeed one of the maximization options it accepts, and directs us to the maximize documentation for details.

When I look at the code behind ml maximize (viewsource ml_max.ado) I see that it uses version control set to version 6, and the code accepts both the nltolerance() and gtolerance() options. An antique comment in the code describes gtolerance() as specifying the "relative gradient_k/(1+Beta_k) tolerance" while help maximize tells us that nltolrance() specifies the tolerance for g*inv(H)*g' . Whatever those mean.

So there you have it. Old code originally developed, likely, before Stata release 8 continues to be supported under Stata release 16.

[Scott Merryman]

It is explained under -arch-:

 gtolerance(#) specifies the tolerance for the gradient relative to the coefficients.  When |g_i*b_i|
    < gtolerance() for all parameters b_i and the corresponding elements of the gradient g_i, the
    gradient tolerance criterion is met.  The default gradient tolerance for arch is gtolerance(.05).

[William Lisowski]

Aha. It seems that the writer of the maximize documentation thinks gtolerance() has been deprecated in favor of nltolerance(). But as is usual for Stata, the gtolerance() code remains in place for backward compatibility and for use under version control, and arch continues to favor gtolerance() over nltolerance(). Perhaps someone didn't get the nltolerance() memo, or perhaps in this case gltolerance() performs adequately, or nltolerance() performs poorly.

Reflecting on this, I think I would conclude that Stata documentation is good at describing the current version of Stata, but does not try to document every historical possibility that remains available from past versions. That way lies madness. The problem then arises when we try to interpret older code that makes use of features that have generally been improved upon in newer releases and are no longer included in the documentation.

[Hewan Belayneh]

Dear Scott, thanks so much for pointing me to the mention of -gtolerance()- in -arch-. This gives me an idea that -gtol()- determines how "fine-grained" the search for a maximum is to be.
William, much appreciated for the reference that nltolerance() appears to supercede -gtol- Even if there is no more stata manual that describes the old code, I was surprised that I didn't find anything on statalist (or generally google) re gtol heretofore.
Fernando, just to let you know that neither the help for -ml- nor that for -maximise- ever mentions -gtolerance-. But the above pointers by Scott and William have been helpful, thus am all set.
Thanks!
Hewan

[Hewan Belayneh]

Dear William, sorry I forgot to reply to your question: Yes: indeed I am trying to use the -sfmodel- command developed by Kumbhakar and Wang (2015), and I have already perused the book, especially the relevant chapter, Ch. 3.