@ -3,13 +3,14 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [UNRELEASED]
## [0.3 UNRELEASED]
### Changed
### Changed
* Configuration schema is very different now. Check `soil.config` for more information. We are using Pydantic for (de)serialization.
* Configuration schema is very different now. Check `soil.config` for more information. We are also using Pydantic for (de)serialization.
* There may be more than one topology/network in the simulation
* There may be more than one topology/network in the simulation
* Agents are split into groups now. Each group may be assigned a given set of agents or an agent distribution, and a network topology to be assigned to.
* Agents are split into groups now. Each group may be assigned a given set of agents or an agent distribution, and a network topology to be assigned to.
### Removed
### Removed
* Any `tsih` and `History` integration in the main classes. To record the state of environments/agents, just use a datacollector. In some cases this may be slower or consume more memory than the previous system. However, few cases actually used the full potential of the history, and it came at the cost of unnecessary complexity and worse performance for the majority of cases.
* Any `tsih` and `History` integration in the main classes. To record the state of environments/agents, just use a datacollector. In some cases this may be slower or consume more memory than the previous system. However, few cases actually used the full potential of the history, and it came at the cost of unnecessary complexity and worse performance for the majority of cases.
## [0.20.7]
## [0.20.7]
### Changed
### Changed
* Creating a `time.When` from another `time.When` does not nest them anymore (it returns the argument)
* Creating a `time.When` from another `time.When` does not nest them anymore (it returns the argument)
@ -5,6 +5,42 @@ Learn how to run your own simulations with our [documentation](http://soilsim.re
Follow our [tutorial](examples/tutorial/soil_tutorial.ipynb) to develop your own agent models.
Follow our [tutorial](examples/tutorial/soil_tutorial.ipynb) to develop your own agent models.
# Changes in version 0.3
Version 0.3 came packed with many changes to provide much better integration with MESA.
For a long time, we tried to keep soil backwards-compatible, but it turned out to be a big endeavour and the resulting code was less readable.
This translates to harder maintenance and a worse experience for newcomers.
In the end, we decided to make some breaking changes.
If you have an older Soil simulation, you have two options:
* Update the necessary configuration files and code. You may use the examples in the `examples` folder for reference, as well as the documentation.
* Keep using a previous `soil` version.
## Mesa compatibility
Soil is in the process of becoming fully compatible with MESA.
The idea is to provide a set of modular classes and functions that extend the functionality of mesa, whilst staying compatible.
In the end, it should be possible to add regular mesa agents to a soil simulation, or use a soil agent within a mesa simulation/model.
This is a non-exhaustive list of tasks to achieve compatibility:
- [ ] Integrate `soil.Simulation` with mesa's runners:
- [ ] `soil.Simulation` could mimic/become a `mesa.batchrunner`
- [ ] Integrate `soil.Environment` with `mesa.Model`:
- [x] `Soil.Environment` inherits from `mesa.Model`
- [x] `Soil.Environment` includes a Mesa-like Scheduler (see the `soil.time` module.
- [ ] Allow for `mesa.Model` to be used in a simulation.
- [ ] Integrate `soil.Agent` with `mesa.Agent`:
- [x] Rename agent.id to unique_id?
- [x] mesa agents can be used in soil simulations (see `examples/mesa`)
- [ ] Provide examples
- [ ] Using mesa modules in a soil simulation
- [ ] Using soil modules in a mesa simulation
- [ ] Document the new APIs and usage
## Citation
## Citation
@ -31,25 +67,6 @@ If you use Soil in your research, don't forget to cite this paper:
```
```
## Mesa compatibility
Soil is in the process of becoming fully compatible with MESA.
As of this writing,
This is a non-exhaustive list of tasks to achieve compatibility:
* Environments.agents and mesa.Agent.agents are not the same. env is a property, and it only takes into account network and environment agents. Might rename environment_agents to other_agents or sth like that
- [ ] Integrate `soil.Simulation` with mesa's runners:
- [ ] `soil.Simulation` could mimic/become a `mesa.batchrunner`
- [ ] Integrate `soil.Environment` with `mesa.Model`:
- [x] `Soil.Environment` inherits from `mesa.Model`
- [x] `Soil.Environment` includes a Mesa-like Scheduler (see the `soil.time` module.
- [ ] Integrate `soil.Agent` with `mesa.Agent`:
- [x] Rename agent.id to unique_id?
- [x] mesa agents can be used in soil simulations (see `examples/mesa`)
- [ ] Document the new APIs and usage
@Copyright GSI - Universidad Politécnica de Madrid 2017-2021
@Copyright GSI - Universidad Politécnica de Madrid 2017-2021
@ -13,7 +13,7 @@ Here's an example (``example.yml``).
This example configuration will run three trials (``num_trials``) of a simulation containing a randomly generated network (``network_params``).
This example configuration will run three trials (``num_trials``) of a simulation containing a randomly generated network (``network_params``).
The 100 nodes in the network will be SISaModel agents (``network_agents.agent_type``), which is an agent behavior that is included in Soil.
The 100 nodes in the network will be SISaModel agents (``network_agents.agent_class``), which is an agent behavior that is included in Soil.
10% of the agents (``weight=1``) will start in the content state, 10% in the discontent state, and the remaining 80% (``weight=8``) in the neutral state.
10% of the agents (``weight=1``) will start in the content state, 10% in the discontent state, and the remaining 80% (``weight=8``) in the neutral state.
All agents will have access to the environment (``environment_params``), which only contains one variable, ``prob_infected``.
All agents will have access to the environment (``environment_params``), which only contains one variable, ``prob_infected``.
The state of the agents will be updated every 2 seconds (``interval``).
The state of the agents will be updated every 2 seconds (``interval``).
@ -116,7 +116,7 @@ Agents
======
======
Agents are a way of modelling behavior.
Agents are a way of modelling behavior.
Agents can be characterized with two variables: agent type (``agent_type``) and state.
Agents can be characterized with two variables: agent type (``agent_class``) and state.
The agent type is a ``soil.Agent`` class, which contains the code that encapsulates the behavior of the agent.
The agent type is a ``soil.Agent`` class, which contains the code that encapsulates the behavior of the agent.
The state is a set of variables, which may change during the simulation, and that the code may use to control the behavior.
The state is a set of variables, which may change during the simulation, and that the code may use to control the behavior.
All agents provide a ``step`` method either explicitly or implicitly (by inheriting it from a superclass), which controls how the agent will behave in each step of the simulation.
All agents provide a ``step`` method either explicitly or implicitly (by inheriting it from a superclass), which controls how the agent will behave in each step of the simulation.
@ -142,7 +142,7 @@ Hence, every node in the network will be associated to an agent of that type.
..code:: yaml
..code:: yaml
agent_type: SISaModel
agent_class: SISaModel
It is also possible to add more than one type of agent to the simulation.
It is also possible to add more than one type of agent to the simulation.
@ -152,9 +152,9 @@ For instance, with following configuration, it is five times more likely for a n
..code:: yaml
..code:: yaml
network_agents:
network_agents:
- agent_type: SISaModel
- agent_class: SISaModel
weight: 1
weight: 1
- agent_type: CounterModel
- agent_class: CounterModel
weight: 5
weight: 5
The third option is to specify the type of agent on the node itself, e.g.:
The third option is to specify the type of agent on the node itself, e.g.:
@ -165,10 +165,10 @@ The third option is to specify the type of agent on the node itself, e.g.:
topology:
topology:
nodes:
nodes:
- id: first
- id: first
agent_type: BaseAgent
agent_class: BaseAgent
states:
states:
first:
first:
agent_type: SISaModel
agent_class: SISaModel
This would also work with a randomly generated network:
This would also work with a randomly generated network:
@ -179,9 +179,9 @@ This would also work with a randomly generated network:
network:
network:
generator: complete
generator: complete
n: 5
n: 5
agent_type: BaseAgent
agent_class: BaseAgent
states:
states:
- agent_type: SISaModel
- agent_class: SISaModel
@ -192,11 +192,11 @@ e.g., to populate the network with SISaModel, roughly 10% of them with a discont
..code:: yaml
..code:: yaml
network_agents:
network_agents:
- agent_type: SISaModel
- agent_class: SISaModel
weight: 9
weight: 9
state:
state:
id: neutral
id: neutral
- agent_type: SISaModel
- agent_class: SISaModel
weight: 1
weight: 1
state:
state:
id: discontent
id: discontent
@ -206,7 +206,7 @@ For instance, to add a state for the two nodes in this configuration:
..code:: yaml
..code:: yaml
agent_type: SISaModel
agent_class: SISaModel
network:
network:
generator: complete_graph
generator: complete_graph
n: 2
n: 2
@ -231,10 +231,10 @@ These agents are programmed in much the same way as network agents, the only dif
..code::
..code::
environment_agents:
environment_agents:
- agent_type: MyAgent
- agent_class: MyAgent
state:
state:
mood: happy
mood: happy
- agent_type: DummyAgent
- agent_class: DummyAgent
You may use environment agents to model events that a normal agent cannot control, such as natural disasters or chance.
You may use environment agents to model events that a normal agent cannot control, such as natural disasters or chance.
J. Fernando Sánchez
2 years ago