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 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.
72 #. Install (or update) required packages
74    .. code-block:: bash
76       sudo pip3 install numpy scipy matplotlib pandas 'sympy<1.3' mpmath
77       sudo pip3 install networkx docopt jinja2 textx
78       sudo pip3 install sortedcontainers tqdm pyyaml colorama
79       sudo pip3 install bokeh sqlalchemy utm
81 #. Clone the EMULSION repository
83    .. code-block:: bash
85       git clone https://git.renater.fr/emulsion-public.git
86       cd emulsion-public
88 #. Add the local directory and ``src`` directory to your ``PYTHONPATH`` environment
89    variable.
91    .. code-block:: bash
93       echo "export PYTHONPATH=$(pwd)/src:." >>$HOME/.bashrc
95 #. Install command-line completion (optional but very convenient).
97    .. code-block:: bash
99       echo "source $(pwd)/src/emulsion/scripts/emulsion-completion.sh" >>$HOME/.bashrc
101    Command-line completion (available with a bash shell, under Linux
102    or MacOS) allows to use ``TAB`` key to get suggestions on what is
103    expected (options, files, parameters...) in the command.
105 #. Create command ``emulsion``:
107    .. code-block:: bash
109       echo "alias emulsion='python3 -m emulsion'" >>$HOME/.bashrc
111 #. Force the shell to update your init file:
113    .. code-block:: bash
115       source $HOME/.bashrc
118 Install third-party software
119 ****************************
121 `Graphviz <http://www.graphviz.org>`_ is highly recommended
122 (otherwise, simulations will run but you will not be able to get the
123 nice diagrams representing model structure).
125 Linux
126 =====
128 .. code-block:: bash
130    sudo apt install graphviz
132 MacOS
133 =====
135 To install on MacOS, use for instance `homebrew <https://brew.sh/>`_
137 .. code-block:: bash
139    brew install graphviz
141 Windows
142 =======
144 To install on Windows, download the latest stable version from
145 `Graphviz website <https://graphviz.gitlab.io/_pages/Download/Download_windows.html>`_
146 and update the ``PATH`` environment variable according to where you
147 installed the executable files (especially ``dot.exe``).
148 For instance, if ``dot.exe`` is located in
149 ``C:\Program Files (x86)\Graphviz\bin``, just type:
151 .. code-block:: batch
153   setx PATH "%PATH%;C:\Program Files (x86)\Graphviz\bin"
156 Test your installation
157 **********************
159 Download **model examples**
160 `here. <https://sourcesup.renater.fr/emulsion-public/models.zip>`_
162 Extract the archive, open a terminal in the ``models`` directory, then type:
164 .. code-block:: bash
166    cd quickstart
167    emulsion run --plot quickstart.yaml --view-model --silent
169 This should produce the following output::
171     Simulation level: herd
172     Generated state machine diagram img/Quickstart_age_group_machine.png
173     Generated state machine diagram img/Quickstart_life_cycle_machine.png
174     Generated state machine diagram img/Quickstart_health_state_machine.png
175     100%|*************************************************************| 10/10
176     Simulation finished in 9.48 s
177     Outputs stored in outputs/counts.csv
178     Outputs plot in file: img/Quickstart.html
180 and the following figures should appear in your navigator:
182 .. graphviz:: ../_images/Quickstart_age_group.dot
183    :align: center
185 .. image:: ../_images/Quickstart_JA.png
186    :align: left
188 .. graphviz:: ../_images/Quickstart_life_cycle.dot
189    :align: center
191 .. image:: ../_images/Quickstart_GNG.png
192    :align: left
194 .. graphviz:: ../_images/Quickstart_health_state.dot
195    :align: center
197 .. image:: ../_images/Quickstart_MSEIRQ.png
198    :align: left
200 .. image:: ../_images/Quickstart_others.png
201    :align: left