Updated readthedocs

docs/_build/html/_sources/index.rst.txt

@@ -13,11 +13,13 @@ Soil is an Agent-based Social Simulator in Python for modelling and simulation o
    :caption: Learn more about soil:
 
    installation
+   usage
+   models
 
 
-Indices and tables
-==================
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. Indices and tables
+   ==================
+   * :ref:`genindex`
+   * :ref:`modindex`
+   * :ref:`search`

docs/_build/html/_sources/models.rst.txt

@@ -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 Simulation 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.number_of_nodes):
+        sentimentCorrelationNodeArray.append({'id': x})
+    # Initialize agent states. Let's assume everyone is normal.
+    init_states = [{'id': 0, } for _ in range(settings.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. 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/_build/html/_sources/usage.rst.txt

@@ -0,0 +1,98 @@
+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.py file you will find the configuration of the network.
+
+  .. code:: python
+
+    # Network settings
+    network_type = 1
+    number_of_nodes = 1000
+    max_time = 50
+    num_trials = 1
+    timeout = 2
+
+* In the Simulation Settings JSON file, you will 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 Simulation Settings JSON file.
+
+.. 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.
+
+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
+
+    python 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.