mirror of
https://github.com/gsi-upm/soil
synced 2024-11-14 15:32:29 +00:00
55bbc76b2a
* Improve text * Move to docs * Autogenerate with sphinx * Fix naming issue `environment.run` (double name) * Add to tests
92 lines
4.5 KiB
Markdown
92 lines
4.5 KiB
Markdown
# [SOIL](https://github.com/gsi-upm/soil)
|
|
|
|
|
|
Soil is an extensible and user-friendly Agent-based Social Simulator for Social Networks.
|
|
Learn how to run your own simulations with our [documentation](http://soilsim.readthedocs.io).
|
|
|
|
Follow our [tutorial](docs/tutorial/soil_tutorial.ipynb) to develop your own agent models.
|
|
|
|
> **Warning**
|
|
> Soil 1.0 introduced many fundamental changes. Check the [documention on how to update your simulations to work with newer versions](docs/notes_v1.0.rst)
|
|
|
|
## Features
|
|
|
|
* Integration with (social) networks (through `networkx`)
|
|
* Convenience functions and methods to easily assign agents to your model (and optionally to its network):
|
|
* Following a given distribution (e.g., 2 agents of type `Foo`, 10% of the network should be agents of type `Bar`)
|
|
* Based on the topology of the network
|
|
* **Several types of abstractions for agents**:
|
|
* Finite state machine, where methods can be turned into a state
|
|
* Network agents, which have convenience methods to access the model's topology
|
|
* Generator-based agents, whose state is paused though a `yield` and resumed on the next step
|
|
* **Reporting and data collection**:
|
|
* Soil models include data collection and record some data by default (# of agents, state of each agent, etc.)
|
|
* All data collected are exported by default to a SQLite database and a description file
|
|
* Options to export to other formats, such as CSV, or defining your own exporters
|
|
* A summary of the data collected is shown in the command line, for easy inspection
|
|
* **An event-based scheduler**
|
|
* Agents can be explicit about when their next time/step should be, and not all agents run in every step. This avoids unnecessary computation.
|
|
* Time intervals between each step are flexible.
|
|
* There are primitives to specify when the next execution of an agent should be (or conditions)
|
|
* **Actor-inspired** message-passing
|
|
* A simulation runner (`soil.Simulation`) that can:
|
|
* Run models in parallel
|
|
* Save results to different formats
|
|
* Simulation configuration files
|
|
* A command line interface (`soil`), to quickly run simulations with different parameters
|
|
* An integrated debugger (`soil --debug`) with custom functions to print agent states and break at specific states
|
|
|
|
## Mesa compatibility
|
|
|
|
SOIL has been redesigned to integrate well with [Mesa](https://github.com/projectmesa/mesa).
|
|
For instance, it should be possible to run a `mesa.Model` models using a `soil.Simulation` and the `soil` CLI, or to integrate the `soil.TimedActivation` scheduler on a `mesa.Model`.
|
|
|
|
Note that some combinations of `mesa` and `soil` components, while technically possible, are much less useful or might yield surprising results.
|
|
For instance, you may add any `soil.agent` agent on a regular `mesa.Model` with a vanilla scheduler from `mesa.time`.
|
|
But in that case the agents will not get any of the advanced event-based scheduling, and most agent behaviors that depend on that may not work.
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
|
|
## Citation
|
|
|
|
|
|
If you use Soil in your research, don't forget to cite this paper:
|
|
|
|
```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",
|
|
}
|
|
|
|
```
|
|
|
|
@Copyright GSI - Universidad Politécnica de Madrid 2017-2021
|
|
|
|
[](https://www.gsi.upm.es)
|