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 and pip3 refer to your Python3 installation. If not, replace them by your own configuration in the commands below (e.g. with Windows: respectively python.exe and pip.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

MacOS

To install on MacOS, use for instance homebrew

brew 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 -c
  

• in “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.

1. 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
   

2. Clone the EMULSION repository

   git clone https://git.renater.fr/anonscm/git/emulsion-public/emulsion-public.git
   cd emulsion-public
   

3. Add the local directory and src directory to your PYTHONPATH environment variable.

   echo "export PYTHONPATH=$(pwd)/src:." >>$HOME/.bashrc
   

4. 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.

5. Create command emulsion:

   echo "alias emulsion='python3 -m emulsion'" >>$HOME/.bashrc
   

6. 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:

1. Search for “emulsion” project on PyPI’s test website to identify a development version that suits your needs

2. Install the development version (replace VERSION below with the version number, e.g. 1.1rc5 or 1.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
   

3. 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.