.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/tutorials/plot_b02_parameters.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_tutorials_plot_b02_parameters.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_tutorials_plot_b02_parameters.py:


Configuring Biogeme with parameters
===================================

We illustrate how to obtain information about configuration parameters, and how to modify them.

:author: Michel Bierlaire, EPFL
:date: Thu May 16 13:24:56 2024

.. GENERATED FROM PYTHON SOURCE LINES 12-25

.. code-block:: Python


    import os

    import pandas as pd

    import biogeme.biogeme_logging as blog
    from biogeme.biogeme import BIOGEME
    from biogeme.database import Database
    from biogeme.expressions import Beta

    logger = blog.get_screen_logger(level=blog.INFO)
    logger.info('Illustration of the definition of parameters')





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Illustration of the definition of parameters 




.. GENERATED FROM PYTHON SOURCE LINES 26-28

Biogeme accepts several parameters that modifies its functionalities. In this example, we illustrate
how to obtain information about those parameters, and how to modify them.

.. GENERATED FROM PYTHON SOURCE LINES 30-31

We first create a dummy dataset that is needed to create the Biogeme object. Its content is irrelevant.

.. GENERATED FROM PYTHON SOURCE LINES 31-37

.. code-block:: Python

    data = {
        'x1': pd.Series([0]),
    }
    pandas_dataframe = pd.DataFrame(data)
    biogeme_database = Database('dummy', pandas_dataframe)








.. GENERATED FROM PYTHON SOURCE LINES 38-39

We also create a dummy model, irrelevant as well.

.. GENERATED FROM PYTHON SOURCE LINES 39-41

.. code-block:: Python

    logprob = Beta('dummy_parameter', 0, None, None, 0)








.. GENERATED FROM PYTHON SOURCE LINES 42-44

When you create the Biogeme model, Biogeme tries to read the values of the parameters
from the file `biogeme.toml`. If the file does not exist, default values are used.

.. GENERATED FROM PYTHON SOURCE LINES 44-46

.. code-block:: Python

    biogeme_object = BIOGEME(database=biogeme_database, formulas=logprob)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Biogeme parameters read from biogeme.toml. 




.. GENERATED FROM PYTHON SOURCE LINES 47-48

For instance, let's check the value for the maximum number of iterations:

.. GENERATED FROM PYTHON SOURCE LINES 48-50

.. code-block:: Python

    print(f'Max. number of iterations: {biogeme_object.max_iterations}')





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Max. number of iterations: 1000




.. GENERATED FROM PYTHON SOURCE LINES 51-52

If it did not exist before, Biogeme has created a file called `biogeme.toml`.

.. GENERATED FROM PYTHON SOURCE LINES 52-56

.. code-block:: Python

    default_toml_file_name = 'biogeme.toml'
    with open(default_toml_file_name, 'r') as file:
        lines = file.readlines()








.. GENERATED FROM PYTHON SOURCE LINES 57-59

Here are the first lines of this file. As you see, it is structured into sections. Each section contains
a list of parameters, their value, and a short description.

.. GENERATED FROM PYTHON SOURCE LINES 59-65

.. code-block:: Python

    number_of_lines_to_display = 20
    for i, line in enumerate(lines):
        print(line, end='')
        if i == number_of_lines_to_display:
            break





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    # Default parameter file for Biogeme 3.2.14
    # Automatically created on August 05, 2024. 20:44:17

    [Specification]
    missing_data = 99999 # number: If one variable has this value, it is assumed that
                         # a data is missing and an exception will be triggered.

    [SimpleBounds]
    second_derivatives = 1.0 # float: proportion (between 0 and 1) of iterations when
                             # the analytical Hessian is calculated
    tolerance = 0.0001220703125 # float: the algorithm stops when this precision is
                                # reached
    max_iterations = 1000 # int: maximum number of iterations
    infeasible_cg = "False" # 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
    initial_radius = 1 # Initial radius of the trust region
    steptol = 1e-05 # The algorithm stops when the relative change in x is below this
                    # threshold. Basically, if p significant digits of x are needed,




.. GENERATED FROM PYTHON SOURCE LINES 66-67

Let's now replace the value of a parameter in the file by 500.

.. GENERATED FROM PYTHON SOURCE LINES 67-74

.. code-block:: Python

    for i, line in enumerate(lines):
        if 'max_iterations' in line:
            lines[i] = 'max_iterations = 500\n'

    with open(default_toml_file_name, 'w') as file:
        file.writelines(lines)








.. GENERATED FROM PYTHON SOURCE LINES 75-77

We create a new Biogeme object. The values of the parameters are read from
the file `biogeme.toml`.

.. GENERATED FROM PYTHON SOURCE LINES 77-79

.. code-block:: Python

    biogeme_object = BIOGEME(database=biogeme_database, formulas=logprob)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Biogeme parameters read from biogeme.toml. 




.. GENERATED FROM PYTHON SOURCE LINES 80-81

We check that the value 500 that we have specified has indeed been considered.

.. GENERATED FROM PYTHON SOURCE LINES 81-83

.. code-block:: Python

    print(f'Max. number of iterations: {biogeme_object.max_iterations}')





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Max. number of iterations: 500




.. GENERATED FROM PYTHON SOURCE LINES 84-86

It is possible to have several toml files, with different configurations. For instance, let's create another
file with a different value for the `max_iterations` parameter: 650.

.. GENERATED FROM PYTHON SOURCE LINES 86-94

.. code-block:: Python

    another_toml_file_name = 'customized.toml'
    new_value = 650
    for i, line in enumerate(lines):
        if 'max_iterations' in line:
            lines[i] = f'max_iterations = {new_value}\n'
    with open(another_toml_file_name, 'w') as file:
        file.writelines(lines)








.. GENERATED FROM PYTHON SOURCE LINES 95-96

The name of the file must now be specified at the creation of the Biogeme object.

.. GENERATED FROM PYTHON SOURCE LINES 96-101

.. code-block:: Python

    biogeme_object = BIOGEME(
        database=biogeme_database, formulas=logprob, parameters=another_toml_file_name
    )
    print(f'Max. number of iterations: {biogeme_object.max_iterations}')





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Biogeme parameters read from customized.toml. 
    Max. number of iterations: 650




.. GENERATED FROM PYTHON SOURCE LINES 102-104

Note that if you specify the name of a file that does not exist, this file will be created, and the default value
of the parameters used.

.. GENERATED FROM PYTHON SOURCE LINES 104-110

.. code-block:: Python

    yet_another_toml_file_name = 'xxx.toml'
    biogeme_object = BIOGEME(
        database=biogeme_database, formulas=logprob, parameters=yet_another_toml_file_name
    )
    print(f'Max. number of iterations: {biogeme_object.max_iterations}')





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Default values of the Biogeme parameters are used. 
    File xxx.toml has been created 
    Max. number of iterations: 1000




.. GENERATED FROM PYTHON SOURCE LINES 111-113

Another way to set the value of a parameter is to specify it explicitly at the creation of the Biogeme object.
It supersedes the value in the .toml file.

.. GENERATED FROM PYTHON SOURCE LINES 113-119

.. code-block:: Python

    yet_another_value = 234
    biogeme_object = BIOGEME(
        database=biogeme_database, formulas=logprob, max_iterations=yet_another_value
    )
    print(f'Max. number of iterations: {biogeme_object.max_iterations}')





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Biogeme parameters read from biogeme.toml. 
    Max. number of iterations: 234




.. GENERATED FROM PYTHON SOURCE LINES 120-121

Both can be combined.

.. GENERATED FROM PYTHON SOURCE LINES 121-128

.. code-block:: Python

    biogeme_object = BIOGEME(
        database=biogeme_database,
        formulas=logprob,
        max_iterations=234,
        parameters=another_toml_file_name,
    )
    print(f'Max. number of iterations: {biogeme_object.max_iterations}')




.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Biogeme parameters read from customized.toml. 
    Max. number of iterations: 234




.. GENERATED FROM PYTHON SOURCE LINES 129-130

We delete the toml files to clean the directory.

.. GENERATED FROM PYTHON SOURCE LINES 130-133

.. code-block:: Python

    os.remove(default_toml_file_name)
    os.remove(another_toml_file_name)
    os.remove(yet_another_toml_file_name)








.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.035 seconds)


.. _sphx_glr_download_auto_examples_tutorials_plot_b02_parameters.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_b02_parameters.ipynb <plot_b02_parameters.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_b02_parameters.py <plot_b02_parameters.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_b02_parameters.zip <plot_b02_parameters.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_