You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Go to file
J. Fernando Sánchez 25d042f16c v1.0.0rc11 2 months ago
benchmarks v1.0.0rc11 2 months ago
docs v1.0.0rc11 2 months ago
examples v1.0.0rc11 2 months ago
soil v1.0.0rc11 2 months ago
tests v1.0.0rc11 2 months ago
.dockerignore v0.20.8 fix bugs 1 year ago
.gitignore v0.20.8 fix bugs 1 year ago
.gitlab-ci.yml Update python version in gitlab-ci 1 year ago v1.0.0rc11 2 months ago
Dockerfile Python3.7, testing and bug fixes 6 years ago
LICENSE Create LICENSE 8 years ago 0.13.8 5 years ago
Makefile Avoid writing gexf in test 5 years ago Improve tutorial 1 year ago WIP soil 7 years ago
docker-compose.yml Python3.7, testing and bug fixes 6 years ago
logo_gsi.png added logos 8 years ago
logo_gsi.svg Added GSI logo 8 years ago
poetry.lock v1.0.0rc11 2 months ago
pyproject.toml v1.0.0rc11 2 months ago
requirements.txt Pre-release version of v1.0 1 year ago
setup.cfg Fix pre-release version of v1.0.0rc1 1 year ago Improve tutorial 1 year ago
test-requirements.txt Add jupyter to test-requirements 1 year ago


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


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


If you use Soil in your research, don't forget to cite this paper:

    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 = "",
    volume = "10349",
    year = "2017",

@Copyright GSI - Universidad Politécnica de Madrid 2017-2021