The Higher Education and Research forge

Home My Page Projects Code Snippets Project Openings EMULSION public releases
Summary Activity Surveys SCM Listes Sympa

SCM Repository

1 ************
2 Installation
3 ************
5 Requirements
6 ************
8 System
9     EMULSION has been designed under **MacOS** and **Linux**, and
10     works (with minor limitations) with **Windows 10**. See the
11     installation procedure specific to your system.
13     Also, in what follows, we assume that MacOS and Linux users are
14     working with a **bash** shell. If you are not sure, typing: ``echo
15     $SHELL`` in a terminal should print ``/bin/bash``. Otherwise, please refer to
16     the documentation of your shell to adapt the commands below.
18 Language
19     EMULSION is written in **Python 3** (version 3.6 or higher). In what
20     follows, we assume that ``python3`` and ``pip3`` refer to your
21     Python3 installation. If not, replace them by your own
22     configuration in the commands below (e.g. with Windows:
23     respectively ``python.exe`` and ``pip.exe``).
25     To install Python on your system, please consult
26     `Python website <https://www.python.org/downloads/>`_. When
27     installing on Windows, check the box "Add Python 3.x to PATH" to
28     make python commands available from the terminal.
31 Install with ``pip`` (recommended)
32 **********************************
34 Linux and MacOS:
35 ================
37 .. code-block:: bash
39    sudo pip3 install emulsion
40    init_emulsion
41    source $HOME/.bashrc
43 Depending on how you installed Python, ``sudo`` is sometimes
44 optional.
46 The second command (``init_emulsion``) initializes command-line
47 completion (available with a bash shell, under Linux or MacOS), which allows
48 to use ``TAB`` key to get suggestions on what is expected (options,
49 files, parameters...) in the command. It also creates (or modifies)
50 the environment variable named ``PYTHONPATH`` to make EMULSION able to
51 find code add-ons located in the same directory as your models.
53 EMULSION `documentation <https://sourcesup.renater.fr/emulsion-public>`_
54 is provided on-line.
56 Windows
57 =======
59 Open a terminal ("Command Prompt" or "Windows Power Shell"), then
60 type:
62 .. code-block:: batch
64    pip.exe install emulsion
66 To make EMULSION able to find code add-ons in the directory where your model
67 files are located, you must declare (or modify) an environment
68 variable named ``PYTHONPATH`` to add the current directory ("``.``").
70 To do so, you can use the graphical interface (from System
71 Preferences), or the terminal. The syntax depends on the kind of
72 terminal you are using:
74   - with the "Command Prompt" (``cmd.exe``), type:
76     .. code-block:: batch
78        setx PYTHONPATH ".;%PYTHONPATH%"
80   - with "Windows Power Shell", type:
82     .. code-block:: batch
84        setx PYTHONPATH ".;$Env:PYTHONPATH"
89 Install third-party software
90 ****************************
92 `Graphviz <http://www.graphviz.org>`_ is highly recommended
93 (otherwise, simulations will run but you will not be able to get the
94 nice diagrams representing model structure).
96 Linux
97 =====
99 .. code-block:: bash
101    sudo apt install graphviz
103 MacOS
104 =====
106 To install on MacOS, use for instance `homebrew <https://brew.sh/>`_
108 .. code-block:: bash
110    brew install graphviz
112 Windows
113 =======
115 To install on Windows, download the latest stable version from
116 `Graphviz website <https://graphviz.gitlab.io/_pages/Download/Download_windows.html>`_
117 and update the ``PATH`` environment variable according to where you
118 installed the executable files (especially ``dot.exe``).
119 For instance, if ``dot.exe`` is located in
120 ``C:\Program Files (x86)\Graphviz\bin``, just type:
122   - in the "Command Prompt":
124     .. code-block:: batch
126       setx PATH "C:\Program Files (x86)\Graphviz\bin;%PATH%"
128   - in "Windows Power Shell":
130     .. code-block:: batch
132       setx PATH "C:\Program Files (x86)\Graphviz\bin;$Env:PATH"
135 Test your installation
136 **********************
138 Download **model examples**
139 `here. <https://sourcesup.renater.fr/emulsion-public/models.zip>`_
141 Extract the archive, open a terminal in the ``models`` directory, then type:
143 .. code-block:: bash
145    cd quickstart
146    emulsion run --plot quickstart.yaml --view-model --silent
148 This should produce the following output::
150     Simulation level:herd
151     Generated state machine diagram img/Quickstart_age_group_machine.svg
152     Generated state machine diagram img/Quickstart_life_cycle_machine.svg
153     Generated state machine diagram img/Quickstart_health_state_machine.svg
154     100%|*************************************************************| 10/10
155     Simulation finished in 12.37 s
156     Outputs stored in outputs/counts.csv
157     Outputs plot in file: img/Quickstart.html
159 and the following figures should appear in your navigator:
161 .. graphviz:: ../_images/Quickstart_age_group.dot
162    :align: center
164 .. image:: ../_images/Quickstart_JA.png
165    :align: left
167 .. graphviz:: ../_images/Quickstart_life_cycle.dot
168    :align: center
170 .. image:: ../_images/Quickstart_GNG.png
171    :align: left
173 .. graphviz:: ../_images/Quickstart_health_state.dot
174    :align: center
176 .. image:: ../_images/Quickstart_MSEIRQ.png
177    :align: left
179 .. image:: ../_images/Quickstart_others.png
180    :align: left
184 Alternative: install with ``git``
185 *********************************
187 This procedure assumes that you have ``git`` already
188 `installed on your system <https://git-scm.com/downloads>`_.
189 It is provided here for Linux or MacOS.
191 #. Install (or update) required packages
193    .. code-block:: bash
195       sudo pip3 install numpy scipy matplotlib pandas 'sympy==1.1.1' mpmath
196       sudo pip3 install networkx docopt jinja2 textx
197       sudo pip3 install sortedcontainers tqdm pyyaml colorama
198       sudo pip3 install bokeh sqlalchemy utm
200 #. Clone the EMULSION repository
202    .. code-block:: bash
204       git clone https://git.renater.fr/emulsion-public.git
205       cd emulsion-public
207 #. Add the local directory and ``src`` directory to your ``PYTHONPATH`` environment
208    variable.
210    .. code-block:: bash
212       echo "export PYTHONPATH=$(pwd)/src:." >>$HOME/.bashrc
214 #. Install command-line completion (optional but very convenient).
216    .. code-block:: bash
218       echo "source $(pwd)/src/emulsion/scripts/emulsion-completion.sh" >>$HOME/.bashrc
220    Command-line completion (available with a bash shell, under Linux
221    or MacOS) allows to use ``TAB`` key to get suggestions on what is
222    expected (options, files, parameters...) in the command.
224 #. Create command ``emulsion``:
226    .. code-block:: bash
228       echo "alias emulsion='python3 -m emulsion'" >>$HOME/.bashrc
230 #. Force the shell to update your init file:
232    .. code-block:: bash
234       source $HOME/.bashrc