Simulation Mechanism: Summary
=============================

In this page, we briefly explain the models and logics behind UXsim.
If you want to know more details, please refer to `arXiv preprint on UXsim <https://arxiv.org/pdf/2309.17114.pdf>`_, the code, the original articles, or  `Japanese textbook on traffic simulation <https://www.coronasha.co.jp/np/isbn/9784339052794/>`_.

Models
------

UXsim computes network traffic flow dynamics by combining following models:

* The mesoscopic version of `Newell's simplified car-following model <https://doi.org/10.1016/S0191-2615(00)00044-8>`_ (aka. `X-model <https://doi.org/10.1016/j.trb.2013.02.008>`_) for link and vehicle dynamics.
* The `mesoscopic version of the incremental node model <https://www.ubiquitypress.com/site/chapters/10.5334/baw.50/download/1518/>`_ for inter-link transfer at nodes.
* `Dynamic user optimum <https://doi.org/10.1016/S0191-2615(00)00005-9>`_ (aka. reactive assignment) with stochasticity and delay for route choice of travelers.

Key Inputs
----------

UXsim's key inputs (i.e., simulation scenario parameters) are as follows:

* Reaction time of vehicles (`reaction_time` argument of `World`). This value determines the simulation time step width. This is a global parameter.
* Platoon size for mesoscopic simulation (`deltan` of `World`). This value determines the simulation time step width. This is a global parameter.
* Route choice model parameters: shortest path update interval (`duo_update_time` of `World`) and weight value (`duo_update_weight` of `World`).
* Lists of nodes and links. They define the network structure.
* Parameters of each link. For example, length, free flow speed (`free_flow_speed`), number of lanes (`number_of_lanes`), jam density (`jam_density`), merging priority parameter (`merge_priority`), and traffic signal setting (`signal_group`).
* Parameters of each node. For example, position (`x` and `y`) and traffic signal setting (`signal`).
* Demand. For example, origin, destination, and departure time of each vehicle are specified.

Program Structure
-----------------

Class diagram of UXsim: the relationship between classes and their key properties.

.. image:: img/class_diagram.png

Computation Procedure
---------------------

Activity diagram of UXsim: the overall computation procedure of UXsim.

.. image:: img/activity_diagram.png

Activity diagram of a specific vehicle in UXsim: the computation procedure for each vehicle.

.. image:: img/activity_diagram_veh.png


Traffic Flow Model Parameters
-----------------------------

The following parameters are used in UXsim, defined through `Link`, `World`, and `Node` (\*: input, \*\*: alternative input).
If you are not familiar with the traffic flow theory, it is recommended that you adjust only ``free_flow_speed`` and ``number_of_lanes`` for the traffic flow model parameters, leaving the other parameters at their default values.

- \* ``free_flow_speed`` (m/s)
- \* ``jam_density`` (veh/m/LINK)
- \*\* ``jam_density_per_lane`` (veh/m/lane)
- \* ``lanes``, ``number_of_lane`` (lane)
- ``tau``: y-intercept of link FD (s/veh\*LINK)
- ``REACTION_TIME`` (s/veh\*lane)
- ``w`` (m/s)
- ``capacity`` (veh/s/LINK)
- ``capacity_per_lane`` (veh/s/lane)
- ``delta``: minimum spacing (m/veh\*LINK)
- ``delta_per_lane``: minimum spacing in lane (m/veh\*lane)
- ``q_star``: capacity (veh/s/LINK)
- ``k_star``: critical density (veh/s/LINK)
- \* ``capacity_in``, ``capacity_out``: bottleneck capacity at beginning/end of link (veh/s/LINK)
- \* ``Node.flow_capacity``: node flow capacity (veh/s/LINK-LIKE)

.. image:: img/fundamental_diagram.png