Sumo comes with a Python interface to its numerical engine. It is located under the installation folder (after installing the DTT addon):
<Sumo install path>/PythonAPI/dynamita
There are various ways to use the Python interface or API in custom Python applications.
The easiest way to use the interface is to copy the dynamita folder from the installation folder to the location of the custom Python application.
Let's say, the custom project is in the C:/Users/username/My Sumo simulation folder. Simply copy the dynamita folder from the Sumo install folder to this custom application folder; it will look like:
C:/Users/username/My Sumo simulation/dynamita
Every Python script located in the custom folder will be able to import the API like this:
import dynamita.scheduler as ds
import dynamita.tool as dtool
One drawback of this method is that if there are multiple Python projects in different folders, we must copy the API into each project. If the API changes we need to update all custom projects using the API.
This also can be an advantage if different projects need different versions of the API.
PYTHONPATH environment variableWe describe the simplest case of setting the environment varable in a command prompt window. Various editors or integrated development environments (IDE) may have other ways to set this variable.
Open a command prompt window by pressing the Windows button on the keyboard then type cmd and Enter. In the command window type:
set PYTHONPATH=<Sumo install path>/PythonAPI
where <Sumo install path> needs to be replaced to the actual path. Running scripts in this window they can access the API from the Sumo install folder; no need to copy. One drawback, or for some users advantage, is that every Python project is tied to one version of the API.
This is the safest, but most tedious way to set up the Sumo Python interface. The Python documentation contains examples how to create virtual environments.
In a virtual environment we can install the interface package with the usual pip install command. We can create multiple virtual environments for various Python and Sumo API versions and work safely in these environments.
In this scenario the Sumo Python interface is packaged in a so called Python Wheel file in the following format: dynamita-V.M.m-py3-none-any.whl, which can be installed with pip like:
pip install dynamita-V.M.m-py3-none-any.whl
The V.M.m part shows the version of Sumo, where V is the version number, M is the major revision and m is the minor revision number. At the moment the package should be requested from Dynamita S.A.R.L. separately, and may look like dynamita-24.0.0-py3-none-any.whl containing the actual Sumo version. Older or newer versions of Sumo may contain different version numbers.
On Linux systems Python is part of the operating system and we may not want to modify anything in that Python version. We can create a virtual Python environment following the Python documentation, to separate our workspace from the default OS Python.
After activating the virtual environment we can set the PYTHONPATH variable with the following command:
set PYTHONPATH=<Sumo Install path>/PythonAPIexport PYTHONPATH=<Python API path>