Configuration parameters

Biogeme can be configured using a parameter file. By default, the file is named biogeme.toml. If it does not exist, Biogeme creates one containing the default values.

Name

Description

Default

Section

Type

largest_neighborhood

int: size of the largest neighborhood considered 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

bayesian_draws

Number of draws per chain from the posterior distribution

2000

Bayesian

int

calculate_likelihood

Calculates likelihood-based statistics from the posterior draws

True

Bayesian

bool

calculate_loo

Calculates the Leave-One-Out Cross-Validation (LOO)

True

Bayesian

bool

calculate_waic

Calculates the Widely Applicable Information Criterion (WAIC)

False

Bayesian

bool

chains

Number of independent Markov chains to run in parallel.

4

Bayesian

int

mcmc_sampling_strategy

Defines how MCMC sampling is performed: ‘automatic’ (selected based on hardware), ‘numpyro-parallel’ (one chain per device), ‘numpyro-vectorized’ (all chains on one device), ‘pymc’ (default PyMC sampler on CPU)

automatic

Bayesian

str

sample_from_prior

bool: if “True”, samples from the prior distributions are generated. This may help in the diagnostic of indentification issues.

True

Bayesian

bool

target_accept

Target acceptance probability for the No-U-Turn Sampler (NUTS) algorithm. Higher values like 0.9 or 0.95 often work better for problematic posteriors.

0.9

Bayesian

float

warmup

Number of warm-up / burn-in iterations per chain that are used only to adapt the sampler, not to estimate the posterior.

2000

Bayesian

int

version

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

3.3.5

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

analytical_hessian_mode

Implementation of the analytical Hessian: full, chunked, or automatic. The compatibility default is full.

full

Estimation

str

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

hessian_memory_fraction

Maximum fraction of effective process memory allocated to analytical Hessian intermediates. Resource-manager limits, such as a Slurm memory allocation, are honored when available.

0.25

Estimation

float

hessian_observation_batch_size

Number of observations evaluated simultaneously by the chunked analytical Hessian.

100

Estimation

int

hessian_parameter_block_size

Number of parameter directions evaluated simultaneously by the chunked analytical Hessian.

4

Estimation

int

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

monte_carlo_diagnostic_auto

Run the post-estimation Monte Carlo draw-stability diagnostic automatically after estimate_or_load. Disabled by default.

False

MonteCarlo

bool

monte_carlo_diagnostic_draw_factors

Comma-separated factors applied to the estimation draw count for the post-estimation stability diagnostic.

0.25,0.5,1.0,2.0,4.0

MonteCarlo

str

monte_carlo_diagnostic_gradient_tolerance

Maximum infinity norm of the gradient discrepancy considered stable by the Monte Carlo diagnostic.

1e-05

MonteCarlo

float

monte_carlo_diagnostic_max_draws

Maximum number of draws in one diagnostic evaluation.

1000000

MonteCarlo

int

monte_carlo_diagnostic_minimum_level_factor

Minimum draw-count factor above the original count required for a conclusive stability result.

2.0

MonteCarlo

float

monte_carlo_diagnostic_objective_tolerance

Maximum absolute objective discrepancy considered stable by the Monte Carlo diagnostic.

0.001

MonteCarlo

float

monte_carlo_diagnostic_replications

Number of independent diagnostic draw designs per level.

2

MonteCarlo

int

monte_carlo_diagnostic_safety_factor

Safety multiplier applied to the forecast runtime of pending diagnostic evaluations.

1.5

MonteCarlo

float

monte_carlo_diagnostic_time_budget

Hard wall-clock budget in seconds for the draw-stability diagnostic.

1800

MonteCarlo

int

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_netcdf

bool: “True” if the netcdf file with the Bayesian estimation 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 prioritizes numerical stability over speed. Likelihood expressions use finite masks for unavailable alternatives and empty nests so that values and automatic derivatives remain finite.

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.5
  2# Automatically created on August 28, 2026. 11:53:34
  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[MonteCarlo]
  9number_of_draws = 10000 # int: Number of draws for Monte-Carlo integration.
 10monte_carlo_diagnostic_auto = "False" # Run the post-estimation Monte Carlo
 11                                      # draw-stability diagnostic automatically
 12                                      # after estimate_or_load. Disabled by
 13                                      # default.
 14monte_carlo_diagnostic_draw_factors = "0.25,0.5,1.0,2.0,4.0" # Comma-separated
 15                                                             # factors applied to
 16                                                             # the estimation
 17                                                             # draw count for the
 18                                                             # post-estimation
 19                                                             # stability
 20                                                             # diagnostic.
 21monte_carlo_diagnostic_replications = 2 # Number of independent diagnostic draw
 22                                        # designs per level.
 23monte_carlo_diagnostic_time_budget = 1800 # Hard wall-clock budget in seconds for
 24                                          # the draw-stability diagnostic.
 25monte_carlo_diagnostic_max_draws = 1000000 # Maximum number of draws in one
 26                                           # diagnostic evaluation.
 27monte_carlo_diagnostic_safety_factor = 1.5 # Safety multiplier applied to the
 28                                           # forecast runtime of pending
 29                                           # diagnostic evaluations.
 30monte_carlo_diagnostic_objective_tolerance = 0.001 # Maximum absolute objective
 31                                                   # discrepancy considered
 32                                                   # stable by the Monte Carlo
 33                                                   # diagnostic.
 34monte_carlo_diagnostic_gradient_tolerance = 1e-05 # Maximum infinity norm of the
 35                                                  # gradient discrepancy
 36                                                  # considered stable by the
 37                                                  # Monte Carlo diagnostic.
 38monte_carlo_diagnostic_minimum_level_factor = 2.0 # Minimum draw-count factor
 39                                                  # above the original count
 40                                                  # required for a conclusive
 41                                                  # stability result.
 42seed = 0 # int: Seed used for the pseudo-random number generation. It is useful
 43         # only when each run should generate the exact same result. If 0, a new
 44         # seed is used at each run.
 45
 46[Bayesian]
 47mcmc_sampling_strategy = "automatic" # Defines how MCMC sampling is performed:
 48                                     # 'automatic' (selected based on hardware),
 49                                     # 'numpyro-parallel' (one chain per device),
 50                                     # 'numpyro-vectorized' (all chains on one
 51                                     # device), 'pymc' (default PyMC sampler on
 52                                     # CPU)
 53sample_from_prior = "True" # bool: if "True", samples from the prior distributions
 54                           # are generated. This may help in the diagnostic of
 55                           # indentification issues.
 56bayesian_draws = 2000 # Number of draws per chain from the posterior distribution
 57warmup = 2000 # Number of warm-up / burn-in iterations per chain that are used
 58              # only to adapt the sampler, not to estimate the posterior.
 59chains = 4 # Number of independent Markov chains to run in parallel.
 60target_accept = 0.9 # Target acceptance probability for the No-U-Turn Sampler
 61                    # (NUTS) algorithm. Higher values like 0.9 or 0.95 often work
 62                    # better for problematic posteriors.
 63calculate_waic = "False" # Calculates the Widely Applicable Information Criterion
 64                         # (WAIC)
 65calculate_loo = "True" # Calculates the Leave-One-Out Cross-Validation (LOO)
 66calculate_likelihood = "True" # Calculates likelihood-based statistics from the
 67                              # posterior draws
 68
 69[Estimation]
 70bootstrap_samples = 100 # int: number of re-estimations for bootstrap sampling.
 71calculating_second_derivatives = "analytical" # Defines how to calculate the second
 72                                              # derivatives:
 73                                              # analytical,finite_differences,never.
 74                                              # 
 75analytical_hessian_mode = "full" # Implementation of the analytical Hessian: full,
 76                                 # chunked, or automatic. The compatibility
 77                                 # default is full.
 78hessian_parameter_block_size = 4 # Number of parameter directions evaluated
 79                                 # simultaneously by the chunked analytical
 80                                 # Hessian.
 81hessian_observation_batch_size = 100 # Number of observations evaluated
 82                                     # simultaneously by the chunked analytical
 83                                     # Hessian.
 84hessian_memory_fraction = 0.25 # Maximum fraction of effective process memory
 85                               # allocated to analytical Hessian intermediates.
 86                               # Resource-manager limits, such as a Slurm memory
 87                               # allocation, are honored when available.
 88large_data_set = 100000 # If the number of observations is larger than this
 89                        # value, the data set is deemed large, and the default
 90                        # estimation algorithm will not use second derivatives.
 91max_number_parameters_to_report = 15 # int: maximum number of parameters to
 92                                     # report during the estimation.
 93save_iterations = "True" # bool: If True, the current iterate is saved after each
 94                         # iteration, in a file named ``__[modelName].iter``,
 95                         # where ``[modelName]`` is the name given to the model.
 96                         # If such a file exists, the starting values for the
 97                         # estimation are replaced by the values saved in the
 98                         # file.
 99maximum_number_catalog_expressions = 100 # If the expression contains catalogs,
100                                         # the parameter sets an upper bound of
101                                         # the total number of possible
102                                         # combinations that can be estimated in
103                                         # the same loop.
104optimization_algorithm = "automatic" # str: optimization algorithm to be used for
105                                     # estimation. Valid values: ['automatic',
106                                     # 'scipy', 'LS-newton', 'TR-newton',
107                                     # 'LS-BFGS', 'TR-BFGS', 'simple_bounds',
108                                     # 'simple_bounds_newton',
109                                     # 'simple_bounds_BFGS']
110
111[SimpleBounds]
112second_derivatives = 1.0 # float: proportion (between 0 and 1) of iterations when
113                         # the analytical Hessian is calculated
114tolerance = 6.055454452393343e-06 # float: the algorithm stops when this
115                                  # precision is reached
116max_iterations = 1000 # int: maximum number of iterations
117infeasible_cg = "False" # If True, the conjugate gradient algorithm may generate
118                        # infeasible solutions until termination.  The result
119                        # will then be projected on the feasible domain.  If
120                        # False, the algorithm stops as soon as an infeasible
121                        # iterate is generated
122initial_radius = 1 # Initial radius of the trust region
123steptol = 3.666852862501036e-11 # The algorithm stops when the relative change in
124                                # x is below this threshold. Basically, if p
125                                # significant digits of x are needed, steptol
126                                # should be set to 1.0e-p.
127enlarging_factor = 10 # If an iteration is very successful, the radius of the
128                      # trust region is multiplied by this factor
129
130[AssistedSpecification]
131maximum_number_parameters = 50 # int: maximum number of parameters allowed in a
132                               # model. Each specification with a higher number
133                               # is deemed invalid and not estimated.
134number_of_neighbors = 20 # int: maximum number of neighbors that are visited by
135                         # the VNS algorithm.
136largest_neighborhood = 20 # int: size of the largest neighborhood considered by
137                          # the Variable Neighborhood Search (VNS) algorithm.
138maximum_attempts = 100 # int: an attempts consists in selecting a solution in the
139                       # Pareto set, and trying to improve it. The parameter
140                       # imposes an upper bound on the total number of attempts,
141                       # irrespectively if they are successful or not.
142
143[MultiThreading]
144number_of_threads = 0 # int: Number of threads/processors to be used. If the
145                      # parameter is 0, the number of available threads is
146                      # calculated using cpu_count().
147
148[Output]
149identification_threshold = 1e-05 # float: if the smallest eigenvalue of the
150                                 # second derivative matrix is lesser or equal to
151                                 # this parameter, the model is considered not
152                                 # identified. The corresponding eigenvector is
153                                 # then reported to identify the parameters
154                                 # involved in the issue.
155only_robust_stats = "True" # bool: "True" if only the robust statistics need to be
156                           # reported. If "False", the statistics from the
157                           # Rao-Cramer bound are also reported.
158generate_html = "True" # bool: "True" if the HTML file with the results must be
159                       # generated.
160generate_yaml = "True" # bool: "True" if the yaml file with the results must be
161                       # generated.
162generate_netcdf = "True" # bool: "True" if the netcdf file with the Bayesian
163                         # estimation results must be generated.
164save_validation_results = "True" # bool: "True" if the validation results are saved
165                                 # in CSV files.
166
167[Biogeme]
168version = "3.3.5" # Version of Biogeme that created the TOML file. Do not modify
169                  # this value.
170
171[TrustRegion]
172dogleg = "True" # bool: choice of the method to solve the trust region subproblem.
173                # True: dogleg. False: truncated conjugate gradient.
174
175[Specification]
176missing_data = 99999 # number: If one variable has this value, it is assumed that
177                     # a data is missing and an exception will be triggered.
178numerically_safe = "False" # If true, Biogeme prioritizes numerical stability over
179                           # speed. Likelihood expressions use finite masks for
180                           # unavailable alternatives and empty nests so that
181                           # values and automatic derivatives remain finite.
182use_jit = "True" # If True, the model is compiled using jit (just-in-time) to speed
183                 # up the calculation. For complex models, compilation time may
184                 # exceed the gain due to compilation, so that it is worth
185                 # turning it off.
186