docs initialization

Symu examples/SymuGroupAndInteraction/Home.resx

@@ -123,8 +123,8 @@
 * People who are members of the group
 
 Knowledge, activites, beliefs and social-demographics are defined for every agents.
-Those parameters has an impact on the way people are interacting every day in their group, in their sphere of _model.
-Play with the _model strategy to see the impact on the organization flexibility, defined by the capacity of creating triads.
-Try to increase triads with the creation of new _models.</value>
+Those parameters has an impact on the way people are interacting every day in their group, in their sphere of interaction
+Play with the interaction strategy to see the impact on the organization flexibility, defined by the capacity of creating triads.
+Try to increase triads with the creation of new interactions.</value>
   </data>
 </root>

docs/index.rst

@@ -5,8 +5,19 @@ Welcome to Symu's documentation!
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: User guides:
 
+   userguides/symugroupandinteraction
+   userguides/symulearnAndforget
+   userguides/symugmessageandtask
+   models/agent
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Models:
+
+   models/simulation
+   models/agent
 
 Indices and tables
 ==================

docs/models/agent.rst

@@ -0,0 +1,24 @@
+*****
+Agent
+*****
+
+Each agent as a cognitive architecture which allow to set up agent's models.
+This model is inspired by Construct specifications [#f1]_.
+
+Each model can be turn off or on. When the model is on, you can choose the percentage of agents that are impacted by the model. If 0 is chosen, any agent will be impacted, if 1 is chosen every agent will be impacted.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: models:
+
+   cognitivearchitecture/interactionpatterns
+   cognitivearchitecture/internalcharacteristics
+   cognitivearchitecture/knowledgeandbeliefs
+   cognitivearchitecture/tasksandperformance
+   cognitivearchitecture/interactioncharacteristics
+
+
+.. rubric:: Footnotes
+
+.. [#f1] "Specifying agents in Construct", Carley, 2007

docs/models/cognitivearchitecture/Internalcharacteristics.rst

@@ -0,0 +1,29 @@
+************************
+Internal characteristics 
+************************
+
+Model of forgetting
+*******************
+The counterpart of learning is forgetting. Agents may forget knowledge or information if they are not solicited during the simulation. Using a bit of knowledge during a step is enough to be sure that this bit will not be forget today.
+Forgetting has different modes: 
+
+* it could be random 
+* based on the age of the information
+
+Randomly selected
+=================
+
+You define a probability to forget, combined with the length of the knowledge, it will define the number of bits that will be forget during the day. If this rate = 0, agent will forget any bits of knowledge; if rate =1, every bit will be affected by the knowledge.
+For example, if you don’t use Symu, with a forgetting rate of 0.1, you may loose 0.1* 20 bits = 2 bits of knowledge today.
+Stander deviation define the level of randomness you want around the forgetting rate.
+
+Oldest knowledge
+================
+
+If the oldest knowledge mode is selected, only the oldest knowledge is eligible to be forgotten. It is based on it’s TimeToLive parameter. If set to -1, information will last during the simulation, otherwise it is compared with the age if the information to decide to forget it or not.
+
+Partial forgetting
+==================
+
+Then you must define the how every bit of knowledge is affected. If partial forgetting is chosen, the partial forgetting rate define how much an agent loose at each step, otherwise, the bit is completely forgotten.
+You can define the minimum level of information that left for each bit.

docs/models/cognitivearchitecture/interactioncharacteristics.rst

@@ -0,0 +1,21 @@
+***************************
+Interaction characteristics
+***************************
+
+Messaging is the only way agents communicate to each other. So messaging model represents the interaction mechanism of agents. This is one of the means of ensuring the autonomy of agents. A message can have different types: it can be a phone call, a meeting, an email, …
+Interaction characteritics model deinfes the way an agent will interact with other agents.
+There are two main aspects of the model that you can configure: 
+
+* limit
+* cost
+
+Limit messages
+**************
+
+You can limit the total number of messages an agent can send or received during a step; you can also specify the number of messages sent or the number of receptions per agent per step.
+It can be useful when you want to test the limitation of interaction between agents, whatever the interaction.
+
+Cost of the messages
+********************
+
+Sending or receiving a message can have a cost that depends of the type of the message. The cost may be a fraction of the capacity of an agent. For example, for an agent with a capacity of 1, going to a meeting of two hours, the cost to send the message may be equal to 0 (sending invitations) and the cost to receive the message may be equal to 0.25 (doing the meeting).

docs/models/cognitivearchitecture/interactionpatterns.rst

@@ -0,0 +1,51 @@
+********************
+Interaction patterns
+********************
+
+Each agent defines the way the agent interacts with other agents.
+certain types of non-relational agents such as a database are not part of the sphere.
+For those who are part of the interaction sphere, the sphere is computed depending on different parameters
+
+Interaction sphere
+******************
+
+It is based on different parameters:
+
+* Relative knowledge
+* Relative activities
+* Relative beliefs
+* Social demographics
+
+Each parameter has an associated weight to calculate the homophily factor.
+
+To interact with another agent, a filter agent with interaction sphere with an interaction strategy based on:
+
+* Relative knowledge
+* Relative activities
+* Relative beliefs
+* Social demographics
+* Homophily
+
+Sphere initialization
+*********************
+
+This model defines the way the interaction sphere is initialized and can change over time.
+The interaction sphere may be initialized in two ways: similarity matching and random generation.
+
+Similarity matching
+===================
+
+In that case, the interaction sphere is generated based on known informations about agents (knowledge, activities, beliefs, socio-demographics).
+
+Random generation
+=================
+
+This option can be usefull when you don't want to define nowledge, beliefs, ... It is based on parameters such as min/max density of the sphere. This specifies the proportion of agents who can appear in a given agent's interaction sphere.
+If an agent appears in the interaction sphere, its weigth is randomly generated.
+
+Sphere evolution
+****************
+During the simulation, the interaction sphere is updated with the updated agent's informations. As the action time consuming and based on the fact that knowledge, beliefs, ... don't evolve too frequently, you can adjust the frequency of update every day, every week, every month, enevry year.
+
+The sphere size may change over time if new agents are on boarding or agents are leaving the simulation.
+

docs/models/cognitivearchitecture/knowledgeandbeliefs.rst

@@ -0,0 +1,17 @@
+*********************
+Knowledge and beliefs
+*********************
+
+Symu is a multi-agent system for the co-evolution of agents and socio-cultural environments with an interaction model between agents. Each agent defines the way the agent interacts with other agents.
+certain types of non-relational agents such as a database are not part of the sphere.
+For those who are part of the interaction sphere, the sphere is computed depending on different parameters
+
+Knowledge model
+***************
+
+Agents have the capacity to have initial knowledge, during the simulation (learning model). If an agent has initial knowledge, it is initialized randomly depending on the knowledge level. You can choose the level in a list from no knowledge to full knowledge.
+
+Knowledge is defined by an array of bit of information between 0 and 1. The length of this array is a parameter between 0 to 100.
+
+For example, the knowledge to use Symu can be defined as an array of 20 bits. If you don’t know anything about it, the array is filled with 0. If you have a full knowledge of it, it will be filled with 1.
+Most of the case, the array will be filled randomly with 0/1 if the Binary Knowledge is chosen, or with float between [0; 1] otherwise.

docs/models/cognitivearchitecture/messagecontent.rst

@@ -0,0 +1,15 @@
+***************
+Message content
+***************
+
+Messaging is the only way agents communicate to each other. So messaging model represents the interaction mechanism of agents. This is one of the means of ensuring the autonomy of agents. A message can have different types: it can be a phone call, a meeting, an email, …
+Message content helps you define the content of a message : knowledge, beliefs, referral, ...
+
+Knowledge content
+*****************
+
+Each agent may be able to send or not knowledge (or information) and to receive or not knowledge.
+
+.. topic:: Example
+
+    You can use a book to learn new knowledge. As an agent, a book is able to send knowledge, but not able to receive knowledge.

docs/models/cognitivearchitecture/tasksandperformance.rst

@@ -0,0 +1,41 @@
+*********************
+Tasks and performance
+*********************
+
+Tasking model
+*************
+
+In Symu, agents are task-based. A task is an action with a cost. Some of them don’t perform task, such as a book or a static website; others can perform task such as workers. You can specify if the agent can perform task on weekends or not, that can be useful when your organization is an enterprise.
+There are also two main aspects of the model that you can configure: 
+
+* limit
+* capacity
+
+Limit tasks
+===========
+
+You can limit the total number of tasks an agent can perform during the entire simulation.
+You can also limit the number of simultaneous tasks an agent is performing. If you want to avoid multi-tasking, you can set the limit to one. It is also an easy way to create a pull-system.
+When you allow multi-tasking, you can define the impact of context switching between tasks on capacity. In that case, multiple tasks may be in progress at the same time.
+
+Cost of task and capacity of the agent
+======================================
+
+A task has a cost. To perform a task, an agent has capacity, re initialized at each new step. Each time an agent is performing a task, the capacity of the agent is decreased.
+
+Learning model
+**************
+Agents have the capacity to learn new knowledge or information during the simulation.
+There are different means to learn new knowledge: 
+
+* learning from a source of information
+* by interacting with another agent 
+* by doing by itself.
+
+This model is mainly defined by a rate of learning (learn rate and learn by doing rate). It defines how quickly an agent will learn new knowledge when interacting with other agents. 
+With a rate of 0.01, if an agent has initially a knowledge of 0.5, after a learning, its knowledge will be 0.5 +0.01 = 0.51.
+
+Learning by doing
+=================
+
+A special case is when an agent is doing by itself and gain knowledge. For that, agent must have a minimum of initial knowledge to do it by itself (knowledge threshold for doing) and it has a cost (cost factor), the associated task will take longer than if he already knew it, that is the cost of learning.

docs/models/simulation.rst

@@ -0,0 +1,34 @@
+**********
+Simulation
+**********
+
+Of course, Simulation is at the heart of this framework. It is based on two asynchronous models:
+
+* Messaging between agents
+* Tasks for each agent
+
+Messaging model
+***************
+Messaging is the only way agents communicate to each other. So messaging model represents the interaction mechanism of agents. This is one of the means of ensuring the autonomy of agents. A message can have different types: it can be a phone call, a meeting, an email, …
+
+Each type of message can be configure via templates.
+
+.. note:: to be done
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Each agent can configure its messaging model:
+
+   cognitivearchitecture/messagecontent
+   cognitivearchitecture/interactioncharacteristics
+
+Tasking model
+=============
+
+In Symu, agents are task-based. A task is an action with a cost. Some of them don’t perform task, such as a book or a static website; others can perform task such as workers. You can specify if the agent can perform task on weekends or not, that can be useful when your organization is an enterprise.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Each agent can configure its tasking model:
+
+   cognitivearchitecture/tasksandperformance

docs/userguides/symuLearnandforget.rst

@@ -0,0 +1,58 @@
+**************************
+SymuLearnAndForget example
+**************************
+
+.. image:: ../_static/SymuLearnAndForget.PNG 
+   :align: center
+
+Different models are implemented in this simulator. This example demonstrates the use of three of them: knowledge, learning and forgetting.
+
+Knowledge model
+***************
+
+Agents can start the simulation with initial knowledge or information.
+
+Learning model
+**************
+
+Agents have the capacity to learn new knowledge or information during the simulation.
+There are different means to learn new knowledge: 
+
+* learning from a source of information
+* by interacting with another agent
+* by doing by itself.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Find more information about the learning model:
+
+   ../models/cognitivearchitecture/tasksandperformance
+
+Forgetting model
+****************
+
+The counterpart of learning is forgetting. Agents may forget knowledge or information if they are not solicited during the simulation. Using a bit of knowledge during a step is enough to be sure that this bit will not be forget today.
+Forgetting has different modes: 
+
+* it could be random 
+* based on the age of the information.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Find more information about the forgetting model:
+
+   ../models/cognitivearchitecture/internalcharacteristics
+
+Scenario
+********
+
+You can use this example to discover and understand the impact of all the setups on the agents. That will help you setup you own learning and forgetting models.
+
+#. The first agent learns from a learning source
+#. The second agent learns from doing
+#. The third one learns by asking to an expert agent
+#. The last agent doesn’t learn
+#. All learnings are stored in a wiki.
+
+
+Find the `source code <https://github.com/lmorisse/Symu/tree/master/Symu%20examples/SymuLearnAndForget>`_

docs/userguides/symugroupandinteraction.rst

@@ -0,0 +1,34 @@
+*******************************
+SymuGroupAndInteraction example
+*******************************
+
+.. image:: ../_static/SymuGroupAndInteraction.PNG 
+   :align: center
+
+Different models are implemented in this simulator. SymuGroupAndInteraction demonstrate the use of one of them: the interaction model.
+
+You can use this example to discover and understand the impact of all the setups on the agents. That will help you setup you own interaction model.
+
+Interaction model
+*****************
+
+Symu is a multi-agent system for the co-evolution of agents and socio-cultural environments with an interaction model between agents.
+Find more information about the interaction model :
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   ../models/cognitivearchitecture/interactionpatterns
+
+Scenario
+********
+
+* Groups of people
+* People who are members of the group
+
+Knowledge, activites, beliefs and social-demographics are defined for every agents. Those parameters has an impact on the way people are interacting every day in their group, in their sphere of interaction.
+Play with the interaction strategy to see the impact on the organization flexibility, defined by the capacity of creating triads.
+Try to increase triads with the creation of new interactions.
+
+Find the `source code <https://github.com/lmorisse/Symu/tree/master/Symu%20examples/SymuGroupAndInteraction>`_