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