docs: list the gradient optimizers as refine_method options by wshlavacek · Pull Request #664 · lanl/PyBNF

wshlavacek · 2026-08-25T04:36:22Z

What this changes

The documentation says that refine_method accepts sim, powell, or cmaes. It actually accepts four more. Every gradient optimizer registers itself as a refiner, so refine = 1 with refine_method = gntr has worked since #403, along with lbfgs, trf, and ms.

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.

The refinement section of 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.
The note about var and logvar keys in docs/config_keys.rst.
The refine_method entry in docs/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:

uv run --with 'sphinx>=7,<9' sphinx-build -W --keep-going -b html docs <output>

The build succeeds with no warnings. The new cross reference to the gradient optimization section resolves.

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.

wshlavacek · 2026-08-25T04:36:22Z

What this changes

The documentation says that refine_method accepts sim, powell, or cmaes. It actually accepts four more. Every gradient optimizer registers itself as a refiner, so refine = 1 with refine_method = gntr has worked since #403, along with lbfgs, trf, and ms.

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.

The refinement section of 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.
The note about var and logvar keys in docs/config_keys.rst.
The refine_method entry in docs/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:

uv run --with 'sphinx>=7,<9' sphinx-build -W --keep-going -b html docs <output>

The build succeeds with no warnings. The new cross reference to the gradient optimization section resolves.

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.

wshlavacek · 2026-08-25T04:36:22Z

What this changes

The documentation says that refine_method accepts sim, powell, or cmaes. It actually accepts four more. Every gradient optimizer registers itself as a refiner, so refine = 1 with refine_method = gntr has worked since #403, along with lbfgs, trf, and ms.

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.

The refinement section of 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.
The note about var and logvar keys in docs/config_keys.rst.
The refine_method entry in docs/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:

uv run --with 'sphinx>=7,<9' sphinx-build -W --keep-going -b html docs <output>

The build succeeds with no warnings. The new cross reference to the gradient optimization section resolves.

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.

wshlavacek · 2026-08-25T04:36:22Z

What this changes

The documentation says that refine_method accepts sim, powell, or cmaes. It actually accepts four more. Every gradient optimizer registers itself as a refiner, so refine = 1 with refine_method = gntr has worked since #403, along with lbfgs, trf, and ms.

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.

The refinement section of 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.
The note about var and logvar keys in docs/config_keys.rst.
The refine_method entry in docs/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:

uv run --with 'sphinx>=7,<9' sphinx-build -W --keep-going -b html docs <output>

The build succeeds with no warnings. The new cross reference to the gradient optimization section resolves.

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.

wshlavacek · 2026-08-25T04:36:22Z

What this changes

The documentation says that refine_method accepts sim, powell, or cmaes. It actually accepts four more. Every gradient optimizer registers itself as a refiner, so refine = 1 with refine_method = gntr has worked since #403, along with lbfgs, trf, and ms.

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.

The refinement section of 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.
The note about var and logvar keys in docs/config_keys.rst.
The refine_method entry in docs/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:

uv run --with 'sphinx>=7,<9' sphinx-build -W --keep-going -b html docs <output>

The build succeeds with no warnings. The new cross reference to the gradient optimization section resolves.

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.

wshlavacek · 2026-08-25T04:36:22Z

What this changes

The documentation says that refine_method accepts sim, powell, or cmaes. It actually accepts four more. Every gradient optimizer registers itself as a refiner, so refine = 1 with refine_method = gntr has worked since #403, along with lbfgs, trf, and ms.

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.

The refinement section of 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.
The note about var and logvar keys in docs/config_keys.rst.
The refine_method entry in docs/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:

uv run --with 'sphinx>=7,<9' sphinx-build -W --keep-going -b html docs <output>

The build succeeds with no warnings. The new cross reference to the gradient optimization section resolves.

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.

wshlavacek · 2026-08-25T04:36:22Z

What this changes

The documentation says that refine_method accepts sim, powell, or cmaes. It actually accepts four more. Every gradient optimizer registers itself as a refiner, so refine = 1 with refine_method = gntr has worked since #403, along with lbfgs, trf, and ms.

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.

The refinement section of 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.
The note about var and logvar keys in docs/config_keys.rst.
The refine_method entry in docs/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:

uv run --with 'sphinx>=7,<9' sphinx-build -W --keep-going -b html docs <output>

The build succeeds with no warnings. The new cross reference to the gradient optimization section resolves.

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.

wshlavacek · 2026-08-25T04:36:22Z

What this changes

The documentation says that refine_method accepts sim, powell, or cmaes. It actually accepts four more. Every gradient optimizer registers itself as a refiner, so refine = 1 with refine_method = gntr has worked since #403, along with lbfgs, trf, and ms.

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.

The refinement section of 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.
The note about var and logvar keys in docs/config_keys.rst.
The refine_method entry in docs/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:

uv run --with 'sphinx>=7,<9' sphinx-build -W --keep-going -b html docs <output>

The build succeeds with no warnings. The new cross reference to the gradient optimization section resolves.

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.

wshlavacek merged commit 2493ba4 into mainAug 25, 2026
9 checks passed

wshlavacek deleted the docs-refine-method-gradient-optimizers branch August 25, 2026 04:52