.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "_auto_examples/run_module/plot_run_module.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_run_module_plot_run_module.py>`
        to download the full example code.

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

.. _sphx_glr__auto_examples_run_module_plot_run_module.py:


.. _run_module_example:

Run module
==========

In this example we demonstrate how to use AequilibraE's run module using Sioux Falls example.

.. GENERATED FROM PYTHON SOURCE LINES 11-15

.. admonition:: References

  * :doc:`../../run_module`
  * :ref:`parameters_run`

.. GENERATED FROM PYTHON SOURCE LINES 17-21

.. seealso::
    Several functions, methods, classes and modules are used in this example:

    * :attr:`aequilibrae.project.Project.run`

.. GENERATED FROM PYTHON SOURCE LINES 23-32

.. code-block:: Python


    # Imports
    from uuid import uuid4
    from tempfile import gettempdir
    from os.path import join

    from aequilibrae.parameters import Parameters
    from aequilibrae.utils.create_example import create_example








.. GENERATED FROM PYTHON SOURCE LINES 34-40

.. code-block:: Python


    # Let's create the Sioux Falls example in an arbitrary folder.
    folder = join(gettempdir(), uuid4().hex)

    project = create_example(folder)








.. GENERATED FROM PYTHON SOURCE LINES 41-46

First, let's check the matrix information using ``matrix_summary()``. This method
provides us useful information such as the matrix total, minimum and maximum values
in the array, and the number of non-empty pairs in the matrix.

Notice that the matrix summary is presented for each matrix core.

.. GENERATED FROM PYTHON SOURCE LINES 46-48

.. code-block:: Python

    project.run.matrix_summary()





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

 .. code-block:: none


    {'demand_omx': {'matrix': {'total': 360600.0, 'min': 0.0, 'max': 4400.0, 'nnz': 528}}, 'demand_mc': {'car': {'total': 271266.6324170904, 'min': 0.0, 'max': 3414.160702028352, 'nnz': 528}, 'motorcycle': {'total': 89819.0708124364, 'min': 0.0, 'max': 1237.9652821904103, 'nnz': 528}, 'trucks': {'total': 90235.57459796841, 'min': 0.0, 'max': 1318.3068496025667, 'nnz': 528}}, 'skims': {'distance_blended': {'total': 6725.294972629576, 'min': 0.0, 'max': 27.000048290421308, 'nnz': 552}, 'time_final': {'total': 13600.90095750823, 'min': 0.0, 'max': 46.66452630996126, 'nnz': 552}}, 'demand_aem': {'matrix': {'total': 360600.0, 'min': 0.0, 'max': 4400.0, 'nnz': 528}}}



.. GENERATED FROM PYTHON SOURCE LINES 49-51

If our matrices folder is empty, instead of a nested dictionary of data,
AequilibraE run would return an empty dictionary.

.. GENERATED FROM PYTHON SOURCE LINES 53-54

Let's create a graph for mode `car`.

.. GENERATED FROM PYTHON SOURCE LINES 54-56

.. code-block:: Python

    mode = "c"








.. GENERATED FROM PYTHON SOURCE LINES 57-64

.. code-block:: Python

    network = project.network
    network.build_graphs(modes=[mode])
    graph = network.graphs[mode]
    graph.set_graph("distance")
    graph.set_skimming("distance")
    graph.set_blocked_centroid_flows(False)








.. GENERATED FROM PYTHON SOURCE LINES 65-68

With the method ``graph_summary()``, we can check the total number of links, nodes, and zones,
as well as the compact number of links and nodes used for computation. If we had more than
one graph, its information would be displayed within the nested dictionary.

.. GENERATED FROM PYTHON SOURCE LINES 68-71

.. code-block:: Python


    project.run.graph_summary()





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

 .. code-block:: none


    {'c': {'num_links': 76, 'num_nodes': 24, 'num_zones': 24, 'compact_num_links': 76, 'compact_num_nodes': 24}}



.. GENERATED FROM PYTHON SOURCE LINES 72-73

If no graphs have been built, an empty dictionary will be returned.

.. GENERATED FROM PYTHON SOURCE LINES 75-78

Let's add a ``create_delaunay`` function to our ``run/__init__.py`` file.

This function replicates the example in which we :ref:`create Delaunay lines <creating_delaunay_lines>`.

.. GENERATED FROM PYTHON SOURCE LINES 78-90

.. code-block:: Python

    func_string = """
    def create_delaunay(source: str, name: str, computational_view: str, result_name: str, overwrite: bool=False):\n
    \tfrom aequilibrae.utils.create_delaunay_network import DelaunayAnalysis\n
    \tproject = get_active_project()\n
    \tmatrix = project.matrices\n
    \tmat = matrix.get_matrix(name)\n
    \tmat.computational_view(computational_view)\n
    \tda = DelaunayAnalysis(project)\n
    \tda.create_network(source, overwrite)\n
    \tda.assign_matrix(mat, result_name)\n
    """








.. GENERATED FROM PYTHON SOURCE LINES 91-95

.. code-block:: Python

    with open(join(folder, "run", "__init__.py"), "a") as file:
        file.write("\n")
        file.write(func_string)








.. GENERATED FROM PYTHON SOURCE LINES 96-97

Now we add new parameters to our model

.. GENERATED FROM PYTHON SOURCE LINES 97-106

.. code-block:: Python


    p = Parameters(project)
    p.parameters["run"]["create_delaunay"] = {}
    p.parameters["run"]["create_delaunay"]["source"] = "zones"
    p.parameters["run"]["create_delaunay"]["name"] = "demand_omx"
    p.parameters["run"]["create_delaunay"]["computational_view"] = "matrix"
    p.parameters["run"]["create_delaunay"]["result_name"] = "my_run_module_example"
    p.write_back()








.. GENERATED FROM PYTHON SOURCE LINES 107-108

And we run the function

.. GENERATED FROM PYTHON SOURCE LINES 108-110

.. code-block:: Python

    project.run.create_delaunay()





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

 .. code-block:: none


    delaunay                                          :   0%|          | 0/24 [00:00<?, ?it/s]
    Equilibrium Assignment                            :   0%|          | 0/250 [00:00<?, ?it/s]
    All-or-Nothing - Traffic Class: delaunay          :   0%|          | 1/250 [00:00<00:00, 39945.75it/s]
    All-or-Nothing - Traffic Class: delaunay          :   0%|          | 1/250 [00:00<00:00, 7319.90it/s] 
    All-or-Nothing - Traffic Class: delaunay          :   0%|          | 0/250 [00:00<?, ?it/s]          
    All-or-Nothing - Traffic Class: delaunay - Zones: 0/24:   0%|          | 0/250 [00:00<?, ?it/s]
    All-or-Nothing - Traffic Class: delaunay - Zones: 10/24:   0%|          | 0/250 [00:00<?, ?it/s]
    All-or-Nothing - Traffic Class: delaunay - Zones: 20/24:   0%|          | 0/250 [00:00<?, ?it/s]
    All-or-Nothing - Traffic Class: delaunay - Zones: 24/24:   0%|          | 0/250 [00:00<?, ?it/s]
                                                                                                



.. GENERATED FROM PYTHON SOURCE LINES 111-117

.. note::

   To run the ``create_delaunay`` function we created above without argument
   values, we must insert the values as a project parameter. Adding an unused
   parameter to the ``parameters.yml`` file will raise an execution error.


.. GENERATED FROM PYTHON SOURCE LINES 119-122

Creating Delaunay lines also creates a ``results_database.sqlite`` that contains the
result of the all-or-nothing algorithim that generated the output. We can check
the existing results in the results_database using the ``results_summary`` method.

.. GENERATED FROM PYTHON SOURCE LINES 122-124

.. code-block:: Python

    project.run.results_summary()






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>table_name</th>
          <th>procedure</th>
          <th>procedure_id</th>
          <th>procedure_report</th>
          <th>timestamp</th>
          <th>description</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>my_run_module_example</td>
          <td>Delaunay assignment</td>
          <td>adf32361ed6c421d91e25851f1647602</td>
          <td>{'setup': "{'Algorithm': 'all-or-nothing', 'Cl...</td>
          <td>2025-06-17 01:07:07.003981</td>
          <td></td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 125-126

Let's check what our Delaunay lines look like!

.. GENERATED FROM PYTHON SOURCE LINES 126-131

.. code-block:: Python


    import sqlite3
    import pandas as pd
    import geopandas as gpd








.. GENERATED FROM PYTHON SOURCE LINES 132-133

Let's retrieve the results

.. GENERATED FROM PYTHON SOURCE LINES 133-138

.. code-block:: Python

    res_path = join(project.project_base_path, "results_database.sqlite")
    conn = sqlite3.connect(res_path)

    results = pd.read_sql("SELECT * FROM my_run_module_example", conn).set_index("link_id")








.. GENERATED FROM PYTHON SOURCE LINES 139-145

.. code-block:: Python

    with project.db_connection as conn:
        links = gpd.read_postgis(
            "SELECT link_id, st_asBinary(geometry) geometry FROM delaunay_network", conn, geom_col="geometry", crs=4326
        )
    links.set_index("link_id", inplace=True)








.. GENERATED FROM PYTHON SOURCE LINES 146-149

.. code-block:: Python

    df = links.join(results)
    max_vol = df.matrix_tot.max()








.. GENERATED FROM PYTHON SOURCE LINES 150-151

And finally plot the data

.. GENERATED FROM PYTHON SOURCE LINES 151-153

.. code-block:: Python

    df.plot(linewidth=5 * df["matrix_tot"] / max_vol, color="blue")




.. image-sg:: /_auto_examples/run_module/images/sphx_glr_plot_run_module_001.png
   :alt: plot run module
   :srcset: /_auto_examples/run_module/images/sphx_glr_plot_run_module_001.png
   :class: sphx-glr-single-img


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

 .. code-block:: none


    <Axes: >



.. GENERATED FROM PYTHON SOURCE LINES 154-156

.. code-block:: Python

    project.close()








.. GENERATED FROM PYTHON SOURCE LINES 157-159

Pipeline image credits to
`Data-pipeline icons created by Vectors Tank - Flaticon <https://www.flaticon.com/free-icons/data-pipeline>`_


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

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


.. _sphx_glr_download__auto_examples_run_module_plot_run_module.py:

.. only:: html

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

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

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

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

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

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

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


.. only:: html

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

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