Configuration parameters

Biogeme can be configured using a parameter file. By default, the name is supposed to be biogeme.toml. If such a file does not exist, Biogeme will create one containing the default values. The following table provides a description of all parameters that can be configured.

Name

Description

Default

Section

Type

largest_neighborhood

int: size of the largest neighborhood copnsidered by the Variable Neighborhood Search (VNS) algorithm.

20

AssistedSpecification

int

maximum_attempts

int: an attempts consists in selecting a solution in the Pareto set, and trying to improve it. The parameter imposes an upper bound on the total number of attempts, irrespectively if they are successful or not.

100

AssistedSpecification

int

maximum_number_parameters

int: maximum number of parameters allowed in a model. Each specification with a higher number is deemed invalid and not estimated.

50

AssistedSpecification

int

number_of_neighbors

int: maximum number of neighbors that are visited by the VNS algorithm.

20

AssistedSpecification

int

version

Version of Biogeme that created the TOML file. Do not modify this value.

3.3.1

Biogeme

str

number_of_jobs

int: The maximum number of concurrently running jobs. If -1 is given, joblib tries to use all CPUs.

2

Bootstrap

int

bootstrap_samples

int: number of re-estimations for bootstrap sampling.

100

Estimation

int

calculating_second_derivatives

Defines how to calculate the second derivatives: analytical,finite_differences,never.

analytical

Estimation

str

large_data_set

If the number of observations is larger than this value, the data set is deemed large, and the default estimation algorithm will not use second derivatives.

100000

Estimation

int

max_number_parameters_to_report

int: maximum number of parameters to report during the estimation.

15

Estimation

int

maximum_number_catalog_expressions

If the expression contains catalogs, the parameter sets an upper bound of the total number of possible combinations that can be estimated in the same loop.

100

Estimation

int

optimization_algorithm

str: optimization algorithm to be used for estimation. Valid values: [‘automatic’, ‘scipy’, ‘LS-newton’, ‘TR-newton’, ‘LS-BFGS’, ‘TR-BFGS’, ‘simple_bounds’, ‘simple_bounds_newton’, ‘simple_bounds_BFGS’]

automatic

Estimation

str

save_iterations

bool: If True, the current iterate is saved after each iteration, in a file named __[modelName].iter, where [modelName] is the name given to the model. If such a file exists, the starting values for the estimation are replaced by the values saved in the file.

True

Estimation

bool

number_of_draws

int: Number of draws for Monte-Carlo integration.

10000

MonteCarlo

int

seed

int: Seed used for the pseudo-random number generation. It is useful only when each run should generate the exact same result. If 0, a new seed is used at each run.

0

MonteCarlo

int

number_of_threads

int: Number of threads/processors to be used. If the parameter is 0, the number of available threads is calculated using cpu_count().

0

MultiThreading

int

generate_html

bool: “True” if the HTML file with the results must be generated.

True

Output

bool

generate_yaml

bool: “True” if the yaml file with the results must be generated.

True

Output

bool

identification_threshold

float: if the smallest eigenvalue of the second derivative matrix is lesser or equal to this parameter, the model is considered not identified. The corresponding eigenvector is then reported to identify the parameters involved in the issue.

1e-05

Output

float

only_robust_stats

bool: “True” if only the robust statistics need to be reported. If “False”, the statistics from the Rao-Cramer bound are also reported.

True

Output

bool

save_validation_results

bool: “True” if the validation results are saved in CSV files.

True

Output

bool

enlarging_factor

If an iteration is very successful, the radius of the trust region is multiplied by this factor

10

SimpleBounds

float

infeasible_cg

If True, the conjugate gradient algorithm may generate infeasible solutions until termination. The result will then be projected on the feasible domain. If False, the algorithm stops as soon as an infeasible iterate is generated

False

SimpleBounds

bool

initial_radius

Initial radius of the trust region

1

SimpleBounds

float

max_iterations

int: maximum number of iterations

1000

SimpleBounds

int

second_derivatives

float: proportion (between 0 and 1) of iterations when the analytical Hessian is calculated

1.0

SimpleBounds

float

steptol

The algorithm stops when the relative change in x is below this threshold. Basically, if p significant digits of x are needed, steptol should be set to 1.0e-p.

3.666852862501036e-11

SimpleBounds

float

tolerance

float: the algorithm stops when this precision is reached

6.055454452393343e-06

SimpleBounds

float

missing_data

number: If one variable has this value, it is assumed that a data is missing and an exception will be triggered.

99999

Specification

int

numerically_safe

If true, Biogeme is doing its best to deal with numerical issues, such as division by a number close to zero, at the possible expense of speed.

False

Specification

bool

use_jit

If True, the model is compiled using jit (just-in-time) to speed up the calculation. For complex models, compilation time may exceed the gain due to compilation, so that it is worth turning it off.

True

Specification

bool

dogleg

bool: choice of the method to solve the trust region subproblem. True: dogleg. False: truncated conjugate gradient.

True

TrustRegion

bool

The structure of the biogeme.toml file is as follows.

  1# Default parameter file for Biogeme 3.3.1
  2# Automatically created on September 03, 2025. 08:19:44
  3
  4[Bootstrap]
  5number_of_jobs = 2 # int: The maximum number of concurrently running jobs. If -1
  6                   # is given, joblib tries to use all CPUs.
  7
  8[Estimation]
  9bootstrap_samples = 100 # int: number of re-estimations for bootstrap sampling.
 10calculating_second_derivatives = "analytical" # Defines how to calculate the second
 11                                              # derivatives:
 12                                              # analytical,finite_differences,never.
 13                                              # 
 14large_data_set = 100000 # If the number of observations is larger than this
 15                        # value, the data set is deemed large, and the default
 16                        # estimation algorithm will not use second derivatives.
 17max_number_parameters_to_report = 15 # int: maximum number of parameters to
 18                                     # report during the estimation.
 19save_iterations = "True" # bool: If True, the current iterate is saved after each
 20                         # iteration, in a file named ``__[modelName].iter``,
 21                         # where ``[modelName]`` is the name given to the model.
 22                         # If such a file exists, the starting values for the
 23                         # estimation are replaced by the values saved in the
 24                         # file.
 25maximum_number_catalog_expressions = 100 # If the expression contains catalogs,
 26                                         # the parameter sets an upper bound of
 27                                         # the total number of possible
 28                                         # combinations that can be estimated in
 29                                         # the same loop.
 30optimization_algorithm = "automatic" # str: optimization algorithm to be used for
 31                                     # estimation. Valid values: ['automatic',
 32                                     # 'scipy', 'LS-newton', 'TR-newton',
 33                                     # 'LS-BFGS', 'TR-BFGS', 'simple_bounds',
 34                                     # 'simple_bounds_newton',
 35                                     # 'simple_bounds_BFGS']
 36
 37[MultiThreading]
 38number_of_threads = 0 # int: Number of threads/processors to be used. If the
 39                      # parameter is 0, the number of available threads is
 40                      # calculated using cpu_count().
 41
 42[TrustRegion]
 43dogleg = "True" # bool: choice of the method to solve the trust region subproblem.
 44                # True: dogleg. False: truncated conjugate gradient.
 45
 46[Biogeme]
 47version = "3.3.1" # Version of Biogeme that created the TOML file. Do not modify
 48                  # this value.
 49
 50[MonteCarlo]
 51number_of_draws = 10000 # int: Number of draws for Monte-Carlo integration.
 52seed = 0 # int: Seed used for the pseudo-random number generation. It is useful
 53         # only when each run should generate the exact same result. If 0, a new
 54         # seed is used at each run.
 55
 56[Specification]
 57missing_data = 99999 # number: If one variable has this value, it is assumed that
 58                     # a data is missing and an exception will be triggered.
 59numerically_safe = "False" # If true, Biogeme is doing its best to deal with
 60                           # numerical issues, such as division by a number close
 61                           # to zero, at the possible expense of speed.
 62use_jit = "True" # If True, the model is compiled using jit (just-in-time) to speed
 63                 # up the calculation. For complex models, compilation time may
 64                 # exceed the gain due to compilation, so that it is worth
 65                 # turning it off.
 66
 67[Output]
 68identification_threshold = 1e-05 # float: if the smallest eigenvalue of the
 69                                 # second derivative matrix is lesser or equal to
 70                                 # this parameter, the model is considered not
 71                                 # identified. The corresponding eigenvector is
 72                                 # then reported to identify the parameters
 73                                 # involved in the issue.
 74only_robust_stats = "True" # bool: "True" if only the robust statistics need to be
 75                           # reported. If "False", the statistics from the
 76                           # Rao-Cramer bound are also reported.
 77generate_html = "True" # bool: "True" if the HTML file with the results must be
 78                       # generated.
 79generate_yaml = "True" # bool: "True" if the yaml file with the results must be
 80                       # generated.
 81save_validation_results = "True" # bool: "True" if the validation results are saved
 82                                 # in CSV files.
 83
 84[AssistedSpecification]
 85maximum_number_parameters = 50 # int: maximum number of parameters allowed in a
 86                               # model. Each specification with a higher number
 87                               # is deemed invalid and not estimated.
 88number_of_neighbors = 20 # int: maximum number of neighbors that are visited by
 89                         # the VNS algorithm.
 90largest_neighborhood = 20 # int: size of the largest neighborhood copnsidered by
 91                          # the Variable Neighborhood Search (VNS) algorithm.
 92maximum_attempts = 100 # int: an attempts consists in selecting a solution in the
 93                       # Pareto set, and trying to improve it. The parameter
 94                       # imposes an upper bound on the total number of attempts,
 95                       # irrespectively if they are successful or not.
 96
 97[SimpleBounds]
 98second_derivatives = 1.0 # float: proportion (between 0 and 1) of iterations when
 99                         # the analytical Hessian is calculated
100tolerance = 6.055454452393343e-06 # float: the algorithm stops when this
101                                  # precision is reached
102max_iterations = 1000 # int: maximum number of iterations
103infeasible_cg = "False" # If True, the conjugate gradient algorithm may generate
104                        # infeasible solutions until termination.  The result
105                        # will then be projected on the feasible domain.  If
106                        # False, the algorithm stops as soon as an infeasible
107                        # iterate is generated
108initial_radius = 1 # Initial radius of the trust region
109steptol = 3.666852862501036e-11 # The algorithm stops when the relative change in
110                                # x is below this threshold. Basically, if p
111                                # significant digits of x are needed, steptol
112                                # should be set to 1.0e-p.
113enlarging_factor = 10 # If an iteration is very successful, the radius of the
114                      # trust region is multiplied by this factor
115