2. Installation

2.1. Requirements

System

EMULSION has been designed under MacOS and Linux, and works (with minor limitations) with Windows 10 or later. 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.9 or higher).

2.2. Using installation script (recommended)

This installation script installs everything you need to run EMULSION without requiring administrator rights. To do so, it installs a conda environment (based on Miniconda3), unless you already have conda installed on your system.

By installing EMULSION that way, we assume that you agree with the terms of the Miniconda3 license and of EMULSION license (see License).

1. Download the installation script dedicated to your platform:

• Windows: install_emulsion-1.2rc6-Windows.exe

• MacOS (Silicon processor e.g. M1, M2): install_emulsion-1.2rc6-MacOSX-arm64

• MacOS (Intel processor): install_emulsion-1.2rc6-MacOSX-x86_64

• Linux: install_emulsion-1.2rc6-Linux-x86_64.sh

2. Run the script (double-click or from the terminal). You need to be online during the process to download installation files. The installation process might ask you some questions:

   most of the time, default answers are OK.

   e.g., on MacOS/Linux:

   sh install_emulsion-1.2rc6-Linux-x86_64.sh
   

   or on Windows (open powershell):

   install_emulsion-1.2rc6-Windows.exe
   

   This will install version 1.2rc6, but the script can also be used to install the latest stable version, for instance:

   sh install_emulsion-1.2rc6-Linux-x86_64.sh latest
   

3. At the end of EMULSION installation, you can choose to download example models (the Quickstart model and those provided in Feature examples) and run the Quickstart model to make sure that the installation succeeded.

EMULSION documentation is provided on-line.

If you need a specific version of EMULSION (e.g., a development version such as 1.3b1), you can specify it when running the script (ensure first that this version is available on PyPI):

sh install_emulsion-latest-Linux-x86_64.sh 1.3b1

or on Windows (open powershell):

install_emulsion-latest-Windows.exe 1.3b1

Build your own installation script

If you do not find the installation script corresponding to your own machine, you can either install EMULSION step-by-step (see next section), or try to build an installation script on your system.

To do so, you need a Python3 environment with packages pyinstaller, pyyaml, semantic_version and colorama.

1. Download the multi-platform installation script install_emulsion.py

2. Run:

python3 install_emulsion.py --build

The resulting installation script is now located in dist/. You can also specify a version number in the build command.

2.3. Alternative 1: Manual install with pip

1. Install a Python 3 environment

To ensure a consistent environment, we recommend installing Miniconda3. Otherwise, to install a classical Python environment 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 powershell).

In what follows, we assume that python and pip refer to your Python3 installation. If not, replace them by your own configuration in the commands below.

2a. Linux and MacOS:

pip install emulsion
init_emulsion
source $HOME/.bashrc

Depending on how you installed Python, you might need administrator privileges (sudo before pip install).

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.

2b. Windows:

Open a terminal (“Command Prompt” or “Windows Power Shell”), then type:

pip.exe install emulsion

3. Install completion (optional)

As typing long emulsion commands with many options may be tedious, EMULSION comes with completion scripts, so that you can get value proposals using the TAB key.

To do so, you can download one of the following files and run it at the opening of your session:

• Windows powershell script: emulsion-powershell-completion.ps1

  powershell -ExecutionPolicy Bypass -File emulsion-powershell-completion.ps1
  

• Linux/MacOS bash script: emulsion-bash-completion.sh then add to your .bashrc or .bash_profile, e.g.:

  echo "source emulsion-bash-completion.sh" >>$HOME/.bashrc
  

• Linux/MacOS zsh script: emulsion-zsh-completion.sh then add to your .zshrc:

  echo -e "autoload -U compinit ; compinit\nsource $HOME/emulsion-zsh-completion.sh" >>$HOME/.zshrc
  

4. Install Graphviz (optional)

Graphviz is a third-party software used by EMULSION to produce diagrams for the processes represented by state machines (more specifically, the program called dot).

If you installed Python 3 with Miniconda (or Anaconda), the installation of Graphviz within the Python environment does not require administrator privileges:

conda install -c conda-forge python-graphviz
# configure 'dot' program
dot -c

An alternative is to follow Graphviz installation instructions.

5. 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 -r 20 --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%|█████████████████████████████████████████████████████████████████| 20/20
Simulation finished in 6.75 s
Outputs stored in outputs/counts.csv
Outputs plot in file: img/Quickstart.html

and the following figures should appear in your navigator:

2.4. Alternative 2: manual install with git

This procedure assumes that you have both Python3 and git already installed on your system. It is provided here for Linux or MacOS.

1. Install (or update) required packages

   pip install numpy scipy matplotlib pandas sympy mpmath pydot networkx docopt jinja2 sortedcontainers tqdm pyyaml colorama bokeh sqlalchemy
   

2. Clone the EMULSION repository

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

3. Add src directory to your PYTHONPATH environment variable.

   echo "export PYTHONPATH=$(pwd)/src:$PYTHONPATH" >>$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.5. 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.2rc3 or 1.3b1):

   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.