Repository navigation
Convert all algorithm documentation to the new format. - #690
Merged
Merged
Conversation
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
… annotations. With `from __future__ import annotations`, dataclass field types are annotation strings rather than type objects, so the TYPE_CONVERTERS lookup in Algorithm.__post_init__ never matched and option coercion/validation was silently skipped for all optimizer modules using the import. Adds a string-keyed TYPE_CONVERTERS_BY_NAME lookup so coercion works identically with and without the import, plus regression tests: a dummy algorithm defined under postponed annotations mirroring the existing type conversion tests, and a registry-wide test that passes floats for all int-typed options of every algorithm. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
janosg
force-pushed
the
standardize-algo-docs
branch
from
July 5, 2026 15:15
51d4bec to
cde6d90
Compare
Brings in #696, which replaces the hand-written option converter table with pydantic validation. PR #691, whose fix for the same problem was the first commit on this branch, was closed in favor of #696, so its changes are dropped here rather than merged: - src/optimagic/type_conversion.py: deleted (superseded by validated_dataclass in optimagic/typing.py), including the TYPE_CONVERTERS_BY_NAME lookup #691 added. - Algorithm.__post_init__: removed, main validates via mark.minimizer instead. - tests/.../test_algorithm_future_annotations.py: deleted. Its coverage of the postponed-annotations path is provided by main's test_algo_option_validation_stringified.py, and its registry-wide int coercion test by test_all_algorithms_can_be_instantiated_with_defaults. Docs conflicts resolved by keeping this branch's docstrings on top of main's widened annotations: - Fides.hessian_update_strategy is now HessianUpdateStrategy, not a bare Literal, so its docstring no longer claims that HessianApproximation instances are unavailable; it explains that Broyden must be passed as an instance because phi has no default. - PygmoMbh.inner_algorithm uses the PygmoAlgorithm alias. Also documents the new constraint that field annotations must be resolvable at runtime in how_to_document_optimizers.md, since pydantic now resolves them and a TYPE_CHECKING-only name in a field type raises on instantiation. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
abelaba
reviewed
Sep 29, 2026
Collaborator
There was a problem hiding this comment.
For the algorithm examples, the value passed to params parameter is a list, and the lambda function passed to fun does a matrix multiplication. If someone tries to directly copy and paste the example, it fails. How about changing the lambda function to lambda x: sum(v**2 for v in x) or the list into a NumPy array, and also removing the ellipsis from the algorithm options?
For example:
import optimagic as om
om.minimize(
fun=lambda x: sum(v**2 for v in x),
params=[1.0, 2.0, 3.0],
algorithm=om.algos.scipy_neldermead(stopping_maxiter=1_000),
)Or
import numpy as np
import optimagic as om
om.minimize(
fun=lambda x: x @ x,
params=np.array([1.0, 2.0, 3.0]),
algorithm=om.algos.scipy_neldermead(stopping_maxiter=1_000),
)Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Removes CLEANUP_NOTES.MD, CONSTRAINTS_REFACTOR_REVIEW.md and REPORT.md, which were committed by accident, and fixes "libray" and "simple have a look" in how_to_add_optimizers.ipynb. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts: # docs/source/refs.bib
Every example in algorithms.md now passes params as a NumPy array, drops the `...` placeholders and is self-contained, so each code block runs as is. Bounds are added for all algorithms that need them, and least-squares and likelihood examples mark their functions accordingly. This also fixes examples that used options that don't exist (bayes_opt `n_iter`, pyswarms `topology_type` and `k_neighbors`), a syntax error in the iminuit example, a shgo example that crashed without bounds, and a nag_pybobyqa string-interface example whose option was silently dropped. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Since mark.minimizer re-creates algorithm classes as pydantic dataclasses that inherit from the original class, autodoc treated all documented fields as inherited and did not show them. Every autoclass directive in algorithms.md now uses `:inherited-members: Algorithm, object`, as the gfo and pyswarms entries already did, and the how-to guide explains why. The guide's quote of the ScipyLBFGSB docstring is synced with the corrected docstring. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…sources. Every class and field docstring was checked against the optimagic wrapper code and the upstream sources (scipy 1.17.1, NLopt 2.10.1, pagmo2, Ipopt 3.14 / cyipopt 1.6.1, DFO-LS 1.6.2, Py-BOBYQA 1.5.0, fides 0.7.4, tranquilo 0.1.1). Wrong formulas, defaults, option semantics and references are corrected, undocumented deviations from upstream defaults are stated, and where the wrapper behaves unexpectedly the docstrings describe the actual behavior. The stale module-level constant docstrings in nag_optimizers.py, which contradicted the class docs, are removed. Typos in a few error and warning messages are fixed; no logic changes. refs.bib gets corrected author fields and titles and a new entry for the Ipopt negative curvature test. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts: # docs/source/how_to/how_to_add_optimizers.ipynb
# Conflicts: # docs/source/algorithms.md # src/optimagic/optimizers/nlopt_optimizers.py
This was referenced Nov 15, 2026
Open
timmens
approved these changes
Nov 15, 2026
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
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.
Previously, algorithm documentation was in algorithms.md; now it's in the docstrings of the algorithm classes. The new format is described here. While converting, we found and fixed the issues listed below. Every docstring was checked against the optimagic wrapper code and the upstream sources: scipy 1.17.1, NLopt 2.10.1, pagmo2, Ipopt 3.14 / cyipopt 1.6.1, DFO-LS 1.6.2, Py-BOBYQA 1.5.0, fides 0.7.4 and tranquilo 0.1.1. Where the wrapper behaves unexpectedly, the docstrings describe what it actually does. The underlying code bugs are fixed in follow-up PRs or listed in #583. Apart from corrected error and warning messages, this PR changes no code.
0. Changes to
algorithms.mdand the how-to guidemark.minimizerre-creates every algorithm class as a pydantic dataclass that inherits from the original class. Autodoc therefore treated all documented fields as inherited and hid them. Everyautoclassnow uses:inherited-members: Algorithm, object, as the gfo and pyswarms entries already did. The how-to guide explains why.paramsas a NumPy array, has no...placeholders and is self-contained. Bounds are added where the algorithm needs them, and least-squares and likelihood examples mark their functions. All 184 snippets were executed. Onlynevergrad_bo(needsbayes-optim) andtao_pounders(Linux only) could not be run. This also fixed examples that were broken before:bayes_optused a nonexistentn_iteroption.topology_typeandk_neighborsoptions.fides>=0.7.4, make sure you have at least 0.7.1"), "AX-platfofm" and "Toolkit of Advanced optimization".neg_curv_test_*options. They cited an unrelated paper before.1. Errors in the old documentation (corrected)
scipy
Stale constraint-support notes. The old text said "SLSQP's / COBYLA's / trust_constr's general nonlinear constraints are not supported yet by optimagic". All three have
supports_nonlinear_constraints=Truetoday. The new docstrings instead explain how optimagic converts equality constraints to pairs of inequality constraints for COBYLA. COBYLA natively only handles inequalities.Copy-paste error in
scipy_newton_cg. The warning advised refining "an optimum found with Powell" with another optimizer. It meant an optimum found with newton_cg.Wrong default for
scipy_direct. The old text claimed that the volume toleranceepsdefaults to 1e-6, "differing from scipy's default 1e-4". The actual optimagic default isCONVERGENCE_FTOL_REL = 2e-9. A smallerepsmakes the search more local, not a larger one.Wrong Powell convergence formula. The documented
ftolformula was the one from L-BFGS-B. Powell uses2(f^k - f^{k+1}) <= ftol (|f^k| + |f^{k+1}|) + 1e-20.xtolonly controls the precision of the line search; it is not a stopping criterion.Nonexistent options documented.
scipy_truncated_newtonwas documented withstopping.maxiter, but the class only hasstopping_maxfun.scipy_ls_lmwas documented withtr_solver/tr_solver_options, which only exist for the trf and dogbox least-squares solvers. Both were dropped.Misleading option semantics:
stopping_maxiterlimits function evaluations.xtolis an average absolute step criterion.n_local_optimizationslocal optimizations in total (SciPyniter = n - 1).minhgrdstops after a single iteration whose growth is at most the given value.finishis called asfinish(func, x0, args=...).shgo:
n_simplex_iterationshas no effect becausemaxevis always passed.Outdated implementation claims. COBYLA has used PRIMA's pure-Python implementation since SciPy 1.16. L-BFGS-B has used a C translation since SciPy 1.15.
Several places where optimagic's defaults silently differ from SciPy are now stated explicitly:
nmaxevfinishfminTypos fixed:
finitie_difference_precisionandmessg_num→mesg_num.nlopt
supports_nonlinear_constraints=False).xtol_relsemantics were outdated. NLopt uses an L1-norm test,sum |Δx| < tol · sum |x|, not a per-parameter test.stopping_maxfun.nlopt.srand.random_search=Truerequireslocally_biased=True; other combinations currently raise an error.nlopt_lbfgs, but the algorithm is registered asnlopt_lbfgsb.nlopt_tnewtonis the plainLD_TNEWTON, not "preconditioned".ftol_rel.:cite:role missing its colon).pygmo
Wrong default population size formula. The old text said "twice the number of parameters but at least X". The code (
get_population_size) uses10 * (n_params + 1), clipped below at the algorithm-specific minimum.ftol/xtoldescriptions swapped for sade, de1220, cmaes and xnes. This is a known pagmo documentation bug that had been copied into algorithms.md.Wrong option ranges and defaults, checked against the pagmo C++ source:
de.weight_coefficientis in [0, 1], not [0, 2].sga.mutation_polynomial_distribution_indexis in [1, 100].sga.selection_tournament_sizedefaults to 2.compass_search.stop_rangemust be strictly smaller thanstart_range.Wrong behavior claims:
Literaltypes.seedonly seeds the initial population.stopping_maxfunis pagmo'sevalstop, which counts generations without improvement.max_fevals=1.Undocumented deviations from pygmo defaults are now stated:
max_n_trialsstopping_max_inner_runs_without_improvementn_range_adjustmentsbin_sizeinitial_search_shareA broken
.. note:directive is fixed.GWO: fixed typos, and the criticism of the algorithm is attributed to the pagmo developers.
The
batch_evaluatorbullets for gaco and pso_gen were dropped; these classes only haven_cores.ipopt
Contradictory
linear_solverdefault. The old text said the default is "ma27", while its own value list said "mumps (default)". The code default is"mumps"; Ipopt's own documented default is "ma27".Options are always passed explicitly. This turns off Ipopt's behavior for unset options, and the affected docstrings now say so:
mu_max_facthas no effect.mu_minis used as given.recalc_yandmu_strategy="adaptive"are not switched on for limited-memory.slack_bound_*does not followbound_*.expect_infeasible_problemdoes not tightenrequired_infeasibility_reduction.Unusable or surprising options now carry warnings:
skip_finalize_solution_callreturns the start parameters with success=True.mehrotra_algorithmaborts unless four further options are set.hessian_approximation="exact"runs without a valid Hessian, because optimagic passes none.warm_start_same_structureaborts.Other options documented with their actual behavior:
warm_start_entire_iteratehas no effect.obj_scaling_factorcannot replaceom.maximize.Default mismatches:
acceptable_dual_inf_tol: the old text documented Ipopt's default of 1e+10, but the code passes 1e-10 (see code issues). The docstring now documents the actual behavior, including that acceptable termination effectively never triggers.resto_failure_feasibility_threshold: the old text said 0; the wrapper mapsNoneto100 * convergence_ftol_rel.Wrong references.
alpha_min_fracis Eqn. (23), not (20).neg_curv_test_*options cited the wrong paper.expect_infeasible_problemis commented out in Ipopt 3.14.Mangled bullets fixed.
theta_max_facthad been fused into thewatchdog_trial_iter_maxbullet, andrecalc_y_feas_tolwas mislabeled.Value typos:
filter_margin_fact)sigma_min)"bound_mult"→"bound-mult"adaptive_mu_kkterror_red_itersis an int, not a floatDeviations from Ipopt defaults are now stated:
tolmax_iterhessian_approximationoption_file_nameThe class docstring names the renamed options and lists all options that are not exposed.
NAG (DFO-LS, Py-BOBYQA)
seek_global_optimumrestriction was wrong. The old text said: "Only applies for noisy criterion functions." Py-BOBYQA's documentation demonstrates it on noise-free functions. The actual requirement is that lower and upper bounds are both specified (individual entries may be infinite).scale_of_trustregion_step_perturbationis always 1.shrinking_factor_not_successfuluses DFO-LS's default, not the user's value.len(x)was dropped, because DFO-LS requires npt ≥len(x)+1.floor_of_jacobian_singular_valueshas no effect.use_resetsdefault also depends onseek_global_optimum.n_extra_*reset options and the auto-detect criteria are corrected.model.abs_tol)."trustregion", the value the code accepts.noise_n_evals_per_pointis documented with its actual positional calling convention, plus a warning that it is currently unusable.:ref:pointers were removed.fides
trustregion.subspace_dimensionwas documented as defaulting to "2D". The optimagic default is"full"; the fides package itself defaults to "2D".stepback_strategyto"truncate", while fides defaults to"reflect".muis not an acceptance threshold. fides accepts every step with a positive ratio, andmuonly triggers a radius decrease.trustregion.refine_stepbackandtrustregion.scaled_gradient_as_possible_stepbackwere documented but are not fields of the class.Optimizer.check_convergence).subspace_dimension="full".>as a redirect.TAO pounders
convergence_gtol_*criteria therefore currently have no effect, and reachingstopping_maxiteris reported as success. This is now documented.\epsilon,X0→X_0).Own optimizers (bhhh, neldermead_parallel, pounders)
@om.mark.likelihoodinterface.funit moves uphill (see code issues).criterion/xparameters.adaptiveadapts to the problem dimension (Gao–Han).n_corescap only applies to parallel reflections.gtol_reldefault was written as "1-8".trustregion_expansion_factor_successfulwas described as a "Shrinking factor"."steihaug_toint".batch_evaluatoroption was dropped.Other documentation fixes
nevergrad_wizard/nevergrad_portfoliodropdowns were broken. They referenced classes that no longer exist (NevergradWizard,Wizard,NevergradPortfolio,Portfolio). The dropdowns are renamed tonevergrad_ngopt/nevergrad_meta, and the examples are rewritten.how_to_add_optimizers.ipynbcrashed the docs build. Its@mark.minimizercall was missing the now-requiredneeds_boundsandsupports_infinite_boundsarguments. Also fixed a dead cross-reference and typos.acceptance_decider="classic_line_search".model_typeis fixed per version.stopping_maxtimeandconvergence_min_trust_region_radiushave no effect.seed=Noneraises an error.batch_evaluatoris not forwarded.🤖 Generated with Claude Code