Initial commit

docs/index.rst

@@ -8,38 +8,13 @@ Welcome to Soil's documentation!
 
 Soil is an Agent-based Social Simulator in Python for modelling and simulation of Social Networks.
 
-If you use Soil in your research, do not forget to cite this paper:
-
-.. code:: bibtex
-
-    @inbook{soil-gsi-conference-2017,
-        author = "S{\'a}nchez, Jes{\'u}s M. and Iglesias, Carlos A. and S{\'a}nchez-Rada, J. Fernando",
-        booktitle = "Advances in Practical Applications of Cyber-Physical Multi-Agent Systems: The PAAMS Collection",
-        doi = "10.1007/978-3-319-59930-4_19",
-        editor = "Demazeau Y., Davidsson P., Bajo J., Vale Z.",
-        isbn = "978-3-319-59929-8",
-        keywords = "soil;social networks;agent based social simulation;python",
-        month = "June",
-        organization = "PAAMS 2017",
-        pages = "234-245",
-        publisher = "Springer Verlag",
-        series = "LNAI",
-        title = "{S}oil: {A}n {A}gent-{B}ased {S}ocial {S}imulator in {P}ython for {M}odelling and {S}imulation of {S}ocial {N}etworks",
-        url = "https://link.springer.com/chapter/10.1007/978-3-319-59930-4_19",
-        volume = "10349",
-        year = "2017",
-    }
-
-
-
-
 .. toctree::
    :maxdepth: 2
    :caption: Learn more about soil:
 
    installation
-   quickstart
-   Tutorial - Spreading news
+   usage
+   models
 
 
 

docs/installation.rst

@@ -1,24 +1,7 @@
 Installation
 ------------
-
-The easiest way to install Soil is through pip:
+The latest version can be installed through GitLab.
 
 .. code:: bash
 
-   pip install soil
-
-
-Now test that it worked by running the command line tool
-
-.. code:: bash
-
-   soil --help
-
-Or using soil programmatically:
-
-.. code:: python
-
-   import soil
-   print(soil.__version__)
-
-The latest version can be installed through `GitLab <https://lab.cluster.gsi.dit.upm.es/soil/soil.git>`_.
+   git clone https://lab.cluster.gsi.dit.upm.es/soil/soil.git

docs/models.rst

@@ -0,0 +1,112 @@
+Developing new models
+---------------------
+This document describes how to develop a new analysis model.
+
+What is a model?
+================
+
+A model defines the behaviour of the agents with a view to assessing their effects on the system as a whole.
+In practice, a model consists of at least two parts:
+
+* Python module: the actual code that describes the behaviour.
+* Setting up the variables in the Settings JSON file.
+
+This separation allows us to run the simulation with different agents.
+
+Models Code
+===========
+
+All the models are imported to the main file. The initialization look like this:
+
+.. code:: python
+
+    import settings
+
+    networkStatus = {}  # Dict that will contain the status of every agent in the network
+
+    sentimentCorrelationNodeArray = []
+    for x in range(0, settings.network_params["number_of_nodes"]):
+        sentimentCorrelationNodeArray.append({'id': x})
+    # Initialize agent states. Let's assume everyone is normal.
+    init_states = [{'id': 0, } for _ in range(settings.network_params["number_of_nodes"])]
+        # add keys as as necessary, but "id" must always refer to that state category
+
+A new model have to inherit the BaseBehaviour class which is in the same module.
+There are two basics methods:
+
+* __init__
+* step: used to define the behaviour over time.
+
+Variable Initialization
+=======================
+
+The different parameters of the model have to be initialize in the Simulation Settings JSON file which will be
+passed as a parameter to the simulation.
+
+.. code:: json
+
+    {
+        "agent": ["SISaModel","ControlModelM2"],
+
+        "neutral_discontent_spon_prob": 0.04,
+        "neutral_discontent_infected_prob": 0.04,
+        "neutral_content_spon_prob": 0.18,
+        "neutral_content_infected_prob": 0.02,
+
+        "discontent_neutral": 0.13,
+        "discontent_content": 0.07,
+        "variance_d_c": 0.02,
+
+        "content_discontent": 0.009,
+        "variance_c_d": 0.003,
+        "content_neutral": 0.088,
+
+        "standard_variance": 0.055,
+
+
+        "prob_neutral_making_denier": 0.035,
+
+        "prob_infect": 0.075,
+
+        "prob_cured_healing_infected": 0.035,
+        "prob_cured_vaccinate_neutral": 0.035,
+
+        "prob_vaccinated_healing_infected": 0.035,
+        "prob_vaccinated_vaccinate_neutral": 0.035,
+        "prob_generate_anti_rumor": 0.035
+    }
+
+In this file you will also define the models you are going to simulate. You can simulate as many models as you want.
+The simulation returns one result for each model, executing each model separately. For the usage, see :doc:`usage`.
+
+Example Model
+=============
+
+In this section, we will implement a Sentiment Correlation Model.
+
+The class would look like this:
+
+.. code:: python
+
+    from ..BaseBehaviour import *
+    from .. import sentimentCorrelationNodeArray
+
+    class SentimentCorrelationModel(BaseBehaviour):
+
+        def __init__(self, environment=None, agent_id=0, state=()):
+            super().__init__(environment=environment, agent_id=agent_id, state=state)
+            self.outside_effects_prob = environment.environment_params['outside_effects_prob']
+            self.anger_prob = environment.environment_params['anger_prob']
+            self.joy_prob = environment.environment_params['joy_prob']
+            self.sadness_prob = environment.environment_params['sadness_prob']
+            self.disgust_prob = environment.environment_params['disgust_prob']
+            self.time_awareness = []
+            for i in range(4):  # In this model we have 4 sentiments
+                self.time_awareness.append(0)  # 0-> Anger, 1-> joy, 2->sadness, 3 -> disgust
+            sentimentCorrelationNodeArray[self.id][self.env.now] = 0
+
+        def step(self, now):
+            self.behaviour()  # Method which define the behaviour
+            super().step(now)
+
+The variables will be modified by the user, so you have to include them in the Simulation Settings JSON file.

docs/quickstart.rst

@@ -1,194 +0,0 @@
-Quickstart
-----------
-
-This section shows how to run simulations from simulation configuration files.
-First of all, you need to install the package (See :doc:`installation`)
-
-Simulation configuration files are ``json`` or ``yaml`` files that define all the parameters of a simulation.
-Here's an example (``example.yml``).
-
-.. code:: yaml
-          
-    ---
-    name: MyExampleSimulation
-    max_time: 50
-    num_trials: 3
-    timeout: 2
-    network_params:
-        network_type: barabasi_albert_graph
-        n: 100
-        m: 2
-    agent_distribution:
-        - agent_type: SISaModel
-            weight: 1
-            state:
-            id: content
-        - agent_type: SISaModel
-            weight: 1
-            state:
-            id: discontent
-        - agent_type: SISaModel
-            weight: 8
-            state:
-            id: neutral
-    environment_params:
-        prob_infect: 0.075
-
-Now run the simulation with the command line tool:
-
-.. code:: bash
-
-   soil example.yml
-
-Once the simulation finishes, its results will be stored in a folder named ``MyExampleSimulation``.
-Four types of objects are saved by default: a pickle of the simulation, a ``YAML`` representation of the simulation (to re-launch it), for every trial, a csv file with the content of the state of every network node and the environment parameters at every step of the simulation as well as the network in gephi format (``gexf``).
-
-
-.. code::
-
-    soil_output
-    ├── Sim_prob_0
-    │   ├── Sim_prob_0.dumped.yml
-    │   ├── Sim_prob_0.simulation.pickle
-    │   ├── Sim_prob_0_trial_0.environment.csv
-    │   └── Sim_prob_0_trial_0.gexf
-
-
-This example configuration will run three trials of a simulation containing a randomly generated network.
-The 100 nodes in the network will be SISaModel agents, 10% of them will start in the content state, 10% in the discontent state, and the remaining 80% in the neutral state.
-All agents will have access to the environment, which only contains one variable, ``prob_infected``.
-The state of the agents will be updated every 2 seconds (``timeout``).
-
-
-Network
-=======
-
-The network topology for the simulation can be loaded from an existing network file or generated with one of the random network generation methods from networkx.
-
-Loading a network
-#################
-
-To load an existing network, specify its path in the configuration:
-
-.. code:: yaml
-
-   ---
-   network_params:
-      path: /tmp/mynetwork.gexf
-
-Soil will try to guess what networkx method to use to read the file based on its extension.
-However, we only test using ``gexf`` files.
-
-Generating a random network
-###########################
-
-To generate a random network using one of networkx's built-in methods, specify the `graph generation algorithm <https://networkx.github.io/documentation/development/reference/generators.html>`_ and other parameters.
-For example, the following configuration is equivalent to :code:`nx.complete_graph(100)`:
-
-.. code:: yaml
-
-    network_params:
-        network_type: complete_graph
-        n: 100
-
-Environment
-============
-The environment is the place where the shared state of the simulation is stored.
-For instance, the probability of certain events.
-The configuration file may specify the initial value of the environment parameters:
-
-.. code:: yaml
-
-    environment_params:
-        daily_probability_of_earthquake: 0.001
-        number_of_earthquakes: 0
-
-Agents
-======
-Agents are a way of modelling behavior.
-Agents can be characterized with two variables: an agent type (``agent_type``) and its state.
-Only one agent is executed at a time (generally, every ``timeout`` seconds), and it has access to its state and the environment parameters.
-Through the environment, it can access the network topology and the state of other agents.
-
-There are three three types of agents according to how they are added to the simulation: network agents, environment agent, and other agents.
-
-Network Agents
-##############
-Network agents are attached to a node in the topology.
-The configuration file allows you to specify how agents will be mapped to topology nodes.
-
-The simplest way is to specify a single type of agent.
-Hence, every node in the network will have an associated agent of that type.
-
-.. code:: yaml
-
-   agent_type: SISaModel
-
-It is also possible to add more than one type of agent to the simulation, and to control the ratio of each type (``weight``).
-For instance, with following configuration, it is five times more likely for a node to be assigned a CounterModel type than a SISaModel type.
-
-.. code:: yaml
-
-   agent_distribution:
-      - agent_type: SISaModel
-        weight: 1
-      - agent_type: CounterModel
-        weight: 5
-
-In addition to agent type, you may also add a custom initial state to the distribution.
-This is very useful to add the same agent type with different states.
-e.g., to populate the network with SISaModel, roughly 10% of them with a discontent state:
-
-.. code:: yaml
-
-    agent_distribution:
-        - agent_type: SISaModel
-            weight: 9
-            state:
-            id: neutral
-        - agent_type: SISaModel
-            weight: 1
-            state:
-            id: discontent
-
-Lastly, the configuration may include initial state for one or more nodes.
-For instance, to add a state for the two nodes in this configuration:
-
-.. code:: yaml
-
-   agent_type: SISaModel
-   network:
-      network_type: complete_graph
-      n: 2
-   states:
-     - id: content
-     - id: discontent
-
-
-Or to add state only to specific nodes (by ``id``).
-For example, to apply special skills to Linux Torvalds in a simulation:
-
-.. literalinclude:: ../examples/torvalds.yml
-   :language: yaml
-
-
-Environment Agents
-##################
-In addition to network agents, more agents can be added to the simulation.
-These agens are programmed in much the same way as network agents, the only difference is that they will not be assigned to network nodes.
-
-
-.. code::
-
-   environment_agents:
-       - agent_type: MyAgent
-         state:
-           mood: happy
-       - agent_type: DummyAgent
-
-
-Visualizing the results
-=======================
-
-The simulation will return a dynamic graph .gexf file which could be visualized with
-`Gephi <https://gephi.org/users/download/>`__.

docs/usage.rst

@@ -0,0 +1,99 @@
+Usage
+-----
+
+First of all, you need to install the package. See :doc:`installation` for installation instructions.
+
+Simulation Settings
+===================
+
+Once installed, before running a simulation, you need to configure it.
+
+* In the Settings JSON file you will find the configuration of the network.
+
+  .. code:: python
+
+    {
+        "network_type": 1,
+        "number_of_nodes": 1000,
+        "max_time": 50,
+        "num_trials": 1,
+        "timeout": 2
+    }
+
+* In the Settings JSON file, you will also find the configuration of the models.
+
+Network Types
+=============
+
+There are three types of network implemented, but you could add more.
+
+.. code:: python
+
+    if settings.network_type == 0:
+        G = nx.complete_graph(settings.number_of_nodes)
+    if settings.network_type == 1:
+        G = nx.barabasi_albert_graph(settings.number_of_nodes, 10)
+    if settings.network_type == 2:
+        G = nx.margulis_gabber_galil_graph(settings.number_of_nodes, None)
+    # More types of networks can be added here
+
+Models Settings
+===============
+
+After having configured the simulation, the next step is setting up the variables of the models.
+For this, you will need to modify the Settings JSON file again.
+
+.. code:: json
+
+    {
+        "agent": ["SISaModel","ControlModelM2"],
+
+        "neutral_discontent_spon_prob": 0.04,
+        "neutral_discontent_infected_prob": 0.04,
+        "neutral_content_spon_prob": 0.18,
+        "neutral_content_infected_prob": 0.02,
+
+        "discontent_neutral": 0.13,
+        "discontent_content": 0.07,
+        "variance_d_c": 0.02,
+
+        "content_discontent": 0.009,
+        "variance_c_d": 0.003,
+        "content_neutral": 0.088,
+
+        "standard_variance": 0.055,
+
+
+        "prob_neutral_making_denier": 0.035,
+
+        "prob_infect": 0.075,
+
+        "prob_cured_healing_infected": 0.035,
+        "prob_cured_vaccinate_neutral": 0.035,
+
+        "prob_vaccinated_healing_infected": 0.035,
+        "prob_vaccinated_vaccinate_neutral": 0.035,
+        "prob_generate_anti_rumor": 0.035
+    }
+
+In this file you will define the different models you are going to simulate. You can simulate as many models
+as you want. Each model will be simulated separately.
+
+After setting up the models, you have to initialize the parameters of each one. You will find the parameters needed
+in the documentation of each model.
+
+Parameter validation will fail if a required parameter without a default has not been provided.
+
+Running the Simulation
+======================
+
+After setting all the configuration, you will be able to run the simulation. All you need to do is execute:
+
+.. code:: bash
+
+    python3 soil.py
+
+The simulation will return a dynamic graph .gexf file which could be visualized with
+`Gephi <https://gephi.org/users/download/>`__.
+
+It will also return one .png picture for each model simulated.