biogeme.likelihood.model_estimation module

Run a model estimation using a specified optimization algorithm.

This module defines the interface for executing a Biogeme-compatible optimization routine and collecting its results.

Michel Bierlaire Sun Mar 30 16:07:55 2025

class biogeme.likelihood.model_estimation.AlgorithmResults(solution, optimization_messages, convergence)

Bases: NamedTuple

Container for the results returned by an optimization algorithm.

Parameters:

• solution (ndarray) – Optimal values of the parameters as a NumPy array.

• optimization_messages (dict[str, Any]) – Dictionary with diagnostic messages from the optimizer.

• convergence (bool) – Boolean indicating whether the optimization terminated successfully.

convergence: bool

Alias for field number 2

optimization_messages: dict[str, Any]

Alias for field number 1

solution: ndarray

Alias for field number 0

biogeme.likelihood.model_estimation.model_estimation(the_algorithm, function_evaluator, parameters, some_starting_values, save_iterations_filename)

Estimate a model using the specified optimization algorithm and modeling elements.

This function prepares the model log-likelihood function and its derivatives based on the provided modeling elements and starting values. It constructs the objective function and delegates the actual optimization to the optimization routine.

Parameters:

• the_algorithm (Callable[[FunctionToMinimize, ndarray, list[tuple[float, float]], list[str], dict[str, Any] | None], OptimizationResults]) – The optimization algorithm to use.

• function_evaluator (CompiledFormulaEvaluator) – Object with the compiled information to evaluate the function.

• parameters (dict[str, bool | int | float | str]) – Dictionary of configuration parameters for the estimation.

• some_starting_values (dict[str, float]) – Initial values for a subset or all of the model’s free parameters.

• save_iterations_filename (str | None) – If not None, the name of the file where to save the best iterations.

Return type:

AlgorithmResults

Returns:

A tuple containing: - the optimal parameter values as a NumPy array, - a dictionary of optimization diagnostic messages, - a boolean indicating whether the optimization converged successfully.

biogeme.likelihood.model_estimation.optimization(the_algorithm, the_function, starting_values, bounds, variable_names, parameters)

Run an optimization algorithm to estimate model parameters.

Parameters:

• the_algorithm (Callable[[FunctionToMinimize, ndarray, list[tuple[float, float]], list[str], dict[str, Any] | None], OptimizationResults]) – Optimization algorithm conforming to the Biogeme interface.

• the_function (FunctionToMinimize) – Function to minimize, providing function value and derivatives.

• starting_values (ndarray) – Initial guess for the optimization variables.

• bounds (list[tuple[float, float]]) – List of (lower, upper) bounds for each parameter.

• variable_names (list[str]) – Names of the variables (used for reporting or algorithm diagnostics).

• parameters (dict[str, Any]) – Dictionary of additional parameters passed to the optimization algorithm.

Return type:

AlgorithmResults

Returns:

A tuple with: - x_star: the optimal solution (array of estimated parameters), - optimization_messages: a dictionary with diagnostic messages and timing, - convergence: a boolean indicating whether the optimization converged successfully.