2. Installation¶
2.1. Requirements¶
- System
EMULSION has been designed under MacOS and Linux, and works (with minor limitations) with Windows 10. See the installation procedure specific to your system.
Also, in what follows, we assume that MacOS and Linux users are working with a bash shell. If you are not sure, typing:
echo $SHELL
in a terminal should print/bin/bash
. Otherwise, please refer to the documentation of your shell to adapt the commands below.- Language
EMULSION is written in Python 3 (version 3.6 or higher). In what follows, we assume that
python3
andpip3
refer to your Python3 installation. If not, replace them by your own configuration in the commands below (e.g. with Windows: respectivelypython.exe
andpip.exe
).To install Python on your system, please consult Python website. When installing on Windows, check the box “Add Python 3.x to PATH” to make python commands available from the terminal.
2.2. Install with pip
(recommended)¶
Linux and MacOS:¶
sudo pip3 install emulsion
init_emulsion
source $HOME/.bashrc
Depending on how you installed Python, sudo
is sometimes
optional.
The second command (init_emulsion
) initializes command-line
completion (available with a bash shell, under Linux or MacOS), which allows
to use TAB
key to get suggestions on what is expected (options,
files, parameters…) in the command. It also creates (or modifies)
the environment variable named PYTHONPATH
to make EMULSION able to
find code add-ons located in the same directory as your models.
EMULSION documentation is provided on-line.
Windows¶
Open a terminal (“Command Prompt” or “Windows Power Shell”), then type:
pip.exe install emulsion
To make EMULSION able to find code add-ons in the directory where your model
files are located, you must declare (or modify) an environment
variable named PYTHONPATH
to add the current directory (“.
”).
To do so, you can use the graphical interface (from System Preferences), or the terminal. The syntax depends on the kind of terminal you are using:
with the “Command Prompt” (
cmd.exe
), type:setx PYTHONPATH ".;%PYTHONPATH%"with “Windows Power Shell”, type:
setx PYTHONPATH ".;$Env:PYTHONPATH"
2.3. Install third-party software¶
Graphviz is highly recommended (otherwise, simulations will run but you will not be able to get the nice diagrams representing model structure).
Linux¶
sudo apt install graphviz
Windows¶
To install on Windows, download the latest stable version from
Graphviz website
and update the PATH
environment variable according to where you
installed the executable files (especially dot.exe
). You also need
to let Graphviz find the relevant plug-ins (especially for SVG, PDF,
PNG diagram production) in the Windows environment.
For instance, if dot.exe
is located in
C:\Program Files (x86)\Graphviz\bin
, just type:
in the “Command Prompt”:
setx PATH "C:\Program Files (x86)\Graphviz\bin;%PATH%" dot -cin “Windows Power Shell”:
setx PATH "C:\Program Files (x86)\Graphviz\bin;$Env:PATH" dot -c
If you encounter any problem with the dot
command (e.g. a message
saying that some file does not have the proper writing permission),
execute your shell (“Command Prompt” or “Windows Power Shell”) as an
administrator and retry the command.
2.4. Test your installation¶
Download model examples here.
Extract the archive, open a terminal in the models
directory, then type:
cd quickstart
emulsion run --plot quickstart.yaml --view-model --silent
This should produce the following output:
Simulation level:population
Generated state machine diagram img/Quickstart_age_group_machine.svg
Generated state machine diagram img/Quickstart_life_cycle_machine.svg
Generated state machine diagram img/Quickstart_health_state_machine.svg
100%|*************************************************************| 10/10
Simulation finished in 12.37 s
Outputs stored in outputs/counts.csv
Outputs plot in file: img/Quickstart.html
and the following figures should appear in your navigator:




2.5. Alternative 1: install with git
¶
This procedure assumes that you have git
already
installed on your system.
It is provided here for Linux or MacOS.
Install (or update) required packages
sudo pip3 install numpy scipy matplotlib pandas 'sympy==1.1.1' mpmath sudo pip3 install networkx docopt jinja2 textx sudo pip3 install sortedcontainers tqdm pyyaml colorama sudo pip3 install bokeh sqlalchemy utm
Clone the EMULSION repository
git clone https://git.renater.fr/anonscm/git/emulsion-public/emulsion-public.git cd emulsion-public
Add the local directory and
src
directory to yourPYTHONPATH
environment variable.echo "export PYTHONPATH=$(pwd)/src:." >>$HOME/.bashrc
Install command-line completion (optional but very convenient).
echo "source $(pwd)/src/emulsion/scripts/emulsion-completion.sh" >>$HOME/.bashrc
Command-line completion (available with a bash shell, under Linux or MacOS) allows to use
TAB
key to get suggestions on what is expected (options, files, parameters…) in the command.Create command
emulsion
:echo "alias emulsion='python3 -m emulsion'" >>$HOME/.bashrc
Force the shell to update your init file:
source $HOME/.bashrc
2.6. Alternative 2: install development version¶
Draft versions of EMULSION are periodically released, usually under
the same license. They are available through pip
from
PyPI’s test server as follows:
Search for “emulsion” project on PyPI’s test website to identify a development version that suits your needs
Install the development version (replace
VERSION
below with the version number, e.g.1.1rc5
or1.2b1
):sudo pip3 install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.python.org/simple/ emulsion==VERSION init_emulsion source $HOME/.bashrc
The development version should be now installed (check version with
emulsion -V
). The documentation of the latest development version publicly available can be found here.