Metadata-Version: 2.4
Name: biogeme-optimization
Version: 0.0.12
Summary: Various optimization algorithms for teaching and research
Author-email: Michel Bierlaire <michel.bierlaire@epfl.ch>
Project-URL: Code, https://github.com/michelbierlaire/optimization
Project-URL: homepage, http://biogeme.epfl.ch
Project-URL: download-url, https://pypi.org/project/biogeme-optimization
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy<3,>=2.0.2
Requires-Dist: scipy<2,>=1.13.1
Requires-Dist: matplotlib<4,>=3.9.4
Requires-Dist: tomlkit<1,>=0.13.2
Requires-Dist: lark>=1.2.2
Requires-Dist: tabulate>=0.9.0
Requires-Dist: networkx>=3.4
Requires-Dist: icecream>=2.1.3
Requires-Dist: dominate>=2.9.1
Provides-Extra: testing
Requires-Dist: pytest>=8.3.5; extra == "testing"
Requires-Dist: pytest-cov>=6.1.1; extra == "testing"
Requires-Dist: tox>=4.26.0; extra == "testing"

# biogeme-optimization
[![PyPi](https://img.shields.io/pypi/v/biogeme_optimization.svg)](https://pypi.python.org/pypi/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:

```bash
uv add biogeme-optimization
```

The canonical imports are:

```python
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 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.

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 `Bounds`that 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](https://transp-or.epfl.ch/books/optimization/html/OptimizationPrinciplesAlgorithms2018.pdf). 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](https://www.ams.org/journals/mcom/1988-50-182/S0025-5718-1988-0929544-3/S0025-5718-1988-0929544-3.pdf). Mathematics
  of Computation, 50(182), 399-430.
- Schnabel, R. B. and Eskow, E. (1999) [A Revised Modified Cholesky Factorization Algorithm](https://doi.org/10.1137/s105262349833266x). SIAM Journal on Optimization, 9(4), 1135-1148.
