biogeme-optimization

Various optimization algorithms used for teaching and research. In particular, they are used by Biogeme.

Biogeme-facing optimizer API

The optimizer can be installed and used without installing the full biogeme distribution:

uv add biogeme-optimization

The canonical imports are:

from biogeme_optimization.function import FunctionToMinimize
from biogeme_optimization.optimization import bfgs_trust_region_for_biogeme

bfgs_trust_region_for_biogeme accepts an objective, a one-dimensional NumPy initial vector, one bound pair and variable name per parameter, and an options mapping containing maxiter, tolerance, and objective_tolerance. It returns a typed result with solution, convergence, and messages attributes. The result retains its historical three-item tuple shape for Biogeme callers; resumable state is exposed as the separate result.state attribute.

The trust-region BFGS path requires only objective and gradient evaluation; implementing a Hessian is optional. The historical bounds argument remains part of the API, although this particular legacy trust-region BFGS algorithm does not enforce finite bounds. The package does not import or depend on the full biogeme distribution.

Resumable trust-region BFGS

The Biogeme-facing trust-region BFGS entry point accepts a TrustRegionBFGSState through state= and returns the final state as result.state. State schema version 1 records the current objective and gradient, BFGS approximation, model history, trust-region radius, cumulative iteration/evaluation counters, convergence status, objective scaling, and the algorithm options. state.to_dict() is JSON-compatible; state.to_npz() and TrustRegionBFGSState.from_npz() provide an efficient binary representation for large Hessian matrices.

checkpoint_callback receives a deep immutable snapshot after initialization, after every rejected or accepted trust-region boundary, and immediately before convergence, interruption, or an iteration-limit return. stop_requested() can request a resumable checkpoint_requested return. Existing calls without state retain the legacy numerical behavior, and the optimizer requires only the objective/gradient protocol; the full biogeme package is not required.

The package contains the following modules:

algebra

It contains functions dealing with linear algebra:

• A modified Cholesky factorization introduced by Schnabel and Eskow (1999)
• The calculation of a descent direction based on this factorization.

bfgs

The functions in this module calculate

• the BFGS update of the hessian approximation (see Eq. (13.12) in Bierlaire (2015)),
• the inverse BFGS update of the hessian approximation (see Eq. (13.13) in Bierlaire (2015)).

bounds

This module mainly defines the class Boundsthat manages the bound constraints.

diagnostics

This module defines the diagnostic of some optimization subproblems (dogleg, and comjugate gradient).

exceptions

It defines the OptimizationError exception.

format

It defines the class FormattedColumns that formats the information reported at each iteration of an algorithm.

function

It defines the abstract class FunctionToMinimize that encapsulate the calculation of the objective function and its derivatives.

hybrid_function

It defines the class HybridFunction that calculates the objective function and its derivatives, where the second derivative can be either the analytical hessian, or a BFGS approximation.

linesearch

This module implements the line search algorithms (see Chapter 11 in Bierlaire, 2015).

simple_bounds

This module implements the minimization algorithm under bound constraints proposed by Conn et al. (1988).

trust_region

This module implements the trust region algorithms (see Chapter 12 in Bierlaire, 2015).

References

• Bierlaire, M. (2015). Optimization: Principles and Algortihms. EPFL Press.
• Conn, A. R., Gould, N. I. M and Toint, Ph. L. (1988) Testing a Class of Methods for Solving Minimization Problems with Simple Bounds on the Variables. Mathematics of Computation, 50(182), 399-430.
• Schnabel, R. B. and Eskow, E. (1999) A Revised Modified Cholesky Factorization Algorithm. SIAM Journal on Optimization, 9(4), 1135-1148.