mirror of
https://github.com/gsi-upm/soil
synced 2024-11-14 15:32:29 +00:00
93 lines
3.4 KiB
ReStructuredText
93 lines
3.4 KiB
ReStructuredText
Quickstart
|
||
----------
|
||
|
||
This section shows how to run your first simulation with Soil.
|
||
For installation instructions, see :doc:`installation`.
|
||
|
||
There are mainly two parts in a simulation: agent classes and simulation configuration.
|
||
An agent class defines how the agent will behave throughout the simulation.
|
||
The configuration includes things such as number of agents to use and their type, network topology to use, etc.
|
||
|
||
|
||
.. image:: soil.png
|
||
:width: 80%
|
||
:align: center
|
||
|
||
|
||
Soil includes several agent classes in the ``soil.agents`` module, and we will use them in this quickstart.
|
||
If you are interested in developing your own agents classes, see :doc:`soil_tutorial`.
|
||
|
||
Configuration
|
||
=============
|
||
To get you started, we will use this configuration (:download:`download the file <quickstart.yml>` directly):
|
||
|
||
.. literalinclude:: quickstart.yml
|
||
:language: yaml
|
||
|
||
The agent type used, SISa, is a very simple model.
|
||
It only has three states (neutral, content and discontent),
|
||
Its parameters are the probabilities to change from one state to another, either spontaneously or because of contagion from neighboring agents.
|
||
|
||
Running the simulation
|
||
======================
|
||
|
||
To see the simulation in action, simply point soil to the configuration, and tell it to store the graph and the history of agent states and environment parameters at every point.
|
||
|
||
.. code::
|
||
|
||
❯ soil --graph --csv quickstart.yml [13:35:29]
|
||
INFO:soil:Using config(s): quickstart
|
||
INFO:soil:Dumping results to soil_output/quickstart : ['csv', 'gexf']
|
||
INFO:soil:Starting simulation quickstart at 13:35:30.
|
||
INFO:soil:Starting Simulation quickstart trial 0 at 13:35:30.
|
||
INFO:soil:Finished Simulation quickstart trial 0 at 13:35:49 in 19.43677067756653 seconds
|
||
INFO:soil:Starting Dumping simulation quickstart trial 0 at 13:35:49.
|
||
INFO:soil:Finished Dumping simulation quickstart trial 0 at 13:35:51 in 1.7733407020568848 seconds
|
||
INFO:soil:Dumping results to soil_output/quickstart
|
||
INFO:soil:Finished simulation quickstart at 13:35:51 in 21.29862952232361 seconds
|
||
|
||
|
||
The ``CSV`` file should look like this:
|
||
|
||
.. code::
|
||
|
||
agent_id,t_step,key,value
|
||
env,0,neutral_discontent_spon_prob,0.05
|
||
env,0,neutral_discontent_infected_prob,0.1
|
||
env,0,neutral_content_spon_prob,0.2
|
||
env,0,neutral_content_infected_prob,0.4
|
||
env,0,discontent_neutral,0.2
|
||
env,0,discontent_content,0.05
|
||
env,0,content_discontent,0.05
|
||
env,0,variance_d_c,0.05
|
||
env,0,variance_c_d,0.1
|
||
|
||
Results and visualization
|
||
=========================
|
||
|
||
The environment variables are marked as ``agent_id`` env.
|
||
Th exported values are only stored when they change.
|
||
To find out how to get every key and value at every point in the simulation, check out the :doc:`soil_tutorial`.
|
||
|
||
The dynamic graph is exported as a .gexf file which could be visualized with
|
||
`Gephi <https://gephi.org/users/download/>`__.
|
||
Now it is your turn to experiment with the simulation.
|
||
Change some of the parameters, such as the number of agents, the probability of becoming content, or the type of network, and see how the results change.
|
||
|
||
|
||
Soil also includes a web server that allows you to upload your simulations, change parameters, and visualize the results, including a timeline of the network.
|
||
To make it work, you have to install soil like this:
|
||
|
||
.. code::
|
||
|
||
pip install soil[web]
|
||
|
||
Once installed, the soil web UI can be run in two ways:
|
||
|
||
.. code::
|
||
|
||
soil-web
|
||
|
||
# OR
|
||
|
||
python -m soil.web |