biogeme.calculator.single_formula module

Module in charge of the actual calculation of the formula on the database.

Michel Bierlaire Wed Mar 26 19:30:57 2025

class biogeme.calculator.single_formula.CompiledFormulaEvaluator(model_elements, second_derivatives_mode, numerically_safe)[source]

Bases: object

Compiles and evaluates a Biogeme expression using JAX for efficient

repeated computation.

Parameters:
evaluate(the_betas, gradient, hessian, bhhh)[source]
Return type:

FunctionOutput

Parameters:

  • the_betas (dict[str, float])

  • gradient (bool)

  • hessian (bool)

  • bhhh (bool)

evaluate_individual(the_betas)[source]

Evaluates the compiled expression using provided beta values and returns the value of the expression for each observation.

Parameters:

the_betas (dict[str, float]) – Dictionary of parameter names to values.

Return type:

ndarray

Returns:

A numpy array with one value per observation.

biogeme.calculator.single_formula.calculate_single_formula(model_elements, the_betas, gradient, hessian, bhhh, second_derivatives_mode, numerically_safe)[source]
Evaluates a single Biogeme expression using JAX, optionally computing the gradient

and Hessian.

Parameters:

  • model_elements (ModelElements) – All elements needed to calculate the expression.

  • the_betas (dict[str, float]) – Dictionary of parameter names to values.

  • gradient (bool) – If True, compute the gradient.

  • hessian (bool) – If True, compute the Hessian (requires gradient=True).

  • bhhh (bool) – Unused here, included for compatibility.

  • second_derivatives_mode (SecondDerivativesMode) – specifies how second derivatives are calculated.

  • numerically_safe (bool) – improves the numerical stability of the calculations.

Return type:

FunctionOutput

Returns:

A BiogemeFunctionOutput with the value, gradient, and optionally the Hessian.

biogeme.calculator.single_formula.calculate_single_formula_from_expression(expression, database, number_of_draws, the_betas, second_derivatives_mode, numerically_safe, use_jit)[source]
Return type:

float

Parameters:
biogeme.calculator.single_formula.evaluate_expression(expression, numerically_safe, use_jit, database=None, betas=None, number_of_draws=1000, aggregation=False)[source]

Evaluate an arithmetic expression

Parameters:

  • expression (Expression) – the expression to be evaluated

  • numerically_safe (bool) – if True, the numerical stability of the evaluation is improved, possibly at the expense of calculation speed. Set it to False except if necessary.

  • use_jit (bool) – if True, performs just-in-time compilation.

  • database (Database | None) – database, needed if the expression involves Variable

  • betas (dict[str, float] | None) – values of the parameters, if the expression involves Beta

  • number_of_draws (int) – number of draws for Monte Carlo integration, if the expression involves it.

  • aggregation (bool) – if True, the sum over all rows is calculated. If False, the value for each row is returned.

Return type:

ndarray | float

biogeme.calculator.single_formula.evaluate_formula(model_elements, the_betas, second_derivatives_mode, numerically_safe)[source]

Evaluates a single Biogeme expression using JAX.

Parameters:

  • model_elements (ModelElements) – All elements needed to calculate the expression.

  • the_betas (dict[str, float]) – Dictionary of parameter names to values.

  • second_derivatives_mode (SecondDerivativesMode) – specifies how second derivatives are calculated.

  • numerically_safe (bool) – improves the numerical stability of the calculations.

Return type:

float

Returns:

the value of the expression.

biogeme.calculator.single_formula.evaluate_model_per_row(model_elements, the_betas, second_derivatives_mode, numerically_safe)[source]

Evaluates a Biogeme expression for each entry in the database and returns individual results.

This function compiles the expression using JAX, applies it to all observations in the database, and returns a NumPy array containing the evaluated values per observation. The result is not aggregated or summed.

Parameters:

  • model_elements (ModelElements) – All elements needed to calculate the expression.

  • the_betas (dict[str, float]) – Dictionary mapping parameter names to their values.

  • second_derivatives_mode (SecondDerivativesMode) – specifies how second derivatives are calculated.

  • numerically_safe (bool) – improves the numerical stability of the calculations.

Return type:

ndarray

Returns:

A NumPy array of values, one for each observation in the database.

biogeme.calculator.single_formula.get_value_and_derivatives(expression, numerically_safe, use_jit, betas=None, database=None, number_of_draws=1000, gradient=True, hessian=True, bhhh=True, named_results=False)[source]
Return type:

FunctionOutput | NamedFunctionOutput

Parameters:

  • expression (Expression)

  • numerically_safe (bool)

  • use_jit (bool)

  • betas (dict[str, float] | None)

  • database (Database | None)

  • number_of_draws (int)

  • gradient (bool)

  • hessian (bool)

  • bhhh (bool)

  • named_results (bool)

biogeme.calculator.single_formula.get_value_c(expression, numerically_safe, use_jit, database=None, betas=None, number_of_draws=1000, aggregation=False)[source]

For backward compatibility. This function used to be a member of the Expression class.

Return type:

ndarray | float

Parameters:

  • expression (Expression)

  • numerically_safe (bool)

  • use_jit (bool)

  • database (Database | None)

  • betas (dict[str, float] | None)

  • number_of_draws (int)

  • aggregation (bool)