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.

Follow our tutorial 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

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. 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:

@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