docs: list the gradient optimizers as refine_method options - #664
Merged
Conversation
refine=1 has accepted gntr, lbfgs, trf and ms as refiners since #403, and all four register with refiner=True. The docs listed only sim, powell and cmaes, so the search-globally-then-polish-with-a-gradient-method workflow was undiscoverable from the documentation. Updates the refinement section in algorithms.rst and both places in config_keys.rst that enumerate the options, splitting them into a derivative-free group usable with any model and a gradient-based group for models that supply sensitivities.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this changes
The documentation says that
refine_methodacceptssim,powell, orcmaes. It actually accepts four more. Every gradient optimizer registers itself as a refiner, sorefine = 1withrefine_method = gntrhas worked since #403, along withlbfgs,trf, andms.That means the workflow of searching globally with a metaheuristic and then polishing the result with a gradient method, which is usually the quickest way to converge a model built from ordinary differential equations, could not be discovered from the documentation. A user would have to read the registry to find out it was possible.
What was edited
Three places listed the options, and all three were wrong in the same way.
docs/algorithms.rst, which is the page a user is pointed to from the config key reference. Rewritten to present two groups, one derivative-free and usable with any model, and one gradient-based for models that supply sensitivities. A guidance bullet for the gradient option was added alongside the existing ones for Simplex, Powell, and CMA-ES.varandlogvarkeys indocs/config_keys.rst.refine_methodentry indocs/config_keys.rst, which also gains a second example.No code changed. This is documentation catching up with what the code already does.
Checking
Built with the same command and flags the docs workflow uses, which treats warnings as errors:
The build succeeds with no warnings. The new cross reference to the gradient optimization section resolves.