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

d9e55f4071dab4d2e3aa01b1a4524b5ae2141d6b
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 Python3 (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 `Python website <https://www.python.org/downloads/>`_
29 Install with ``pip``
30 ********************
32 Linux and MacOS:
33 ================
35 .. code-block:: bash
37    sudo pip3 install emulsion
38    init_emulsion
39    source $HOME/.basrc
41 Depending on how you installed Python, ``sudo`` is sometimes
42 optional.
44 The second command (``init_emulsion``) initializes command-line
45 completion (available with a bash shell, under Linux or MacOS), which allows
46 to use ``TAB`` key to get suggestions on what is expected (options,
47 files, parameters...) in the command.
49 When installing with ``pip``, `documentation <https://sourcesup.renater.fr/emulsion-public>`_
50 is provided on-line.
52 Windows
53 =======
55 Open a terminal ("Command Prompt" or "Windows Power Shell"), then
56 type:
58 .. code-block:: batch
60    pip.exe install emulsion
61    setx PYTHONPATH "%PYTHONPATH%;."
65 Install with ``git``
66 ********************
68 This procedure assumes that you have ``git`` already
69 `installed on your system <https://git-scm.com/downloads>`_.
70 It is provided here for Linux or MacOS.
73 #. Install (or update) required packages
75    .. code-block:: bash
77       sudo pip3 install numpy scipy matplotlib sympy pandas
78       sudo pip3 install networkx docopt jinja2 textx
79       sudo pip3 install sortedcontainers tqdm pyyaml
80       sudo pip3 install bokeh sqlalchemy
82 #. Clone the EMULSION repository
84    .. code-block:: bash
86       git clone https://git.renater.fr/emulsion-public.git
87       cd emulsion-public
89 #. Add the local directory and ``src`` directory to your ``PYTHONPATH`` environment
90    variable.
92    .. code-block:: bash
94       echo "export PYTHONPATH=$(pwd)/src:." >>$HOME/.bashrc
96 #. Install command-line completion (optional but very convenient).
98    .. code-block:: bash
100       echo "source $(pwd)/scripts/emulsion-completion.sh" >>$HOME/.bashrc
102    Command-line completion (available with a bash shell, under Linux
103    or MacOS) allows to use ``TAB`` key to get suggestions on what is
104    expected (options, files, parameters...) in the command.
106 #. Create command ``emulsion``:
108    .. code-block:: bash
110       echo "alias emulsion='python3 -m emulsion'" >>$HOME/.bashrc
112 #. Force the shell to update your init file:
114    .. code-block:: bash
116       source $HOME/.bashrc
119 Install third-party software
120 ****************************
122 `Graphviz <http://www.graphviz.org>`_ is highly recommended
123 (otherwise, simulations will run but you will not be able to get the
124 nice diagrams representing model structure).
126 Linux
127 =====
129 .. code-block:: bash
131    sudo apt install graphviz
133 MacOS
134 =====
136 To install on MacOS, use for instance `homebrew <https://brew.sh/>`_
138 .. code-block:: bash
140    brew install graphviz
142 Windows
143 =======
145 To install on Windows, download the latest stable version from
146 `Graphviz website <https://graphviz.gitlab.io/_pages/Download/Download_windows.html>`_
147 and update the ``PATH`` environment variable according to where you
148 installed the executable files (especially ``dot.exe``).
149 For instance, if ``dot.exe`` is located in
150 ``C:\Program Files (x86)\Graphviz\bin``, just type:
152 .. code-block:: batch
154   setx PATH "%PATH%;C:\Program Files (x86)\Graphviz\bin"
157 Test your installation
158 **********************
160 Download **model examples**
161 `here. <https://sourcesup.renater.fr/emulsion-public/models.zip>`_
163 Extract the archive, open a terminal in the ``models`` directory, then type:
165 .. code-block:: bash
167    cd quickstart
168    emulsion run --plot quickstart.yaml --view-model --silent
170 This should produce the following output::
172     Simulation level: herd
173     Generated state machine diagram img/Quickstart_age_group_machine.png
174     Generated state machine diagram img/Quickstart_life_cycle_machine.png
175     Generated state machine diagram img/Quickstart_health_state_machine.png
176     100%|*************************************************************| 10/10
177     Simulation finished in 9.48 s
178     Outputs stored in outputs/counts.csv
179     Outputs plot in file: img/Quickstart.html
181 and the following figures should appear in your navigator:
183 .. graphviz:: ../_images/Quickstart_age_group.dot
184    :align: center
186 .. image:: ../_images/Quickstart_JA.png
187    :align: left
189 .. graphviz:: ../_images/Quickstart_life_cycle.dot
190    :align: center
192 .. image:: ../_images/Quickstart_GNG.png
193    :align: left
195 .. graphviz:: ../_images/Quickstart_health_state.dot
196    :align: center
198 .. image:: ../_images/Quickstart_MSEIRQ.png
199    :align: left
201 .. image:: ../_images/Quickstart_others.png
202    :align: left