Table of contents
To get Flow running, you need three things: Flow,
SUMO, and (recommended to explore the full suite of Flow’s capabilities) a reinforcement learning library (RLlib). If you wish to use Flow with the traffic simulator Aimsun, this can be achieved by following the setup instructions under the “Installing Aimsun” subsection. If you choose not to install a reinforcement learning library, you will still be able to build and run SUMO-only traffic tasks, but will not be able to run experiments which require learning agents. Once each component is installed successfully, you might get some missing module bugs from Python. Just install the missing module using your OS-specific package manager / installation tool. Follow the shell commands below to get started.
In this section we install Flow as well as the binaries and packages needed to support the traffic simulator used in modeling the dynamics of traffic networks: SUMO.
If you have not done so already, download the Flow github repository.
git clone https://github.com/flow-project/flow.git cd flow
We begin by creating a conda environment and installing Flow and its
dependencies within the environment. This can be done by running the below
script. Be sure to run the below commands from
# create a conda environment conda env create -f environment.yml conda activate flow python setup.py develop
If the conda install fails, you can also install the requirements using pip by calling
# install flow within the environment pip install -e .
Next, we install the necessary pre-compiled SUMO binaries and python tools. In order to install everything you will need from SUMO, run one of the below scripts from the Flow main directory. Choose the script that matches the operating system you are running.
For Ubuntu 14.04:
For Ubuntu 16.04:
For Ubuntu 18.04:
If you are using an unsupported operating system (e.g. Arch Linux), or the binaries provided by the above scripts are not compatible with your machine, you will have to personally build the SUMO binary files. For more, please see (Optional) Direct install of SUMO from GitHub or refer to SUMO’s documentation.
WARNING: Flow is not currently compatible with the most up-to-date version of SUMO.
Finally, test your SUMO install and version by running the following commands.
which sumo sumo --version sumo-gui
Note that, if the above commands did not work, you may need to run
source ~/.bashrc or open a new terminal to update your $PATH variable.
If you are a Mac user and the above command gives you the error
FXApp:openDisplay: unable to open display :0.0, make sure to open the application XQuartz.
Once the above modules have been successfully installed, we can test the installation by running a few examples. Before trying to run any examples, be sure to enter your conda environment by typing:
conda activate flow
Let’s see some traffic action:
Running the following should result in the loading of the SUMO GUI. Click the run button and you should see unstable traffic form after a few seconds, a la (Sugiyama et al, 2008). This means that you have Flow properly configured with SUMO and Flow!
In addition to SUMO, Flow supports the use of the traffic simulator “Aimsun”. In order setup Flow with Aimsun, you will first need to install Aimsun. This can be achieved by following the installation instructions located in: https://www.aimsun.com/aimsun-next/download/.
Once Aimsun has been installed, copy the path to the Aimsun_Next main directory and place it in under the AIMSUN_NEXT_PATH variable in your bashrc. This will allow Flow to locate and use this binary during the execution of various tasks. The path should look something like:
export AIMSUN_NEXT_PATH="/home/user/Aimsun_Next_X_Y_Z/" # Linux export AIMSUN_NEXT_PATH="/Applications/Aimsun Next.app/Contents/MacOS/" # OS X
Note for Mac users: when you download Aimsun, you will get a folder named “Programming”. You need to rename it to “programming” (all lowercase) and to move it inside the “Aimsun Next.app/Contents/MacOS/” directory so that the python API can work.
In addition, being that Aimsun’s python API is written to support Python 2.7.4, we will need to create a Python 2.7.4 conda environment that Aimsun can refer to when executing commands. In order to do so, run the following script from the Flow main directory:
You can then verify that the above command has successfully installed the required conda env by typing:
source activate aimsun_flow which python
Important note: For running Aimsun experiments, the flow environment should be used, NOT the aimsun_flow environment that was just created. The latter command should return an output similar to:
Copy the path up until right before /lib (i.e. /path/to/envs/aimsun_flow) and place it under the AIMSUN_SITEPACKAGES variable in your bashrc, like this:
To test that you installation was successful, you can try running one of the Aimsun examples within the Flow main directory. In order to do so, you need to activate the flow env. Type:
source deactivate aimsun_flow source activate flow python examples/aimsun/sugiyama.py
Troubleshootig for Ubuntu users with Aimsun 8.4: when you run the above example, you may get a subprocess.Popen error
OSError: [Errno 8] Exec format error:.
To fix this, go to the Aimsun Next main directory, open the Aimsun_Next binary with a text editor and add the shebang to the first line of the script
Flow has been tested on a variety of RL libraries, the installation of which is optional but may be of use when trying to execute some of the examples files located in Flow. RLlib is one such library. First visit <https://github.com/flow-project/ray/blob/master/doc/source/installation.rst> and install the required packages.
If you are not intending to develop RL algorithms or customize rllib you don’t need to do anything, Ray was installed when you created the conda environment.
If you are intending to modify Ray, the installation process for this library is as follows:
cd ~ git clone https://github.com/flow-project/ray.git cd ray/python/ python setup.py develop
If missing libraries cause errors, please also install additional required libraries as specified at <http://ray.readthedocs.io/en/latest/installation.html> and then follow the setup instructions.
An additional library that Flow supports is the fork of OpenAI’s Baselines, Stable-Baselines. First visit <https://stable-baselines.readthedocs.io/en/master/guide/install.html> and install the required packages and pip install the stable baselines package as described in their installation instructions.
You can test your installation by running
See getting started with RLlib for sample commands.
To run any of the RL examples, make sure to run
conda activate flow
In order to test run an Flow experiment in RLlib, try the following command:
If it does not fail, this means that you have Flow properly configured with RLlib.
To visualize the training progress:
If tensorboard is not installed, you can install with pip:
pip install tensorboard
For information on how to deploy a cluster, refer to the Ray instructions. The basic workflow is running the following locally, ssh-ing into the host machine, and starting jobs from there.
pip install boto3 ray create-or-update scripts/ray_autoscale.yaml ray teardown scripts/ray_autoscale.yaml
The below commands walk you through installing and building SUMO locally. Note that if this does not work, you are recommended to point an issue on the flow-dev message board or refer to SUMO’s documentation regarding installing their software.
We begin by downloading SUMO’s github directory:
cd ~ git clone https://github.com/eclipse/sumo.git cd sumo git checkout 2147d155b1 make -f Makefile.cvs
If you have OSX, run the following commands. If you don’t have brew you can find installation instructions at <https://docs.brew.sh/Installation>
Alternatively, the following segment of installation instructions is also compatible with OSX installation, following the brew updates and installations shown below. <https://sumo.dlr.de/wiki/Installing/Linux_Build#Building_the_SUMO_binaries_with_cmake_.28recommended.29>
brew update brew install Caskroom/cask/xquartz brew install autoconf brew install automake brew install pkg-config brew install libtool brew install gdal brew install proj brew install xerces-c brew install fox export CPPFLAGS=-I/opt/X11/include export LDFLAGS=-L/opt/X11/lib ./configure CXX=clang++ CXXFLAGS="-stdlib=libc++ -std=gnu++11" --with-xerces=/usr/local --with-proj-gdal=/usr/local make -j$nproc echo 'export SUMO_HOME="$HOME/sumo"' >> ~/.bash_profile echo 'export PATH="$HOME/sumo/bin:$PATH"' >> ~/.bash_profile echo 'export PYTHONPATH="$HOME/sumo/tools:$PYTHONPATH"' >> ~/.bash_profile source ~/.bash_profile
If you have Ubuntu 14.04+, run the following command
./configure make -j$nproc echo 'export SUMO_HOME="$HOME/sumo"' >> ~/.bashrc echo 'export PATH="$HOME/sumo/bin:$PATH"' >> ~/.bashrc echo 'export PYTHONPATH="$HOME/sumo/tools:$PYTHONPATH"' >> ~/.bashrc source ~/.bashrc
To install a containerized Flow stack, run:
docker run -d -p 5901:5901 -p 6901:6901 fywu85/flow-desktop:latest
To access the docker container, go to the following URL and enter the default password password:
To use the Jupyter Notebook inside the container, run:
jupyter notebook --ip=127.0.0.1