Information on -hess_step option to confirm that gradient isn't a problem

[iantaylor-NOAA]

As discussed in class today, if you have a maximum gradient component which is larger than the convergence criterion specified in the starter file (e.g. 0.002 vs 0.0001 for the final convergence criteria), then you can use the -hess_step option described in https://nmfs-ost.github.io/ss3-doc/SS330_User_Manual_release.html#hess-step.

A description for what this option does from Cole Monnahan at admb-project/admb#160 is

One approach used in other contexts is to take Newton steps using the information in the Hessian. Basically, given the MLE found by the optimizer you take MLE*=MLE-(inverse Hessian)(gradient), where the Hessian and gradient are calculated from that spot. This value MLE then in theory is much closer to the mode, but it has a high cost due to the extra matrix calculations.

A key requirement to use this option is that the model needs to be initially run with Hessian before running again with the -hess_step added, such as via the two separate calls on the command line

SS3
SS3 -hess_step

or two separate calls to the r4ss function:

r4ss::run(...)
r4ss::run(..., extras = "-hess_step")

At the end of the second run, you may get a message like the following

The 2 Hessian step(s) reduced maxgrad from 0.00385281 to 0 and NLL by 2.36469e-11.
All output files should be updated, but confirm as this is experimental still.
The fact this was successful gives strong evidence of convergence to a mode with quadratic log-likelihood surface.

This doesn't mean that you should use the second model run to replace your original model with the less good gradient. Instead, it's better to just add a sentence to the report along the lines of

The maximum gradient component was slightly higher than the convergence criterion, but the "hess_step" option was used successfully to confirm that the gradient could be improved without changing the model results, providing strong evidence of convergence to a mode with quadratic log-likelihood surface.