Black formatting

* Fix CLI arguments not being used when easy is passed a simulation instance
* Docs for `examples/events_and_messages/cars.py`

.dockerignore

@@ -1,7 +1,5 @@
 **/soil_output
 .*
-**/.*
 **/__pycache__
 __pycache__
 *.pyc
-**/backup

.gitignore

@@ -8,5 +8,4 @@ soil_output
 docs/_build*
 build/*
 dist/*
-prof
-backup
+prof

CHANGELOG.md

@@ -3,14 +3,21 @@ 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).
 
-## [UNRELEASED]
-
-## [0.20.8]
+## [0.30 UNRELEASED]
+### Added
+* Simple debugging capabilities in `soil.debugging`, with a custom `pdb.Debugger` subclass that exposes commands to list agents and their status and set breakpoints on states (for FSM agents). Try it with `soil --debug <simulation file>`
+* Ability to run 
+* Ability to 
+* The `soil.exporters` module to export the results of datacollectors (model.datacollector) into files at the end of trials/simulations
+* A modular set of classes for environments/models. Now the ability to configure the agents through an agent definition and a topology through a network configuration is split into two classes (`soil.agents.BaseEnvironment` for agents, `soil.agents.NetworkEnvironment` to add topology).
+* FSM agents can now have generators as states. They work similar to normal states, with one caveat. Only `time` values can be yielded, not a state. This is because the state will not change, it will be resumed after the yield, at the appropriate time. The return value *can* be a state, or a `(state, time)` tuple, just like in normal states.
 ### Changed
-* Tsih bumped to version 0.1.8
-### Fixed
-* Mentions to `id` in docs. It should be `state_id` now.
-* Fixed bug: environment agents were not being added to the simulation
+* 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
+* Ability
+### 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.
+
 
 ## [0.20.7]
 ### Changed

README.md

@@ -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.
 
+
+# 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 
 
 
@@ -31,24 +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
 
 [![SOIL](logo_gsi.png)](https://www.gsi.upm.es)

docs/configuration.rst

@@ -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``).
-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.
 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``).
@@ -88,9 +88,18 @@ For example, the following configuration is equivalent to :code:`nx.complete_gra
 
 Environment
 ============
+
 The environment is the place where the shared state of the simulation is stored.
-For instance, the probability of disease outbreak.
-The configuration file may specify the initial value of the environment parameters:
+That means both global parameters, such as the probability of disease outbreak.
+But it also means other data, such as a map, or a network topology that connects multiple agents.
+As a result, it is also typical to add custom functions in an environment that help agents interact with each other and with the state of the simulation.
+
+Last but not least, an environment controls when and how its agents will be executed.
+By default, soil environments incorporate a ``soil.time.TimedActivation`` model for agent execution (more on this on the following section).
+
+Soil environments are very similar, and often interchangeable with, mesa models (``mesa.Model``).
+
+A configuration may specify the initial value of the environment parameters:
 
 .. code:: yaml
 
@@ -98,23 +107,33 @@ The configuration file may specify the initial value of the environment paramete
         daily_probability_of_earthquake: 0.001
         number_of_earthquakes: 0
 
-All agents have access to the environment parameters.
+All agents have access to the environment (and its parameters).
 
 In some scenarios, it is useful to have a custom environment, to provide additional methods or to control the way agents update environment state.
 For example, if our agents play the lottery, the environment could provide a method to decide whether the agent wins, instead of leaving it to the agent.
 
-
 Agents
 ======
+
 Agents are a way of modelling behavior.
-Agents can be characterized with two variables: agent type (``agent_type``) and state.
-Only one agent is executed at a time (generally, every ``interval`` seconds), and it has access to its state and the environment parameters.
+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 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.
+
+When and how agent steps are executed in a simulation depends entirely on the ``environment``.
+Most environments will internally use a scheduler (``mesa.time.BaseScheduler``), which controls the activation of agents.
+
+In soil, we generally used the ``soil.time.TimedActivation`` scheduler, which allows agents to specify when their next activation will happen, defaulting to a 
+
+When an agent's step is executed (generally, every ``interval`` seconds), the agent has access to its state and the environment.
 Through the environment, it can access the network topology and the state of other agents.
 
-There are three three types of agents according to how they are added to the simulation: network agents and environment agent.
+There are two types of agents according to how they are added to the simulation: network agents and environment agent.
 
 Network Agents
 ##############
+
 Network agents are attached to a node in the topology.
 The configuration file allows you to specify how agents will be mapped to topology nodes.
 
@@ -123,17 +142,19 @@ Hence, every node in the network will be associated to an agent of that type.
 
 .. code:: yaml
 
-   agent_type: SISaModel
+   agent_class: SISaModel
 
-It is also possible to add more than one type of agent to the simulation, and to control the ratio of each type (using the ``weight`` property).
+It is also possible to add more than one type of agent to the simulation.
+
+To control the ratio of each type (using the ``weight`` property).
 For instance, with following configuration, it is five times more likely for a node to be assigned a CounterModel type than a SISaModel type.
 
 .. code:: yaml
 
     network_agents:
-          - agent_type: SISaModel
+          - agent_class: SISaModel
             weight: 1
-          - agent_type: CounterModel
+          - agent_class: CounterModel
             weight: 5
 
 The third option is to specify the type of agent on the node itself, e.g.:
@@ -144,10 +165,10 @@ The third option is to specify the type of agent on the node itself, e.g.:
    topology:
        nodes:
            - id: first
-   agent_type: BaseAgent
+   agent_class: BaseAgent
    states:
        first:
-         agent_type: SISaModel
+         agent_class: SISaModel
           
 
 This would also work with a randomly generated network:
@@ -158,9 +179,9 @@ This would also work with a randomly generated network:
    network:
        generator: complete
        n: 5
-   agent_type: BaseAgent
+   agent_class: BaseAgent
    states:
-       - agent_type: SISaModel
+       - agent_class: SISaModel
 
               
 
@@ -171,11 +192,11 @@ e.g., to populate the network with SISaModel, roughly 10% of them with a discont
 .. code:: yaml
 
     network_agents:
-        - agent_type: SISaModel
+        - agent_class: SISaModel
             weight: 9
             state:
             id: neutral
-        - agent_type: SISaModel
+        - agent_class: SISaModel
             weight: 1
             state:
             id: discontent
@@ -185,7 +206,7 @@ For instance, to add a state for the two nodes in this configuration:
 
 .. code:: yaml
 
-   agent_type: SISaModel
+   agent_class: SISaModel
    network:
       generator: complete_graph
       n: 2
@@ -210,10 +231,10 @@ These agents are programmed in much the same way as network agents, the only dif
 .. code::
 
    environment_agents:
-       - agent_type: MyAgent
+       - agent_class: MyAgent
          state:
            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.

docs/example.yml

@@ -8,15 +8,15 @@ network_params:
     n: 100
     m: 2
 network_agents:
-    - agent_type: SISaModel
+    - agent_class: SISaModel
       weight: 1
       state:
         id: content
-    - agent_type: SISaModel
+    - agent_class: SISaModel
       weight: 1
       state:
         id: discontent
-    - agent_type: SISaModel
+    - agent_class: SISaModel
       weight: 8
       state:
         id: neutral

docs/quickstart.yml

@@ -3,11 +3,11 @@ name: quickstart
 num_trials: 1
 max_time: 1000
 network_agents:
-  - agent_type: SISaModel
+  - agent_class: SISaModel
     state:
       id: neutral
     weight: 1
-  - agent_type: SISaModel
+  - agent_class: SISaModel
     state:
       id: content
     weight: 2

docs/requirements.txt

@@ -1 +1 @@
-ipython==7.31.1
+ipython>=7.31.1

docs/soil-vs.rst

@@ -0,0 +1,12 @@
+### MESA
+
+Starting with version 0.3, Soil has been redesigned to complement Mesa, while remaining compatible with it.
+That means that every component in Soil (i.e., Models, Environments, etc.) can be mixed with existing mesa components.
+In fact, there are examples that show how that integration may be used, in the `examples/mesa` folder in the repository.
+
+Here are some reasons to use Soil instead of plain mesa:
+
+- Less boilerplate for common scenarios (by some definitions of common)
+- Functions to automatically populate a topology with an agent distribution (i.e., different ratios of agent class and state)
+- The `soil.Simulation` class allows you to run multiple instances of the same experiment (i.e., multiple trials with the same parameters but a different randomness seed)
+- Reporting functions that aggregate multiple

examples/complete.yml

@@ -1,27 +1,54 @@
 ---
+version: '2'
 name: simple
 group: tests
 dir_path: "/tmp/"
 num_trials: 3
-max_time: 100
+max_steps: 100
 interval: 1
 seed: "CompleteSeed!"
-network_params:
-  generator: complete_graph
-  n: 10
-network_agents:
-  - agent_type: CounterModel
-    weight: 1
-    state:
-      state_id: 0
-  - agent_type: AggregatedCounter
-    weight: 0.2
-environment_agents: []
-environment_class: Environment
-environment_params:
+model_class: Environment
+model_params:
   am_i_complete: true
-default_state:
-  incidents: 0
-states:
-  - name: 'The first node'
-  - name: 'The second node'
+  topology:
+    params:
+      generator: complete_graph
+      n: 12
+  environment:
+  agents:
+    agent_class: CounterModel
+    topology: true
+    state:
+      times: 1
+      # In this group we are not specifying any topology
+    fixed:
+      - name: 'Environment Agent 1'
+        agent_class: BaseAgent
+        group: environment
+        topology: false
+        hidden: true
+        state:
+          times: 10
+      - agent_class: CounterModel
+        id: 0
+        group: fixed_counters
+        state:
+          times: 1
+          total: 0
+      - agent_class: CounterModel
+        group: fixed_counters
+        id: 1
+    distribution:
+      - agent_class: CounterModel
+        weight: 1
+        group: distro_counters
+        state:
+          times: 3
+      - agent_class: AggregatedCounter
+        weight: 0.2
+    override:
+      - filter:
+          agent_class: AggregatedCounter
+        n: 2
+        state:
+          times: 5

examples/custom_generator/custom_generator.yml

@@ -2,7 +2,7 @@
 name: custom-generator
 description: Using a custom generator for the network
 num_trials: 3
-max_time: 100
+max_steps: 100
 interval: 1
 network_params:
   generator: mymodule.mygenerator
@@ -10,7 +10,7 @@ network_params:
   n: 10
   n_edges: 5  
 network_agents:
-  - agent_type: CounterModel
+  - agent_class: CounterModel
     weight: 1
     state:
       state_id: 0

examples/custom_generator/mymodule.py

@@ -1,27 +1,22 @@
 from networkx import Graph
+import random
 import networkx as nx
-from random import choice
+
 
 def mygenerator(n=5, n_edges=5):
-    '''
+    """
     Just a simple generator that creates a network with n nodes and
     n_edges edges. Edges are assigned randomly, only avoiding self loops.
-    '''
+    """
     G = nx.Graph()
 
     for i in range(n):
         G.add_node(i)
-    
+
     for i in range(n_edges):
         nodes = list(G.nodes)
-        n_in = choice(nodes)
+        n_in = random.choice(nodes)
         nodes.remove(n_in)  # Avoid loops
-        n_out = choice(nodes)
+        n_out = random.choice(nodes)
         G.add_edge(n_in, n_out)
     return G
-    
-
-
-
-
-    

examples/custom_timeouts/custom_timeouts.py

@@ -2,34 +2,37 @@ from soil.agents import FSM, state, default_state
 
 
 class Fibonacci(FSM):
-    '''Agent that only executes in t_steps that are Fibonacci numbers'''
+    """Agent that only executes in t_steps that are Fibonacci numbers"""
 
-    defaults = {
-        'prev': 1
-    }
+    defaults = {"prev": 1}
 
     @default_state
     @state
     def counting(self):
-        self.log('Stopping at {}'.format(self.now))
-        prev, self['prev'] = self['prev'], max([self.now, self['prev']])
+        self.log("Stopping at {}".format(self.now))
+        prev, self["prev"] = self["prev"], max([self.now, self["prev"]])
         return None, self.env.timeout(prev)
 
+
 class Odds(FSM):
-    '''Agent that only executes in odd t_steps'''
+    """Agent that only executes in odd t_steps"""
+
     @default_state
     @state
     def odds(self):
-        self.log('Stopping at {}'.format(self.now))
-        return None, self.env.timeout(1+self.now%2)
+        self.log("Stopping at {}".format(self.now))
+        return None, self.env.timeout(1 + self.now % 2)
 
-if __name__ == '__main__':
-    import logging
-    logging.basicConfig(level=logging.INFO)
+
+if __name__ == "__main__":
     from soil import Simulation
-    s = Simulation(network_agents=[{'ids': [0], 'agent_type': Fibonacci},
-                                   {'ids': [1], 'agent_type': Odds}],
-                   network_params={"generator": "complete_graph", "n": 2},
-                   max_time=100,
-                   )
+
+    s = Simulation(
+        network_agents=[
+            {"ids": [0], "agent_class": Fibonacci},
+            {"ids": [1], "agent_class": Odds},
+        ],
+        network_params={"generator": "complete_graph", "n": 2},
+        max_time=100,
+    )
     s.run(dry_run=True)

examples/events_and_messages/README.md

@@ -0,0 +1,7 @@
+This example can be run like with command-line options, like this:
+
+```bash
+python cars.py --level DEBUG  -e summary --csv
+```
+
+This will set the `CSV` (save the agent and model data to a CSV) and `summary` (print the a summary of the data to stdout) exporters, and set the log level to DEBUG.

examples/events_and_messages/cars.py

@@ -0,0 +1,234 @@
+"""
+This is an example of a simplified city, where there are Passengers and Drivers that can take those passengers
+from their location to their desired location.
+
+An example scenario could play like the following:
+
+- Drivers start in the `wandering` state, where they wander around the city until they have been assigned a journey
+- Passenger(1) tells every driver that it wants to request a Journey.
+- Each driver receives the request.
+  If Driver(2) is interested in providing the Journey, it asks Passenger(1) to confirm that it accepts Driver(2)'s request
+- When Passenger(1) accepts the request, two things happen:
+    - Passenger(1) changes its state to `driving_home`
+    - Driver(2) starts moving towards the origin of the Journey
+- Once Driver(2) reaches the origin, it starts moving itself and Passenger(1) to the destination of the Journey
+- When Driver(2) reaches the destination (carrying Passenger(1) along):
+    - Driver(2) starts wondering again
+    - Passenger(1) dies, and is removed from the simulation
+- If there are no more passengers available in the simulation, Drivers die
+"""
+from __future__ import annotations
+from soil import *
+from soil import events
+from mesa.space import MultiGrid
+
+
+# More complex scenarios may use more than one type of message  between objects.
+# A common pattern is to use `enum.Enum` to represent state changes in a request.
+@dataclass
+class Journey:
+    """
+    This represents a request for a journey. Passengers and drivers exchange this object.
+
+    A journey may have a driver assigned or not. If the driver has not been assigned, this
+    object is considered a "request for a journey".
+    """
+
+    origin: (int, int)
+    destination: (int, int)
+    tip: float
+
+    passenger: Passenger
+    driver: Driver = None
+
+
+class City(EventedEnvironment):
+    """
+    An environment with a grid where drivers and passengers will be placed.
+
+    The number of drivers and riders is configurable through its parameters:
+
+    :param str n_cars: The total number of drivers to add
+    :param str n_passengers: The number of passengers in the simulation
+    :param list agents: Specific agents to use in the simulation. It overrides the `n_passengers`
+    and `n_cars` params.
+    :param int height: Height of the internal grid
+    :param int width: Width of the internal grid
+    """
+
+    def __init__(
+        self,
+        *args,
+        n_cars=1,
+        n_passengers=10,
+        height=100,
+        width=100,
+        agents=None,
+        model_reporters=None,
+        **kwargs,
+    ):
+        self.grid = MultiGrid(width=width, height=height, torus=False)
+        if agents is None:
+            agents = []
+            for i in range(n_cars):
+                agents.append({"agent_class": Driver})
+            for i in range(n_passengers):
+                agents.append({"agent_class": Passenger})
+        model_reporters = model_reporters or {
+            "earnings": "total_earnings",
+            "n_passengers": "number_passengers",
+        }
+        print("REPORTERS", model_reporters)
+        super().__init__(
+            *args, agents=agents, model_reporters=model_reporters, **kwargs
+        )
+        for agent in self.agents:
+            self.grid.place_agent(agent, (0, 0))
+            self.grid.move_to_empty(agent)
+
+    @property
+    def total_earnings(self):
+        return sum(d.earnings for d in self.agents(agent_class=Driver))
+
+    @property
+    def number_passengers(self):
+        return self.count_agents(agent_class=Passenger)
+
+
+class Driver(Evented, FSM):
+    pos = None
+    journey = None
+    earnings = 0
+
+    def on_receive(self, msg, sender):
+        """This is not a state. It will run (and block) every time check_messages is invoked"""
+        if self.journey is None and isinstance(msg, Journey) and msg.driver is None:
+            msg.driver = self
+            self.journey = msg
+
+    def check_passengers(self):
+        """If there are no more passengers, stop forever"""
+        c = self.count_agents(agent_class=Passenger)
+        self.info(f"Passengers left {c}")
+        if not c:
+            self.die()
+
+    @default_state
+    @state
+    def wandering(self):
+        """Move around the city until a journey is accepted"""
+        target = None
+        self.check_passengers()
+        self.journey = None
+        while self.journey is None:  # No potential journeys detected (see on_receive)
+            if target is None or not self.move_towards(target):
+                target = self.random.choice(
+                    self.model.grid.get_neighborhood(self.pos, moore=False)
+                )
+
+            self.check_passengers()
+            self.check_messages()  # This will call on_receive behind the scenes, and the agent's status will be updated
+            yield Delta(30)  # Wait at least 30 seconds before checking again
+
+        try:
+            # Re-send the journey to the passenger, to confirm that we have been selected
+            self.journey = yield self.journey.passenger.ask(self.journey, timeout=60)
+        except events.TimedOut:
+            # No journey has been accepted. Try again
+            self.journey = None
+            return
+
+        return self.driving
+
+    @state
+    def driving(self):
+        """The journey has been accepted. Pick them up and take them to their destination"""
+        while self.move_towards(self.journey.origin):
+            yield
+        while self.move_towards(self.journey.destination, with_passenger=True):
+            yield
+        self.earnings += self.journey.tip
+        self.check_passengers()
+        return self.wandering
+
+    def move_towards(self, target, with_passenger=False):
+        """Move one cell at a time towards a target"""
+        self.info(f"Moving { self.pos } -> { target }")
+        if target[0] == self.pos[0] and target[1] == self.pos[1]:
+            return False
+
+        next_pos = [self.pos[0], self.pos[1]]
+        for idx in [0, 1]:
+            if self.pos[idx] < target[idx]:
+                next_pos[idx] += 1
+                break
+            if self.pos[idx] > target[idx]:
+                next_pos[idx] -= 1
+                break
+        self.model.grid.move_agent(self, tuple(next_pos))
+        if with_passenger:
+            self.journey.passenger.pos = (
+                self.pos
+            )  # This could be communicated through messages
+        return True
+
+
+class Passenger(Evented, FSM):
+    pos = None
+
+    def on_receive(self, msg, sender):
+        """This is not a state. It will be run synchronously every time `check_messages` is run"""
+
+        if isinstance(msg, Journey):
+            self.journey = msg
+            return msg
+
+    @default_state
+    @state
+    def asking(self):
+        destination = (
+            self.random.randint(0, self.model.grid.height),
+            self.random.randint(0, self.model.grid.width),
+        )
+        self.journey = None
+        journey = Journey(
+            origin=self.pos,
+            destination=destination,
+            tip=self.random.randint(10, 100),
+            passenger=self,
+        )
+
+        timeout = 60
+        expiration = self.now + timeout
+        self.model.broadcast(journey, ttl=timeout, sender=self, agent_class=Driver)
+        while not self.journey:
+            self.info(f"Passenger at: { self.pos }. Checking for responses.")
+            try:
+                yield self.received(expiration=expiration)
+            except events.TimedOut:
+                self.info(f"Passenger at: { self.pos }. Asking for journey.")
+                self.model.broadcast(
+                    journey, ttl=timeout, sender=self, agent_class=Driver
+                )
+                expiration = self.now + timeout
+            self.check_messages()
+        return self.driving_home
+
+    @state
+    def driving_home(self):
+        while (
+            self.pos[0] != self.journey.destination[0]
+            or self.pos[1] != self.journey.destination[1]
+        ):
+            yield self.received(timeout=60)
+        self.info("Got home safe!")
+        self.die()
+
+
+simulation = Simulation(
+    name="RideHailing", model_class=City, model_params={"n_passengers": 2}
+)
+
+if __name__ == "__main__":
+    with easy(simulation) as s:
+        s.run()

examples/mesa/mesa.yml

@@ -3,19 +3,17 @@ name: mesa_sim
 group: tests
 dir_path: "/tmp"
 num_trials: 3
-max_time: 100
+max_steps: 100
 interval: 1
 seed: '1'
-network_params:
+model_class: social_wealth.MoneyEnv
+model_params:
   generator: social_wealth.graph_generator
-  n: 5
-network_agents:
-  - agent_type: social_wealth.SocialMoneyAgent
-    weight: 1
-environment_class: social_wealth.MoneyEnv
-environment_params:
-  num_mesa_agents: 5
-  mesa_agent_type: social_wealth.MoneyAgent
+  agents:
+    topology: true
+    distribution:
+      - agent_class: social_wealth.SocialMoneyAgent
+        weight: 1
   N: 10
   width: 50
   height: 50

examples/mesa/server.py

@@ -2,6 +2,7 @@ from mesa.visualization.ModularVisualization import ModularServer
 from soil.visualization import UserSettableParameter
 from mesa.visualization.modules import ChartModule, NetworkModule, CanvasGrid
 from social_wealth import MoneyEnv, graph_generator, SocialMoneyAgent
+import networkx as nx
 
 
 class MyNetwork(NetworkModule):
@@ -13,15 +14,18 @@ def network_portrayal(env):
     # The model ensures there is 0 or 1 agent per node
 
     portrayal = dict()
+    wealths = {
+        node_id: data["agent"].wealth for (node_id, data) in env.G.nodes(data=True)
+    }
     portrayal["nodes"] = [
         {
-            "id": agent_id,
-            "size": env.get_agent(agent_id).wealth,
-            # "color": "#CC0000" if not agents or agents[0].wealth == 0 else "#007959",
-            "color": "#CC0000",
-            "label": f"{agent_id}: {env.get_agent(agent_id).wealth}",
+            "id": node_id,
+            "size": 2 * (wealth + 1),
+            "color": "#CC0000" if wealth == 0 else "#007959",
+            # "color": "#CC0000",
+            "label": f"{node_id}: {wealth}",
         }
-        for (agent_id) in env.G.nodes
+        for (node_id, wealth) in wealths.items()
     ]
 
     portrayal["edges"] = [
@@ -29,7 +33,6 @@ def network_portrayal(env):
         for edge_id, (source, target) in enumerate(env.G.edges)
     ]
 
-
     return portrayal
 
 
@@ -40,7 +43,7 @@ def gridPortrayal(agent):
     :param agent:  the agent in the simulation
     :return: the portrayal dictionary
     """
-    color = max(10, min(agent.wealth*10, 100))
+    color = max(10, min(agent.wealth * 10, 100))
     return {
         "Shape": "rect",
         "w": 1,
@@ -51,11 +54,11 @@ def gridPortrayal(agent):
         "Text": agent.unique_id,
         "x": agent.pos[0],
         "y": agent.pos[1],
-        "Color": f"rgba(31, 10, 255, 0.{color})"
+        "Color": f"rgba(31, 10, 255, 0.{color})",
     }
 
 
-grid = MyNetwork(network_portrayal, 500, 500, library="sigma")
+grid = MyNetwork(network_portrayal, 500, 500)
 chart = ChartModule(
     [{"Label": "Gini", "Color": "Black"}], data_collector_name="datacollector"
 )
@@ -70,7 +73,6 @@ model_params = {
         1,
         description="Choose how many agents to include in the model",
     ),
-    "network_agents": [{"agent_type": SocialMoneyAgent}],
     "height": UserSettableParameter(
         "slider",
         "height",
@@ -79,7 +81,7 @@ model_params = {
         10,
         1,
         description="Grid height",
-        ),
+    ),
     "width": UserSettableParameter(
         "slider",
         "width",
@@ -88,13 +90,20 @@ model_params = {
         10,
         1,
         description="Grid width",
-        ),
-    "network_params": {
-        'generator': graph_generator
-    },
+    ),
+    "agent_class": UserSettableParameter(
+        "choice",
+        "Agent class",
+        value="MoneyAgent",
+        choices=["MoneyAgent", "SocialMoneyAgent"],
+    ),
+    "generator": graph_generator,
 }
 
-canvas_element = CanvasGrid(gridPortrayal, model_params["width"].value, model_params["height"].value, 500, 500)
+
+canvas_element = CanvasGrid(
+    gridPortrayal, model_params["width"].value, model_params["height"].value, 500, 500
+)
 
 
 server = ModularServer(

examples/mesa/social_wealth.py

@@ -1,23 +1,26 @@
-'''
+"""
 This is an example that adds soil agents and environment in a normal
 mesa workflow.
-'''
+"""
 from mesa import Agent as MesaAgent
 from mesa.space import MultiGrid
+
 # from mesa.time import RandomActivation
 from mesa.datacollection import DataCollector
 from mesa.batchrunner import BatchRunner
 
 import networkx as nx
 
-from soil import NetworkAgent, Environment
+from soil import NetworkAgent, Environment, serialization
+
 
 def compute_gini(model):
     agent_wealths = [agent.wealth for agent in model.agents]
     x = sorted(agent_wealths)
     N = len(list(model.agents))
-    B = sum( xi * (N-i) for i,xi in enumerate(x) ) / (N*sum(x))
-    return (1 + (1/N) - 2*B)
+    B = sum(xi * (N - i) for i, xi in enumerate(x)) / (N * sum(x))
+    return 1 + (1 / N) - 2 * B
+
 
 class MoneyAgent(MesaAgent):
     """
@@ -25,15 +28,14 @@ class MoneyAgent(MesaAgent):
     It will only share wealth with neighbors based on grid proximity
     """
 
-    def __init__(self, unique_id, model):
+    def __init__(self, unique_id, model, wealth=1):
         super().__init__(unique_id=unique_id, model=model)
-        self.wealth = 1
+        self.wealth = wealth
 
     def move(self):
         possible_steps = self.model.grid.get_neighborhood(
-            self.pos,
-            moore=True,
-            include_center=False)
+            self.pos, moore=True, include_center=False
+        )
         new_position = self.random.choice(possible_steps)
         self.model.grid.move_agent(self, new_position)
 
@@ -45,7 +47,7 @@ class MoneyAgent(MesaAgent):
             self.wealth -= 1
 
     def step(self):
-        self.info("Crying wolf", self.pos)
+        print("Crying wolf", self.pos)
         self.move()
         if self.wealth > 0:
             self.give_money()
@@ -56,10 +58,10 @@ class SocialMoneyAgent(NetworkAgent, MoneyAgent):
 
     def give_money(self):
         cellmates = set(self.model.grid.get_cell_list_contents([self.pos]))
-        friends = set(self.get_neighboring_agents())
+        friends = set(self.get_neighbors())
         self.info("Trying to give money")
-        self.debug("Cellmates: ", cellmates)
-        self.debug("Friends: ", friends)
+        self.info("Cellmates: ", cellmates)
+        self.info("Friends: ", friends)
 
         nearby_friends = list(cellmates & friends)
 
@@ -69,14 +71,35 @@ class SocialMoneyAgent(NetworkAgent, MoneyAgent):
             self.wealth -= 1
 
 
+def graph_generator(n=5):
+    G = nx.Graph()
+    for ix in range(n):
+        G.add_edge(0, ix)
+    return G
+
+
 class MoneyEnv(Environment):
     """A model with some number of agents."""
-    def __init__(self, N, width, height, *args, network_params, **kwargs):
 
-        network_params['n'] = N
-        super().__init__(*args, network_params=network_params, **kwargs)
+    def __init__(
+        self,
+        width,
+        height,
+        N,
+        generator=graph_generator,
+        agent_class=SocialMoneyAgent,
+        topology=None,
+        **kwargs
+    ):
+
+        generator = serialization.deserialize(generator)
+        agent_class = serialization.deserialize(agent_class, globs=globals())
+        topology = generator(n=N)
+        super().__init__(topology=topology, N=N, **kwargs)
         self.grid = MultiGrid(width, height, False)
 
+        self.populate_network(agent_class=agent_class)
+
         # Create agents
         for agent in self.agents:
             x = self.random.randrange(self.grid.width)
@@ -84,37 +107,31 @@ class MoneyEnv(Environment):
             self.grid.place_agent(agent, (x, y))
 
         self.datacollector = DataCollector(
-            model_reporters={"Gini": compute_gini},
-            agent_reporters={"Wealth": "wealth"})
+            model_reporters={"Gini": compute_gini}, agent_reporters={"Wealth": "wealth"}
+        )
 
 
-def graph_generator(n=5):
-    G = nx.Graph()
-    for ix in range(n):
-        G.add_edge(0, ix)
-    return G
+if __name__ == "__main__":
 
-if __name__ == '__main__':
-
-
-    G = graph_generator()
-    fixed_params = {"topology": G,
-                    "width": 10,
-                    "network_agents": [{"agent_type": SocialMoneyAgent,
-                                       'weight': 1}],
-                    "height": 10}
+    fixed_params = {
+        "generator": nx.complete_graph,
+        "width": 10,
+        "network_agents": [{"agent_class": SocialMoneyAgent, "weight": 1}],
+        "height": 10,
+    }
 
     variable_params = {"N": range(10, 100, 10)}
 
-    batch_run = BatchRunner(MoneyEnv,
-                            variable_parameters=variable_params,
-                            fixed_parameters=fixed_params,
-                            iterations=5,
-                            max_steps=100,
-                            model_reporters={"Gini": compute_gini})
+    batch_run = BatchRunner(
+        MoneyEnv,
+        variable_parameters=variable_params,
+        fixed_parameters=fixed_params,
+        iterations=5,
+        max_steps=100,
+        model_reporters={"Gini": compute_gini},
+    )
     batch_run.run_all()
 
     run_data = batch_run.get_model_vars_dataframe()
     run_data.head()
     print(run_data.Gini)
-

examples/mesa/wealth.py

@@ -4,24 +4,26 @@ from mesa.time import RandomActivation
 from mesa.datacollection import DataCollector
 from mesa.batchrunner import BatchRunner
 
+
 def compute_gini(model):
     agent_wealths = [agent.wealth for agent in model.schedule.agents]
     x = sorted(agent_wealths)
     N = model.num_agents
-    B = sum( xi * (N-i) for i,xi in enumerate(x) ) / (N*sum(x))
-    return (1 + (1/N) - 2*B)
+    B = sum(xi * (N - i) for i, xi in enumerate(x)) / (N * sum(x))
+    return 1 + (1 / N) - 2 * B
+
 
 class MoneyAgent(Agent):
-    """ An agent with fixed initial wealth."""
+    """An agent with fixed initial wealth."""
+
     def __init__(self, unique_id, model):
         super().__init__(unique_id, model)
         self.wealth = 1
 
     def move(self):
         possible_steps = self.model.grid.get_neighborhood(
-            self.pos,
-            moore=True,
-            include_center=False)
+            self.pos, moore=True, include_center=False
+        )
         new_position = self.random.choice(possible_steps)
         self.model.grid.move_agent(self, new_position)
 
@@ -37,8 +39,10 @@ class MoneyAgent(Agent):
         if self.wealth > 0:
             self.give_money()
 
+
 class MoneyModel(Model):
     """A model with some number of agents."""
+
     def __init__(self, N, width, height):
         self.num_agents = N
         self.grid = MultiGrid(width, height, True)
@@ -55,29 +59,29 @@ class MoneyModel(Model):
             self.grid.place_agent(a, (x, y))
 
         self.datacollector = DataCollector(
-            model_reporters={"Gini": compute_gini},
-            agent_reporters={"Wealth": "wealth"})
+            model_reporters={"Gini": compute_gini}, agent_reporters={"Wealth": "wealth"}
+        )
 
     def step(self):
         self.datacollector.collect(self)
         self.schedule.step()
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
 
-    fixed_params = {"width": 10,
-                    "height": 10}
+    fixed_params = {"width": 10, "height": 10}
     variable_params = {"N": range(10, 500, 10)}
 
-    batch_run = BatchRunner(MoneyModel,
-                            variable_params,
-                            fixed_params,
-                            iterations=5,
-                            max_steps=100,
-                            model_reporters={"Gini": compute_gini})
+    batch_run = BatchRunner(
+        MoneyModel,
+        variable_params,
+        fixed_params,
+        iterations=5,
+        max_steps=100,
+        model_reporters={"Gini": compute_gini},
+    )
     batch_run.run_all()
 
     run_data = batch_run.get_model_vars_dataframe()
     run_data.head()
     print(run_data.Gini)
-

examples/newsspread/NewsSpread.ipynb

@@ -2,12 +2,13 @@
  "cells": [
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": 4,
    "metadata": {
     "ExecuteTime": {
      "end_time": "2017-11-08T16:22:30.732107Z",
      "start_time": "2017-11-08T17:22:30.059855+01:00"
-    }
+    },
+    "collapsed": true
    },
    "outputs": [],
    "source": [
@@ -27,16 +28,24 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 5,
    "metadata": {
     "ExecuteTime": {
      "end_time": "2017-11-08T16:22:35.580593Z",
      "start_time": "2017-11-08T17:22:35.542745+01:00"
     }
    },
-   "outputs": [],
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Populating the interactive namespace from numpy and matplotlib\n"
+     ]
+    }
+   ],
    "source": [
-    "%matplotlib inline\n",
+    "%pylab inline\n",
     "\n",
     "from soil import *"
    ]
@@ -57,7 +66,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 6,
    "metadata": {
     "ExecuteTime": {
      "end_time": "2017-11-08T16:22:37.242327Z",
@@ -77,14 +86,14 @@
       "  prob_neighbor_spread: 0.0\r\n",
       "  prob_tv_spread: 0.01\r\n",
       "interval: 1\r\n",
-      "max_time: 300\r\n",
+      "max_time: 30\r\n",
       "name: Sim_all_dumb\r\n",
       "network_agents:\r\n",
-      "- agent_type: DumbViewer\r\n",
+      "- agent_class: DumbViewer\r\n",
       "  state:\r\n",
       "    has_tv: false\r\n",
       "  weight: 1\r\n",
-      "- agent_type: DumbViewer\r\n",
+      "- agent_class: DumbViewer\r\n",
       "  state:\r\n",
       "    has_tv: true\r\n",
       "  weight: 1\r\n",
@@ -101,22 +110,22 @@
       "  prob_neighbor_spread: 0.0\r\n",
       "  prob_tv_spread: 0.01\r\n",
       "interval: 1\r\n",
-      "max_time: 300\r\n",
+      "max_time: 30\r\n",
       "name: Sim_half_herd\r\n",
       "network_agents:\r\n",
-      "- agent_type: DumbViewer\r\n",
+      "- agent_class: DumbViewer\r\n",
       "  state:\r\n",
       "    has_tv: false\r\n",
       "  weight: 1\r\n",
-      "- agent_type: DumbViewer\r\n",
+      "- agent_class: DumbViewer\r\n",
       "  state:\r\n",
       "    has_tv: true\r\n",
       "  weight: 1\r\n",
-      "- agent_type: HerdViewer\r\n",
+      "- agent_class: HerdViewer\r\n",
       "  state:\r\n",
       "    has_tv: false\r\n",
       "  weight: 1\r\n",
-      "- agent_type: HerdViewer\r\n",
+      "- agent_class: HerdViewer\r\n",
       "  state:\r\n",
       "    has_tv: true\r\n",
       "  weight: 1\r\n",
@@ -133,18 +142,18 @@
       "  prob_neighbor_spread: 0.0\r\n",
       "  prob_tv_spread: 0.01\r\n",
       "interval: 1\r\n",
-      "max_time: 300\r\n",
+      "max_time: 30\r\n",
       "name: Sim_all_herd\r\n",
       "network_agents:\r\n",
-      "- agent_type: HerdViewer\r\n",
+      "- agent_class: HerdViewer\r\n",
       "  state:\r\n",
       "    has_tv: true\r\n",
-      "    state_id: neutral\r\n",
+      "    id: neutral\r\n",
       "  weight: 1\r\n",
-      "- agent_type: HerdViewer\r\n",
+      "- agent_class: HerdViewer\r\n",
       "  state:\r\n",
       "    has_tv: true\r\n",
-      "    state_id: neutral\r\n",
+      "    id: neutral\r\n",
       "  weight: 1\r\n",
       "network_params:\r\n",
       "  generator: barabasi_albert_graph\r\n",
@@ -160,15 +169,15 @@
       "  prob_tv_spread: 0.01\r\n",
       "  prob_neighbor_cure: 0.1\r\n",
       "interval: 1\r\n",
-      "max_time: 300\r\n",
+      "max_time: 30\r\n",
       "name: Sim_wise_herd\r\n",
       "network_agents:\r\n",
-      "- agent_type: HerdViewer\r\n",
+      "- agent_class: HerdViewer\r\n",
       "  state:\r\n",
       "    has_tv: true\r\n",
-      "    state_id: neutral\r\n",
+      "    id: neutral\r\n",
       "  weight: 1\r\n",
-      "- agent_type: WiseViewer\r\n",
+      "- agent_class: WiseViewer\r\n",
       "  state:\r\n",
       "    has_tv: true\r\n",
       "  weight: 1\r\n",
@@ -186,15 +195,15 @@
       "  prob_tv_spread: 0.01\r\n",
       "  prob_neighbor_cure: 0.1\r\n",
       "interval: 1\r\n",
-      "max_time: 300\r\n",
+      "max_time: 30\r\n",
       "name: Sim_all_wise\r\n",
       "network_agents:\r\n",
-      "- agent_type: WiseViewer\r\n",
+      "- agent_class: WiseViewer\r\n",
       "  state:\r\n",
       "    has_tv: true\r\n",
-      "    state_id: neutral\r\n",
+      "    id: neutral\r\n",
       "  weight: 1\r\n",
-      "- agent_type: WiseViewer\r\n",
+      "- agent_class: WiseViewer\r\n",
       "  state:\r\n",
       "    has_tv: true\r\n",
       "  weight: 1\r\n",
@@ -216,7 +225,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 22,
    "metadata": {
     "ExecuteTime": {
      "end_time": "2017-11-08T18:07:46.781745Z",
@@ -224,24 +233,7 @@
     },
     "scrolled": true
    },
-   "outputs": [
-    {
-     "ename": "ValueError",
-     "evalue": "No objects to concatenate",
-     "output_type": "error",
-     "traceback": [
-      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
-      "\u001b[0;31mValueError\u001b[0m                                Traceback (most recent call last)",
-      "Cell \u001b[0;32mIn[4], line 1\u001b[0m\n\u001b[0;32m----> 1\u001b[0m evodumb \u001b[38;5;241m=\u001b[39m \u001b[43manalysis\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mread_data\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;124;43m'\u001b[39;49m\u001b[38;5;124;43msoil_output/Sim_all_dumb/\u001b[39;49m\u001b[38;5;124;43m'\u001b[39;49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mprocess\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43manalysis\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mget_count\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mgroup\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[38;5;28;43;01mTrue\u001b[39;49;00m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mkeys\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43m[\u001b[49m\u001b[38;5;124;43m'\u001b[39;49m\u001b[38;5;124;43mid\u001b[39;49m\u001b[38;5;124;43m'\u001b[39;49m\u001b[43m]\u001b[49m\u001b[43m)\u001b[49m;\n",
-      "File \u001b[0;32m/mnt/data/home/j/git/lab.gsi/soil/soil/soil/analysis.py:14\u001b[0m, in \u001b[0;36mread_data\u001b[0;34m(group, *args, **kwargs)\u001b[0m\n\u001b[1;32m     12\u001b[0m iterable \u001b[38;5;241m=\u001b[39m _read_data(\u001b[38;5;241m*\u001b[39margs, \u001b[38;5;241m*\u001b[39m\u001b[38;5;241m*\u001b[39mkwargs)\n\u001b[1;32m     13\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m group:\n\u001b[0;32m---> 14\u001b[0m     \u001b[38;5;28;01mreturn\u001b[39;00m \u001b[43mgroup_trials\u001b[49m\u001b[43m(\u001b[49m\u001b[43miterable\u001b[49m\u001b[43m)\u001b[49m\n\u001b[1;32m     15\u001b[0m \u001b[38;5;28;01melse\u001b[39;00m:\n\u001b[1;32m     16\u001b[0m     \u001b[38;5;28;01mreturn\u001b[39;00m \u001b[38;5;28mlist\u001b[39m(iterable)\n",
-      "File \u001b[0;32m/mnt/data/home/j/git/lab.gsi/soil/soil/soil/analysis.py:201\u001b[0m, in \u001b[0;36mgroup_trials\u001b[0;34m(trials, aggfunc)\u001b[0m\n\u001b[1;32m    199\u001b[0m trials \u001b[38;5;241m=\u001b[39m \u001b[38;5;28mlist\u001b[39m(trials)\n\u001b[1;32m    200\u001b[0m trials \u001b[38;5;241m=\u001b[39m \u001b[38;5;28mlist\u001b[39m(\u001b[38;5;28mmap\u001b[39m(\u001b[38;5;28;01mlambda\u001b[39;00m x: x[\u001b[38;5;241m1\u001b[39m] \u001b[38;5;28;01mif\u001b[39;00m \u001b[38;5;28misinstance\u001b[39m(x, \u001b[38;5;28mtuple\u001b[39m) \u001b[38;5;28;01melse\u001b[39;00m x, trials))\n\u001b[0;32m--> 201\u001b[0m \u001b[38;5;28;01mreturn\u001b[39;00m \u001b[43mpd\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mconcat\u001b[49m\u001b[43m(\u001b[49m\u001b[43mtrials\u001b[49m\u001b[43m)\u001b[49m\u001b[38;5;241m.\u001b[39mgroupby(level\u001b[38;5;241m=\u001b[39m\u001b[38;5;241m0\u001b[39m)\u001b[38;5;241m.\u001b[39magg(aggfunc)\u001b[38;5;241m.\u001b[39mreorder_levels([\u001b[38;5;241m2\u001b[39m, \u001b[38;5;241m0\u001b[39m,\u001b[38;5;241m1\u001b[39m] ,axis\u001b[38;5;241m=\u001b[39m\u001b[38;5;241m1\u001b[39m)\n",
-      "File \u001b[0;32m/mnt/data/home/j/git/lab.gsi/soil/soil/.env-v0.20/lib/python3.8/site-packages/pandas/util/_decorators.py:331\u001b[0m, in \u001b[0;36mdeprecate_nonkeyword_arguments.<locals>.decorate.<locals>.wrapper\u001b[0;34m(*args, **kwargs)\u001b[0m\n\u001b[1;32m    325\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m \u001b[38;5;28mlen\u001b[39m(args) \u001b[38;5;241m>\u001b[39m num_allow_args:\n\u001b[1;32m    326\u001b[0m     warnings\u001b[38;5;241m.\u001b[39mwarn(\n\u001b[1;32m    327\u001b[0m         msg\u001b[38;5;241m.\u001b[39mformat(arguments\u001b[38;5;241m=\u001b[39m_format_argument_list(allow_args)),\n\u001b[1;32m    328\u001b[0m         \u001b[38;5;167;01mFutureWarning\u001b[39;00m,\n\u001b[1;32m    329\u001b[0m         stacklevel\u001b[38;5;241m=\u001b[39mfind_stack_level(),\n\u001b[1;32m    330\u001b[0m     )\n\u001b[0;32m--> 331\u001b[0m \u001b[38;5;28;01mreturn\u001b[39;00m \u001b[43mfunc\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;241;43m*\u001b[39;49m\u001b[43margs\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[38;5;241;43m*\u001b[39;49m\u001b[38;5;241;43m*\u001b[39;49m\u001b[43mkwargs\u001b[49m\u001b[43m)\u001b[49m\n",
-      "File \u001b[0;32m/mnt/data/home/j/git/lab.gsi/soil/soil/.env-v0.20/lib/python3.8/site-packages/pandas/core/reshape/concat.py:368\u001b[0m, in \u001b[0;36mconcat\u001b[0;34m(objs, axis, join, ignore_index, keys, levels, names, verify_integrity, sort, copy)\u001b[0m\n\u001b[1;32m    146\u001b[0m \u001b[38;5;129m@deprecate_nonkeyword_arguments\u001b[39m(version\u001b[38;5;241m=\u001b[39m\u001b[38;5;28;01mNone\u001b[39;00m, allowed_args\u001b[38;5;241m=\u001b[39m[\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mobjs\u001b[39m\u001b[38;5;124m\"\u001b[39m])\n\u001b[1;32m    147\u001b[0m \u001b[38;5;28;01mdef\u001b[39;00m \u001b[38;5;21mconcat\u001b[39m(\n\u001b[1;32m    148\u001b[0m     objs: Iterable[NDFrame] \u001b[38;5;241m|\u001b[39m Mapping[HashableT, NDFrame],\n\u001b[0;32m   (...)\u001b[0m\n\u001b[1;32m    157\u001b[0m     copy: \u001b[38;5;28mbool\u001b[39m \u001b[38;5;241m=\u001b[39m \u001b[38;5;28;01mTrue\u001b[39;00m,\n\u001b[1;32m    158\u001b[0m ) \u001b[38;5;241m-\u001b[39m\u001b[38;5;241m>\u001b[39m DataFrame \u001b[38;5;241m|\u001b[39m Series:\n\u001b[1;32m    159\u001b[0m \u001b[38;5;250m    \u001b[39m\u001b[38;5;124;03m\"\"\"\u001b[39;00m\n\u001b[1;32m    160\u001b[0m \u001b[38;5;124;03m    Concatenate pandas objects along a particular axis.\u001b[39;00m\n\u001b[1;32m    161\u001b[0m \n\u001b[0;32m   (...)\u001b[0m\n\u001b[1;32m    366\u001b[0m \u001b[38;5;124;03m    1   3   4\u001b[39;00m\n\u001b[1;32m    367\u001b[0m \u001b[38;5;124;03m    \"\"\"\u001b[39;00m\n\u001b[0;32m--> 368\u001b[0m     op \u001b[38;5;241m=\u001b[39m \u001b[43m_Concatenator\u001b[49m\u001b[43m(\u001b[49m\n\u001b[1;32m    369\u001b[0m \u001b[43m        \u001b[49m\u001b[43mobjs\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    370\u001b[0m \u001b[43m        \u001b[49m\u001b[43maxis\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43maxis\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    371\u001b[0m \u001b[43m        \u001b[49m\u001b[43mignore_index\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43mignore_index\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    372\u001b[0m \u001b[43m        \u001b[49m\u001b[43mjoin\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43mjoin\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    373\u001b[0m \u001b[43m        \u001b[49m\u001b[43mkeys\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43mkeys\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    374\u001b[0m \u001b[43m        \u001b[49m\u001b[43mlevels\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43mlevels\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    375\u001b[0m \u001b[43m        \u001b[49m\u001b[43mnames\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43mnames\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    376\u001b[0m \u001b[43m        \u001b[49m\u001b[43mverify_integrity\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43mverify_integrity\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    377\u001b[0m \u001b[43m        \u001b[49m\u001b[43mcopy\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43mcopy\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    378\u001b[0m \u001b[43m        \u001b[49m\u001b[43msort\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43msort\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m    379\u001b[0m \u001b[43m    \u001b[49m\u001b[43m)\u001b[49m\n\u001b[1;32m    381\u001b[0m     \u001b[38;5;28;01mreturn\u001b[39;00m op\u001b[38;5;241m.\u001b[39mget_result()\n",
-      "File \u001b[0;32m/mnt/data/home/j/git/lab.gsi/soil/soil/.env-v0.20/lib/python3.8/site-packages/pandas/core/reshape/concat.py:425\u001b[0m, in \u001b[0;36m_Concatenator.__init__\u001b[0;34m(self, objs, axis, join, keys, levels, names, ignore_index, verify_integrity, copy, sort)\u001b[0m\n\u001b[1;32m    422\u001b[0m     objs \u001b[38;5;241m=\u001b[39m \u001b[38;5;28mlist\u001b[39m(objs)\n\u001b[1;32m    424\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m \u001b[38;5;28mlen\u001b[39m(objs) \u001b[38;5;241m==\u001b[39m \u001b[38;5;241m0\u001b[39m:\n\u001b[0;32m--> 425\u001b[0m     \u001b[38;5;28;01mraise\u001b[39;00m \u001b[38;5;167;01mValueError\u001b[39;00m(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mNo objects to concatenate\u001b[39m\u001b[38;5;124m\"\u001b[39m)\n\u001b[1;32m    427\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m keys \u001b[38;5;129;01mis\u001b[39;00m \u001b[38;5;28;01mNone\u001b[39;00m:\n\u001b[1;32m    428\u001b[0m     objs \u001b[38;5;241m=\u001b[39m \u001b[38;5;28mlist\u001b[39m(com\u001b[38;5;241m.\u001b[39mnot_none(\u001b[38;5;241m*\u001b[39mobjs))\n",
-      "\u001b[0;31mValueError\u001b[0m: No objects to concatenate"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "evodumb = analysis.read_data('soil_output/Sim_all_dumb/', process=analysis.get_count, group=True, keys=['id']);"
    ]
@@ -729,9 +721,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "venv-soil",
+   "display_name": "Python 3",
    "language": "python",
-   "name": "venv-soil"
+   "name": "python3"
   },
   "language_info": {
    "codemirror_mode": {
@@ -743,7 +735,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.10"
+   "version": "3.6.2"
   },
   "toc": {
    "colors": {

examples/newsspread/NewsSpread.yml

@@ -1,19 +1,18 @@
 ---
 default_state: {}
-load_module: newsspread
 environment_agents: []
 environment_params:
   prob_neighbor_spread: 0.0
   prob_tv_spread: 0.01
 interval: 1
-max_time: 300
+max_steps: 300
 name: Sim_all_dumb
 network_agents:
-- agent_type: DumbViewer
+- agent_class: newsspread.DumbViewer
   state:
     has_tv: false
   weight: 1
-- agent_type: DumbViewer
+- agent_class: newsspread.DumbViewer
   state:
     has_tv: true
   weight: 1
@@ -24,28 +23,27 @@ network_params:
 num_trials: 50
 ---
 default_state: {}
-load_module: newsspread
 environment_agents: []
 environment_params:
   prob_neighbor_spread: 0.0
   prob_tv_spread: 0.01
 interval: 1
-max_time: 300
+max_steps: 300
 name: Sim_half_herd
 network_agents:
-- agent_type: DumbViewer
+- agent_class: newsspread.DumbViewer
   state:
     has_tv: false
   weight: 1
-- agent_type: DumbViewer
+- agent_class: newsspread.DumbViewer
   state:
     has_tv: true
   weight: 1
-- agent_type: HerdViewer
+- agent_class: newsspread.HerdViewer
   state:
     has_tv: false
   weight: 1
-- agent_type: HerdViewer
+- agent_class: newsspread.HerdViewer
   state:
     has_tv: true
   weight: 1
@@ -56,21 +54,20 @@ network_params:
 num_trials: 50
 ---
 default_state: {}
-load_module: newsspread
 environment_agents: []
 environment_params:
   prob_neighbor_spread: 0.0
   prob_tv_spread: 0.01
 interval: 1
-max_time: 300
+max_steps: 300
 name: Sim_all_herd
 network_agents:
-- agent_type: HerdViewer
+- agent_class: newsspread.HerdViewer
   state:
     has_tv: true
     state_id: neutral
   weight: 1
-- agent_type: HerdViewer
+- agent_class: newsspread.HerdViewer
   state:
     has_tv: true
     state_id: neutral
@@ -82,22 +79,21 @@ network_params:
 num_trials: 50
 ---
 default_state: {}
-load_module: newsspread
 environment_agents: []
 environment_params:
   prob_neighbor_spread: 0.0
   prob_tv_spread: 0.01
   prob_neighbor_cure: 0.1
 interval: 1
-max_time: 300
+max_steps: 300
 name: Sim_wise_herd
 network_agents:
-- agent_type: HerdViewer
+- agent_class: newsspread.HerdViewer
   state:
     has_tv: true
     state_id: neutral
   weight: 1
-- agent_type: WiseViewer
+- agent_class: newsspread.WiseViewer
   state:
     has_tv: true
   weight: 1
@@ -108,22 +104,21 @@ network_params:
 num_trials: 50
 ---
 default_state: {}
-load_module: newsspread
 environment_agents: []
 environment_params:
   prob_neighbor_spread: 0.0
   prob_tv_spread: 0.01
   prob_neighbor_cure: 0.1
 interval: 1
-max_time: 300
+max_steps: 300
 name: Sim_all_wise
 network_agents:
-- agent_type: WiseViewer
+- agent_class: newsspread.WiseViewer
   state:
     has_tv: true
     state_id: neutral
   weight: 1
-- agent_type: WiseViewer
+- agent_class: newsspread.WiseViewer
   state:
     has_tv: true
   weight: 1

examples/newsspread/newsspread.py

@@ -1,86 +1,87 @@
-from soil.agents import FSM, state, default_state, prob
+from soil.agents import FSM, NetworkAgent, state, default_state, prob
 import logging
 
 
-class DumbViewer(FSM):
-    '''
+class DumbViewer(FSM, NetworkAgent):
+    """
     A viewer that gets infected via TV (if it has one) and tries to infect
     its neighbors once it's infected.
-    '''
-    defaults = {
-        'prob_neighbor_spread': 0.5,
-        'prob_tv_spread': 0.1,
-    }
+    """
+
+    prob_neighbor_spread = 0.5
+    prob_tv_spread = 0.1
+    has_been_infected = False
 
     @default_state
     @state
     def neutral(self):
-        if self['has_tv']:
-            if prob(self.env['prob_tv_spread']):
+        if self["has_tv"]:
+            if self.prob(self.model["prob_tv_spread"]):
                 return self.infected
+        if self.has_been_infected:
+            return self.infected
 
     @state
     def infected(self):
-        for neighbor in self.get_neighboring_agents(state_id=self.neutral.id):
-            if prob(self.env['prob_neighbor_spread']):
+        for neighbor in self.get_neighbors(state_id=self.neutral.id):
+            if self.prob(self.model["prob_neighbor_spread"]):
                 neighbor.infect()
 
     def infect(self):
-        '''
+        """
         This is not a state. It is a function that other agents can use to try to
         infect this agent. DumbViewer always gets infected, but other agents like
         HerdViewer might not become infected right away
-        '''
+        """
 
-        self.set_state(self.infected)
+        self.has_been_infected = True
 
 
 class HerdViewer(DumbViewer):
-    '''
+    """
     A viewer whose probability of infection depends on the state of its neighbors.
-    '''
+    """
 
     def infect(self):
-        '''Notice again that this is NOT a state. See DumbViewer.infect for reference'''
-        infected = self.count_neighboring_agents(state_id=self.infected.id)
-        total = self.count_neighboring_agents()
-        prob_infect = self.env['prob_neighbor_spread'] * infected/total
-        self.debug('prob_infect', prob_infect)
-        if prob(prob_infect):
-            self.set_state(self.infected)
+        """Notice again that this is NOT a state. See DumbViewer.infect for reference"""
+        infected = self.count_neighbors(state_id=self.infected.id)
+        total = self.count_neighbors()
+        prob_infect = self.model["prob_neighbor_spread"] * infected / total
+        self.debug("prob_infect", prob_infect)
+        if self.prob(prob_infect):
+            self.has_been_infected = True
 
 
 class WiseViewer(HerdViewer):
-    '''
+    """
     A viewer that can change its mind.
-    '''
+    """
 
     defaults = {
-        'prob_neighbor_spread': 0.5,
-        'prob_neighbor_cure': 0.25,
-        'prob_tv_spread': 0.1,
+        "prob_neighbor_spread": 0.5,
+        "prob_neighbor_cure": 0.25,
+        "prob_tv_spread": 0.1,
     }
 
     @state
     def cured(self):
-        prob_cure = self.env['prob_neighbor_cure']
-        for neighbor in self.get_neighboring_agents(state_id=self.infected.id):
-            if prob(prob_cure):
+        prob_cure = self.model["prob_neighbor_cure"]
+        for neighbor in self.get_neighbors(state_id=self.infected.id):
+            if self.prob(prob_cure):
                 try:
                     neighbor.cure()
                 except AttributeError:
-                    self.debug('Viewer {} cannot be cured'.format(neighbor.id))
+                    self.debug("Viewer {} cannot be cured".format(neighbor.id))
 
     def cure(self):
-        self.set_state(self.cured.id)
+        self.has_been_cured = True
 
     @state
     def infected(self):
-        cured = max(self.count_neighboring_agents(self.cured.id),
-                    1.0)
-        infected = max(self.count_neighboring_agents(self.infected.id),
-                       1.0)
-        prob_cure = self.env['prob_neighbor_cure'] * (cured/infected)
-        if prob(prob_cure):
+        if self.has_been_cured:
+            return self.cured
+        cured = max(self.count_neighbors(self.cured.id), 1.0)
+        infected = max(self.count_neighbors(self.infected.id), 1.0)
+        prob_cure = self.model["prob_neighbor_cure"] * (cured / infected)
+        if self.prob(prob_cure):
             return self.cured
-        return self.set_state(super().infected)

examples/programmatic/programmatic.py

@@ -1,6 +1,6 @@
-'''
+"""
 Example of a fully programmatic simulation, without definition files.
-'''
+"""
 from soil import Simulation, agents
 from networkx import Graph
 import logging
@@ -14,21 +14,22 @@ def mygenerator():
 
 
 class MyAgent(agents.FSM):
-
     @agents.default_state
     @agents.state
     def neutral(self):
-        self.debug('I am running')
+        self.debug("I am running")
         if agents.prob(0.2):
-            self.info('This runs 2/10 times on average')
+            self.info("This runs 2/10 times on average")
 
 
-s = Simulation(name='Programmatic',
-               network_params={'generator': mygenerator},
-               num_trials=1,
-               max_time=100,
-               agent_type=MyAgent,
-               dry_run=True)
+s = Simulation(
+    name="Programmatic",
+    network_params={"generator": mygenerator},
+    num_trials=1,
+    max_time=100,
+    agent_class=MyAgent,
+    dry_run=True,
+)
 
 
 # By default, logging will only print WARNING logs (and above).

examples/pubcrawl/pubcrawl.py

@@ -1,12 +1,12 @@
-from soil.agents import FSM, state, default_state
+from soil.agents import FSM, NetworkAgent, state, default_state
 from soil import Environment
-from random import random, shuffle
 from itertools import islice
 import logging
 
 
 class CityPubs(Environment):
-    '''Environment with Pubs'''
+    """Environment with Pubs"""
+
     level = logging.INFO
 
     def __init__(self, *args, number_of_pubs=3, pub_capacity=10, **kwargs):
@@ -14,70 +14,70 @@ class CityPubs(Environment):
         pubs = {}
         for i in range(number_of_pubs):
             newpub = {
-                'name': 'The awesome pub #{}'.format(i),
-                'open': True,
-                'capacity': pub_capacity,
-                'occupancy': 0,
+                "name": "The awesome pub #{}".format(i),
+                "open": True,
+                "capacity": pub_capacity,
+                "occupancy": 0,
             }
-            pubs[newpub['name']] = newpub
-        self['pubs'] = pubs
+            pubs[newpub["name"]] = newpub
+        self["pubs"] = pubs
 
     def enter(self, pub_id, *nodes):
-        '''Agents will try to enter. The pub checks if it is possible'''
+        """Agents will try to enter. The pub checks if it is possible"""
         try:
-            pub = self['pubs'][pub_id]
+            pub = self["pubs"][pub_id]
         except KeyError:
-            raise ValueError('Pub {} is not available'.format(pub_id))
-        if not pub['open'] or (pub['capacity'] < (len(nodes) + pub['occupancy'])):
+            raise ValueError("Pub {} is not available".format(pub_id))
+        if not pub["open"] or (pub["capacity"] < (len(nodes) + pub["occupancy"])):
             return False
-        pub['occupancy'] += len(nodes)
+        pub["occupancy"] += len(nodes)
         for node in nodes:
-            node['pub'] = pub_id
+            node["pub"] = pub_id
         return True
 
     def available_pubs(self):
-        for pub in self['pubs'].values():
-            if pub['open'] and (pub['occupancy'] < pub['capacity']):
-                yield pub['name']
+        for pub in self["pubs"].values():
+            if pub["open"] and (pub["occupancy"] < pub["capacity"]):
+                yield pub["name"]
 
     def exit(self, pub_id, *node_ids):
-        '''Agents will notify the pub they want to leave'''
+        """Agents will notify the pub they want to leave"""
         try:
-            pub = self['pubs'][pub_id]
+            pub = self["pubs"][pub_id]
         except KeyError:
-            raise ValueError('Pub {} is not available'.format(pub_id))
+            raise ValueError("Pub {} is not available".format(pub_id))
         for node_id in node_ids:
             node = self.get_agent(node_id)
-            if pub_id == node['pub']:
-                del node['pub']
-                pub['occupancy'] -= 1
+            if pub_id == node["pub"]:
+                del node["pub"]
+                pub["occupancy"] -= 1
 
 
-class Patron(FSM):
-    '''Agent that looks for friends to drink with. It will do three things:
-        1) Look for other patrons to drink with
-        2) Look for a bar where the agent and other agents in the same group can get in.
-        3) While in the bar, patrons only drink, until they get drunk and taken home.
-    '''
+class Patron(FSM, NetworkAgent):
+    """Agent that looks for friends to drink with. It will do three things:
+    1) Look for other patrons to drink with
+    2) Look for a bar where the agent and other agents in the same group can get in.
+    3) While in the bar, patrons only drink, until they get drunk and taken home.
+    """
+
     level = logging.DEBUG
 
-    defaults = {
-        'pub': None,
-        'drunk': False,
-        'pints': 0,
-        'max_pints': 3,
-    }
+    pub = None
+    drunk = False
+    pints = 0
+    max_pints = 3
+    kicked_out = False
 
     @default_state
     @state
     def looking_for_friends(self):
-        '''Look for friends to drink with'''
-        self.info('I am looking for friends')
-        available_friends = list(self.get_agents(drunk=False,
-                                                 pub=None,
-                                                 state_id=self.looking_for_friends.id))
+        """Look for friends to drink with"""
+        self.info("I am looking for friends")
+        available_friends = list(
+            self.get_agents(drunk=False, pub=None, state_id=self.looking_for_friends.id)
+        )
         if not available_friends:
-            self.info('Life sucks and I\'m alone!')
+            self.info("Life sucks and I'm alone!")
             return self.at_home
         befriended = self.try_friends(available_friends)
         if befriended:
@@ -85,91 +85,91 @@ class Patron(FSM):
 
     @state
     def looking_for_pub(self):
-        '''Look for a pub that accepts me and my friends'''
-        if self['pub'] != None:
+        """Look for a pub that accepts me and my friends"""
+        if self["pub"] != None:
             return self.sober_in_pub
-        self.debug('I am looking for a pub')
-        group = list(self.get_neighboring_agents())
-        for pub in self.env.available_pubs():
-            self.debug('We\'re trying to get into {}: total: {}'.format(pub, len(group)))
-            if self.env.enter(pub, self, *group):
-                self.info('We\'re all {} getting in {}!'.format(len(group), pub))
+        self.debug("I am looking for a pub")
+        group = list(self.get_neighbors())
+        for pub in self.model.available_pubs():
+            self.debug("We're trying to get into {}: total: {}".format(pub, len(group)))
+            if self.model.enter(pub, self, *group):
+                self.info("We're all {} getting in {}!".format(len(group), pub))
                 return self.sober_in_pub
 
     @state
     def sober_in_pub(self):
-        '''Drink up.'''
+        """Drink up."""
         self.drink()
-        if self['pints'] > self['max_pints']:
+        if self["pints"] > self["max_pints"]:
             return self.drunk_in_pub
 
     @state
     def drunk_in_pub(self):
-        '''I'm out. Take me home!'''
-        self.info('I\'m so drunk. Take me home!')
-        self['drunk'] = True
-        pass  # out drunk
+        """I'm out. Take me home!"""
+        self.info("I'm so drunk. Take me home!")
+        self["drunk"] = True
+        if self.kicked_out:
+            return self.at_home
+        pass  # out drun
 
     @state
     def at_home(self):
-        '''The end'''
+        """The end"""
         others = self.get_agents(state_id=Patron.at_home.id, limit_neighbors=True)
-        self.debug('I\'m home. Just like {} of my friends'.format(len(others)))
-    
+        self.debug("I'm home. Just like {} of my friends".format(len(others)))
+
     def drink(self):
-        self['pints'] += 1
-        self.debug('Cheers to that')
-    
+        self["pints"] += 1
+        self.debug("Cheers to that")
+
     def kick_out(self):
-        self.set_state(self.at_home)
+        self.kicked_out = True
 
     def befriend(self, other_agent, force=False):
-        '''
+        """
         Try to become friends with another agent. The chances of
         success depend on both agents' openness.
-        '''
-        if force or self['openness'] > random():
-            self.env.add_edge(self, other_agent)
-            self.info('Made some friend {}'.format(other_agent))
+        """
+        if force or self["openness"] > self.random.random():
+            self.add_edge(self, other_agent)
+            self.info("Made some friend {}".format(other_agent))
             return True
         return False
 
     def try_friends(self, others):
-        ''' Look for random agents around me and try to befriend them'''
+        """Look for random agents around me and try to befriend them"""
         befriended = False
-        k = int(10*self['openness'])
-        shuffle(others)
+        k = int(10 * self["openness"])
+        self.random.shuffle(others)
         for friend in islice(others, k):  # random.choice >= 3.7
             if friend == self:
                 continue
             if friend.befriend(self):
                 self.befriend(friend, force=True)
-                self.debug('Hooray! new friend: {}'.format(friend.id))
+                self.debug("Hooray! new friend: {}".format(friend.id))
                 befriended = True
             else:
-                self.debug('{} does not want to be friends'.format(friend.id))
+                self.debug("{} does not want to be friends".format(friend.id))
         return befriended
 
 
 class Police(FSM):
-    '''Simple agent to take drunk people out of pubs.'''
+    """Simple agent to take drunk people out of pubs."""
+
     level = logging.INFO
 
     @default_state
     @state
     def patrol(self):
-        drunksters = list(self.get_agents(drunk=True,
-                                          state_id=Patron.drunk_in_pub.id))
+        drunksters = list(self.get_agents(drunk=True, state_id=Patron.drunk_in_pub.id))
         for drunk in drunksters:
-            self.info('Kicking out the trash: {}'.format(drunk.id))
+            self.info("Kicking out the trash: {}".format(drunk.id))
             drunk.kick_out()
         else:
-            self.info('No trash to take out. Too bad.')
+            self.info("No trash to take out. Too bad.")
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     from soil import simulation
-    simulation.run_from_config('pubcrawl.yml',
-                               dry_run=True,
-                               dump=None,
-                               parallel=False)
+
+    simulation.run_from_config("pubcrawl.yml", dry_run=True, dump=None, parallel=False)

examples/pubcrawl/pubcrawl.yml

@@ -1,25 +1,25 @@
 ---
 name: pubcrawl
 num_trials: 3
-max_time: 10
+max_steps: 10
 dump: false
 network_params:
   # Generate 100 empty nodes. They will be assigned a network agent
   generator: empty_graph
   n: 30
 network_agents:
-  - agent_type: pubcrawl.Patron
+  - agent_class: pubcrawl.Patron
     description: Extroverted patron
     state:
       openness: 1.0
     weight: 9
-  - agent_type: pubcrawl.Patron
+  - agent_class: pubcrawl.Patron
     description: Introverted patron
     state:
       openness: 0.1
     weight: 1
 environment_agents:
-  - agent_type: pubcrawl.Police
+  - agent_class: pubcrawl.Police
 environment_class: pubcrawl.CityPubs
 environment_params:
   altercations: 0

examples/rabbits/README.md

@@ -0,0 +1,14 @@
+There are two similar implementations of this simulation.
+
+- `basic`. Using simple primites
+- `improved`. Using more advanced features such as the `time` module to avoid unnecessary computations (i.e., skip steps), and generator functions.
+
+The examples can be run directly in the terminal, and they accept command like arguments.
+For example, to enable the CSV exporter and the Summary exporter, while setting `max_time` to `100` and `seed` to `CustomSeed`:
+
+```
+python rabbit_agents.py  --set max_time=100 --csv -e summary  --set 'seed="CustomSeed"'
+```
+
+To learn more about how this functionality works, check out the `soil.easy` function.
+

examples/rabbits/basic/rabbit_agents.py

@@ -0,0 +1,150 @@
+from soil import FSM, state, default_state, BaseAgent, NetworkAgent, Environment
+from collections import Counter
+import logging
+import math
+
+
+class RabbitEnv(Environment):
+    @property
+    def num_rabbits(self):
+        return self.count_agents(agent_class=Rabbit)
+
+    @property
+    def num_males(self):
+        return self.count_agents(agent_class=Male)
+
+    @property
+    def num_females(self):
+        return self.count_agents(agent_class=Female)
+
+
+class Rabbit(NetworkAgent, FSM):
+
+    sexual_maturity = 30
+    life_expectancy = 300
+
+    @default_state
+    @state
+    def newborn(self):
+        self.info("I am a newborn.")
+        self.age = 0
+        self.offspring = 0
+        return self.youngling
+
+    @state
+    def youngling(self):
+        self.age += 1
+        if self.age >= self.sexual_maturity:
+            self.info(f"I am fertile! My age is {self.age}")
+            return self.fertile
+
+    @state
+    def fertile(self):
+        raise Exception("Each subclass should define its fertile state")
+
+    @state
+    def dead(self):
+        self.die()
+
+
+class Male(Rabbit):
+    max_females = 5
+    mating_prob = 0.001
+
+    @state
+    def fertile(self):
+        self.age += 1
+
+        if self.age > self.life_expectancy:
+            return self.dead
+
+        # Males try to mate
+        for f in self.model.agents(
+            agent_class=Female, state_id=Female.fertile.id, limit=self.max_females
+        ):
+            self.debug("FOUND A FEMALE: ", repr(f), self.mating_prob)
+            if self.prob(self["mating_prob"]):
+                f.impregnate(self)
+                break  # Take a break
+
+
+class Female(Rabbit):
+    gestation = 10
+    pregnancy = -1
+
+    @state
+    def fertile(self):
+        # Just wait for a Male
+        self.age += 1
+        if self.age > self.life_expectancy:
+            return self.dead
+        if self.pregnancy >= 0:
+            return self.pregnant
+
+    def impregnate(self, male):
+        self.info(f"impregnated by {repr(male)}")
+        self.mate = male
+        self.pregnancy = 0
+        self.number_of_babies = int(8 + 4 * self.random.random())
+
+    @state
+    def pregnant(self):
+        self.info("I am pregnant")
+        self.age += 1
+
+        if self.age >= self.life_expectancy:
+            return self.die()
+
+        if self.pregnancy < self.gestation:
+            self.pregnancy += 1
+            return
+
+        self.info("Having {} babies".format(self.number_of_babies))
+        for i in range(self.number_of_babies):
+            state = {}
+            agent_class = self.random.choice([Male, Female])
+            child = self.model.add_node(agent_class=agent_class, **state)
+            child.add_edge(self)
+            try:
+                child.add_edge(self.mate)
+                self.model.agents[self.mate].offspring += 1
+            except ValueError:
+                self.debug("The father has passed away")
+
+            self.offspring += 1
+        self.mate = None
+        self.pregnancy = -1
+        return self.fertile
+
+    def die(self):
+        if "pregnancy" in self and self["pregnancy"] > -1:
+            self.info("A mother has died carrying a baby!!")
+        return super().die()
+
+
+class RandomAccident(BaseAgent):
+    def step(self):
+        rabbits_alive = self.model.G.number_of_nodes()
+
+        if not rabbits_alive:
+            return self.die()
+
+        prob_death = self.model.get("prob_death", 1e-100) * math.floor(
+            math.log10(max(1, rabbits_alive))
+        )
+        self.debug("Killing some rabbits with prob={}!".format(prob_death))
+        for i in self.iter_agents(agent_class=Rabbit):
+            if i.state_id == i.dead.id:
+                continue
+            if self.prob(prob_death):
+                self.info("I killed a rabbit: {}".format(i.id))
+                rabbits_alive -= 1
+                i.die()
+        self.debug("Rabbits alive: {}".format(rabbits_alive))
+
+
+if __name__ == "__main__":
+    from soil import easy
+
+    with easy("rabbits.yml") as sim:
+        sim.run()

examples/rabbits/basic/rabbits.yml

@@ -0,0 +1,42 @@
+---
+version: '2'
+name: rabbits_basic
+num_trials: 1
+seed: MySeed
+description: null
+group: null
+interval: 1.0
+max_time: 100
+model_class: rabbit_agents.RabbitEnv
+model_params:
+  agents:
+    topology: true
+    distribution:
+    - agent_class: rabbit_agents.Male
+      weight: 1
+    - agent_class: rabbit_agents.Female
+      weight: 1
+    fixed:
+    - agent_class: rabbit_agents.RandomAccident
+      topology: false
+      hidden: true
+      state:
+        group: environment
+    state:
+      group: network
+      mating_prob: 0.1
+  prob_death: 0.001
+  topology:
+    fixed:
+      directed: true
+      links: []
+      nodes:
+      - id: 1
+      - id: 0
+  model_reporters:
+    num_males: 'num_males'
+    num_females: 'num_females'
+    num_rabbits: |
+      py:lambda env: env.num_males + env.num_females
+extra:
+  visualization_params: {}

examples/rabbits/improved/rabbit_agents.py

@@ -0,0 +1,157 @@
+from soil import FSM, state, default_state, BaseAgent, NetworkAgent, Environment
+from soil.time import Delta
+from enum import Enum
+from collections import Counter
+import logging
+import math
+
+
+class RabbitEnv(Environment):
+    @property
+    def num_rabbits(self):
+        return self.count_agents(agent_class=Rabbit)
+
+    @property
+    def num_males(self):
+        return self.count_agents(agent_class=Male)
+
+    @property
+    def num_females(self):
+        return self.count_agents(agent_class=Female)
+
+
+class Rabbit(FSM, NetworkAgent):
+
+    sexual_maturity = 30
+    life_expectancy = 300
+    birth = None
+
+    @property
+    def age(self):
+        if self.birth is None:
+            return None
+        return self.now - self.birth
+
+    @default_state
+    @state
+    def newborn(self):
+        self.info("I am a newborn.")
+        self.birth = self.now
+        self.offspring = 0
+        return self.youngling, Delta(self.sexual_maturity - self.age)
+
+    @state
+    def youngling(self):
+        if self.age >= self.sexual_maturity:
+            self.info(f"I am fertile! My age is {self.age}")
+            return self.fertile
+
+    @state
+    def fertile(self):
+        raise Exception("Each subclass should define its fertile state")
+
+    @state
+    def dead(self):
+        self.die()
+
+
+class Male(Rabbit):
+    max_females = 5
+    mating_prob = 0.001
+
+    @state
+    def fertile(self):
+        if self.age > self.life_expectancy:
+            return self.dead
+
+        # Males try to mate
+        for f in self.model.agents(
+            agent_class=Female, state_id=Female.fertile.id, limit=self.max_females
+        ):
+            self.debug("FOUND A FEMALE: ", repr(f), self.mating_prob)
+            if self.prob(self["mating_prob"]):
+                f.impregnate(self)
+                break  # Do not try to impregnate other females
+
+
+class Female(Rabbit):
+    gestation = 10
+    conception = None
+
+    @state
+    def fertile(self):
+        # Just wait for a Male
+        if self.age > self.life_expectancy:
+            return self.dead
+        if self.conception is not None:
+            return self.pregnant
+
+    @property
+    def pregnancy(self):
+        if self.conception is None:
+            return None
+        return self.now - self.conception
+
+    def impregnate(self, male):
+        self.info(f"impregnated by {repr(male)}")
+        self.mate = male
+        self.conception = self.now
+        self.number_of_babies = int(8 + 4 * self.random.random())
+
+    @state
+    def pregnant(self):
+        self.debug("I am pregnant")
+
+        if self.age > self.life_expectancy:
+            self.info("Dying before giving birth")
+            return self.die()
+
+        if self.pregnancy >= self.gestation:
+            self.info("Having {} babies".format(self.number_of_babies))
+            for i in range(self.number_of_babies):
+                state = {}
+                agent_class = self.random.choice([Male, Female])
+                child = self.model.add_node(agent_class=agent_class, **state)
+                child.add_edge(self)
+                if self.mate:
+                    child.add_edge(self.mate)
+                    self.mate.offspring += 1
+                else:
+                    self.debug("The father has passed away")
+
+                self.offspring += 1
+            self.mate = None
+            return self.fertile
+
+    def die(self):
+        if self.pregnancy is not None:
+            self.info("A mother has died carrying a baby!!")
+        return super().die()
+
+
+class RandomAccident(BaseAgent):
+    def step(self):
+        rabbits_alive = self.model.G.number_of_nodes()
+
+        if not rabbits_alive:
+            return self.die()
+
+        prob_death = self.model.get("prob_death", 1e-100) * math.floor(
+            math.log10(max(1, rabbits_alive))
+        )
+        self.debug("Killing some rabbits with prob={}!".format(prob_death))
+        for i in self.iter_agents(agent_class=Rabbit):
+            if i.state_id == i.dead.id:
+                continue
+            if self.prob(prob_death):
+                self.info("I killed a rabbit: {}".format(i.id))
+                rabbits_alive -= 1
+                i.die()
+        self.debug("Rabbits alive: {}".format(rabbits_alive))
+
+
+if __name__ == "__main__":
+    from soil import easy
+
+    with easy("rabbits.yml") as sim:
+        sim.run()

examples/rabbits/improved/rabbits.yml

@@ -0,0 +1,42 @@
+---
+version: '2'
+name: rabbits_improved
+num_trials: 1
+seed: MySeed
+description: null
+group: null
+interval: 1.0
+max_time: 100
+model_class: rabbit_agents.RabbitEnv
+model_params:
+  agents:
+    topology: true
+    distribution:
+    - agent_class: rabbit_agents.Male
+      weight: 1
+    - agent_class: rabbit_agents.Female
+      weight: 1
+    fixed:
+    - agent_class: rabbit_agents.RandomAccident
+      topology: false
+      hidden: true
+      state:
+        group: environment
+    state:
+      group: network
+      mating_prob: 0.1
+  prob_death: 0.001
+  topology:
+    fixed:
+      directed: true
+      links: []
+      nodes:
+      - id: 1
+      - id: 0
+  model_reporters:
+    num_males: 'num_males'
+    num_females: 'num_females'
+    num_rabbits: |
+      py:lambda env: env.num_males + env.num_females
+extra:
+  visualization_params: {}

examples/rabbits/rabbit_agents.py

@@ -1,135 +0,0 @@
-from soil.agents import FSM, state, default_state, BaseAgent, NetworkAgent
-from enum import Enum
-from random import random, choice
-import logging
-import math
-
-
-class Genders(Enum):
-    male = 'male'
-    female = 'female'
-
-
-class RabbitModel(FSM):
-
-    defaults = {
-        'age': 0,
-        'gender': Genders.male.value,
-        'mating_prob': 0.001,
-        'offspring': 0,
-    }
-
-    sexual_maturity = 3 #4*30
-    life_expectancy = 365 * 3
-    gestation = 33
-    pregnancy = -1
-    max_females = 5
-
-    @default_state
-    @state
-    def newborn(self):
-        self.debug(f'I am a newborn at age {self["age"]}')
-        self['age'] += 1
-
-        if self['age'] >= self.sexual_maturity:
-            self.debug('I am fertile!')
-            return self.fertile
-    @state
-    def fertile(self):
-        raise Exception("Each subclass should define its fertile state")
-
-    @state
-    def dead(self):
-        self.info('Agent {} is dying'.format(self.id))
-        self.die()
-
-
-class Male(RabbitModel):
-
-    @state
-    def fertile(self):
-        self['age'] += 1
-        if self['age'] > self.life_expectancy:
-            return self.dead
-
-        if self['gender'] == Genders.female.value:
-            return
-
-        # Males try to mate
-        for f in self.get_agents(state_id=Female.fertile.id,
-                                 agent_type=Female,
-                                 limit_neighbors=False,
-                                 limit=self.max_females):
-            r = random()
-            if r < self['mating_prob']:
-                self.impregnate(f)
-                break # Take a break
-    def impregnate(self, whom):
-        whom['pregnancy'] = 0
-        whom['mate'] = self.id
-        whom.set_state(whom.pregnant)
-        self.debug('{} impregnating: {}. {}'.format(self.id, whom.id, whom.state))
-
-class Female(RabbitModel):
-    @state
-    def fertile(self):
-        # Just wait for a Male
-        pass
-
-    @state
-    def pregnant(self):
-        self['age'] += 1
-        if self['age'] > self.life_expectancy:
-            return self.dead
-
-        self['pregnancy'] += 1
-        self.debug('Pregnancy: {}'.format(self['pregnancy']))
-        if self['pregnancy'] >= self.gestation:
-            number_of_babies = int(8+4*random())
-            self.info('Having {} babies'.format(number_of_babies))
-            for i in range(number_of_babies):
-                state = {}
-                state['gender'] = choice(list(Genders)).value
-                child = self.env.add_node(self.__class__, state)
-                self.env.add_edge(self.id, child.id)
-                self.env.add_edge(self['mate'], child.id)
-                # self.add_edge()
-                self.debug('A BABY IS COMING TO LIFE')
-                self.env['rabbits_alive'] = self.env.get('rabbits_alive', self.topology.number_of_nodes())+1
-                self.debug('Rabbits alive: {}'.format(self.env['rabbits_alive']))
-                self['offspring'] += 1
-                self.env.get_agent(self['mate'])['offspring'] += 1
-            del self['mate']
-            self['pregnancy'] = -1
-            return self.fertile
-
-    @state
-    def dead(self):
-        super().dead()
-        if 'pregnancy' in self and self['pregnancy'] > -1:
-            self.info('A mother has died carrying a baby!!')
-
-
-class RandomAccident(NetworkAgent):
-
-    level = logging.DEBUG
-
-    def step(self):
-        rabbits_total = self.topology.number_of_nodes()
-        if 'rabbits_alive' not in self.env:
-            self.env['rabbits_alive'] = 0
-        rabbits_alive = self.env.get('rabbits_alive', rabbits_total)
-        prob_death = self.env.get('prob_death', 1e-100)*math.floor(math.log10(max(1, rabbits_alive)))
-        self.debug('Killing some rabbits with prob={}!'.format(prob_death))
-        for i in self.env.network_agents:
-            if i.state['id'] == i.dead.id:
-                continue
-            r = random()
-            if r < prob_death:
-                self.debug('I killed a rabbit: {}'.format(i.id))
-                rabbits_alive = self.env['rabbits_alive'] = rabbits_alive -1
-                self.log('Rabbits alive: {}'.format(self.env['rabbits_alive']))
-                i.set_state(i.dead)
-        self.log('Rabbits alive: {}/{}'.format(rabbits_alive, rabbits_total))
-        if self.count_agents(state_id=RabbitModel.dead.id) == self.topology.number_of_nodes():
-            self.die()

examples/rabbits/rabbits.yml

@@ -1,21 +0,0 @@
----
-load_module: rabbit_agents
-name: rabbits_example
-max_time: 1000
-interval: 1
-seed: MySeed
-agent_type: rabbit_agents.RabbitModel
-environment_agents:
-    - agent_type: rabbit_agents.RandomAccident
-environment_params:
-  prob_death: 0.001
-default_state:
-  mating_prob: 0.1
-topology:
-  nodes:
-    - id: 1
-      agent_type: rabbit_agents.Male
-    - id: 0
-      agent_type: rabbit_agents.Female
-  directed: true
-  links: []

examples/random_delays/random_delays.py

@@ -1,45 +1,43 @@
-'''
+"""
 Example of setting a 
 Example of a fully programmatic simulation, without definition files.
-'''
+"""
 from soil import Simulation, agents
 from soil.time import Delta
-from random import expovariate
-import logging
-
 
 
 class MyAgent(agents.FSM):
-    '''
+    """
     An agent that first does a ping
-    '''
+    """
 
-    defaults = {'pong_counts': 2}
+    defaults = {"pong_counts": 2}
 
     @agents.default_state
     @agents.state
     def ping(self):
-        self.info('Ping')
-        return self.pong, Delta(expovariate(1/16))
+        self.info("Ping")
+        return self.pong, Delta(self.random.expovariate(1 / 16))
 
     @agents.state
     def pong(self):
-        self.info('Pong')
+        self.info("Pong")
         self.pong_counts -= 1
         self.info(str(self.pong_counts))
         if self.pong_counts < 1:
             return self.die()
-        return None, Delta(expovariate(1/16))
+        return None, Delta(self.random.expovariate(1 / 16))
 
 
-s = Simulation(name='Programmatic',
-               network_agents=[{'agent_type': MyAgent, 'id': 0}],
-               topology={'nodes': [{'id': 0}], 'links': []},
-               num_trials=1,
-               max_time=100,
-               agent_type=MyAgent,
-               dry_run=True)
+s = Simulation(
+    name="Programmatic",
+    network_agents=[{"agent_class": MyAgent, "id": 0}],
+    topology={"nodes": [{"id": 0}], "links": []},
+    num_trials=1,
+    max_time=100,
+    agent_class=MyAgent,
+    dry_run=True,
+)
 
 
-logging.basicConfig(level=logging.INFO)
 envs = s.run()

examples/template.yml

@@ -6,20 +6,20 @@ template:
   group: simple
   num_trials: 1
   interval: 1
-  max_time: 2
+  max_steps: 2
   seed: "CompleteSeed!"
   dump: false
-  network_params:
-    generator: complete_graph
-    n: 10
-  network_agents:
-    - agent_type: CounterModel
-      weight: "{{ x1 }}"
-      state:
-        state_id: 0
-    - agent_type: AggregatedCounter
-      weight: "{{ 1 - x1 }}"
-  environment_params:
+  model_params:
+    network_params:
+      generator: complete_graph
+      n: 10
+    network_agents:
+      - agent_class: CounterModel
+        weight: "{{ x1 }}"
+        state:
+          state_id: 0
+      - agent_class: AggregatedCounter
+        weight: "{{ 1 - x1 }}"
     name: "{{ x3 }}"
   skip_test: true
 vars:

examples/terrorism/TerroristNetworkModel.py

@@ -1,4 +1,3 @@
-import random
 import networkx as nx
 from soil.agents import Geo, NetworkAgent, FSM, state, default_state
 from soil import Environment
@@ -21,56 +20,83 @@ class TerroristSpreadModel(FSM, Geo):
     def __init__(self, model=None, unique_id=0, state=()):
         super().__init__(model=model, unique_id=unique_id, state=state)
 
-        self.information_spread_intensity = model.environment_params['information_spread_intensity']
-        self.terrorist_additional_influence = model.environment_params['terrorist_additional_influence']
-        self.prob_interaction = model.environment_params['prob_interaction']
+        self.information_spread_intensity = model.environment_params[
+            "information_spread_intensity"
+        ]
+        self.terrorist_additional_influence = model.environment_params[
+            "terrorist_additional_influence"
+        ]
+        self.prob_interaction = model.environment_params["prob_interaction"]
 
-        if self['id'] == self.civilian.id:       # Civilian
-            self.mean_belief = random.uniform(0.00, 0.5)
-        elif self['id'] == self.terrorist.id:     # Terrorist
-            self.mean_belief = random.uniform(0.8, 1.00)
-        elif self['id'] == self.leader.id:     # Leader
+        if self["id"] == self.civilian.id:  # Civilian
+            self.mean_belief = self.random.uniform(0.00, 0.5)
+        elif self["id"] == self.terrorist.id:  # Terrorist
+            self.mean_belief = self.random.uniform(0.8, 1.00)
+        elif self["id"] == self.leader.id:  # Leader
             self.mean_belief = 1.00
         else:
-            raise Exception('Invalid state id: {}'.format(self['id']))
-
-        if 'min_vulnerability' in model.environment_params:
-            self.vulnerability = random.uniform( model.environment_params['min_vulnerability'], model.environment_params['max_vulnerability'] )
-        else :
-            self.vulnerability = random.uniform( 0, model.environment_params['max_vulnerability'] )
+            raise Exception("Invalid state id: {}".format(self["id"]))
 
+        if "min_vulnerability" in model.environment_params:
+            self.vulnerability = self.random.uniform(
+                model.environment_params["min_vulnerability"],
+                model.environment_params["max_vulnerability"],
+            )
+        else:
+            self.vulnerability = self.random.uniform(
+                0, model.environment_params["max_vulnerability"]
+            )
 
     @state
     def civilian(self):
-        neighbours = list(self.get_neighboring_agents(agent_type=TerroristSpreadModel))
+        neighbours = list(self.get_neighbors(agent_class=TerroristSpreadModel))
         if len(neighbours) > 0:
             # Only interact with some of the neighbors
-            interactions = list(n for n in neighbours if random.random() <= self.prob_interaction)
-            influence = sum( self.degree(i) for i in interactions )
-            mean_belief = sum( i.mean_belief * self.degree(i) / influence for i in interactions )
-            mean_belief = mean_belief * self.information_spread_intensity + self.mean_belief * ( 1 - self.information_spread_intensity )
-            self.mean_belief = mean_belief * self.vulnerability + self.mean_belief * ( 1 - self.vulnerability )
-        
+            interactions = list(
+                n for n in neighbours if self.random.random() <= self.prob_interaction
+            )
+            influence = sum(self.degree(i) for i in interactions)
+            mean_belief = sum(
+                i.mean_belief * self.degree(i) / influence for i in interactions
+            )
+            mean_belief = (
+                mean_belief * self.information_spread_intensity
+                + self.mean_belief * (1 - self.information_spread_intensity)
+            )
+            self.mean_belief = mean_belief * self.vulnerability + self.mean_belief * (
+                1 - self.vulnerability
+            )
+
         if self.mean_belief >= 0.8:
             return self.terrorist
 
     @state
     def leader(self):
-        self.mean_belief = self.mean_belief ** ( 1 - self.terrorist_additional_influence )
-        for neighbour in self.get_neighboring_agents(state_id=[self.terrorist.id, self.leader.id]):
+        self.mean_belief = self.mean_belief ** (1 - self.terrorist_additional_influence)
+        for neighbour in self.get_neighbors(
+            state_id=[self.terrorist.id, self.leader.id]
+        ):
             if self.betweenness(neighbour) > self.betweenness(self):
                 return self.terrorist
 
     @state
     def terrorist(self):
-        neighbours = self.get_agents(state_id=[self.terrorist.id, self.leader.id],
-                                     agent_type=TerroristSpreadModel,
-                                     limit_neighbors=True)
+        neighbours = self.get_agents(
+            state_id=[self.terrorist.id, self.leader.id],
+            agent_class=TerroristSpreadModel,
+            limit_neighbors=True,
+        )
         if len(neighbours) > 0:
-            influence = sum( self.degree(n) for n in neighbours )
-            mean_belief = sum( n.mean_belief * self.degree(n) / influence for n in neighbours )
-            mean_belief = mean_belief * self.vulnerability + self.mean_belief * ( 1 - self.vulnerability )
-            self.mean_belief = self.mean_belief ** ( 1 - self.terrorist_additional_influence )
+            influence = sum(self.degree(n) for n in neighbours)
+            mean_belief = sum(
+                n.mean_belief * self.degree(n) / influence for n in neighbours
+            )
+            mean_belief = mean_belief * self.vulnerability + self.mean_belief * (
+                1 - self.vulnerability
+            )
+            self.mean_belief = self.mean_belief ** (
+                1 - self.terrorist_additional_influence
+            )
 
         # Check if there are any leaders in the group
         leaders = list(filter(lambda x: x.state.id == self.leader.id, neighbours))
@@ -82,6 +108,34 @@ class TerroristSpreadModel(FSM, Geo):
                     return
             return self.leader
 
+    def ego_search(self, steps=1, center=False, node=None, **kwargs):
+        """Get a list of nodes in the ego network of *node* of radius *steps*"""
+        node = as_node(node if node is not None else self)
+        G = self.subgraph(**kwargs)
+        return nx.ego_graph(G, node, center=center, radius=steps).nodes()
+
+    def degree(self, node, force=False):
+        node = as_node(node)
+        if (
+            force
+            or (not hasattr(self.model, "_degree"))
+            or getattr(self.model, "_last_step", 0) < self.now
+        ):
+            self.model._degree = nx.degree_centrality(self.G)
+            self.model._last_step = self.now
+        return self.model._degree[node]
+
+    def betweenness(self, node, force=False):
+        node = as_node(node)
+        if (
+            force
+            or (not hasattr(self.model, "_betweenness"))
+            or getattr(self.model, "_last_step", 0) < self.now
+        ):
+            self.model._betweenness = nx.betweenness_centrality(self.G)
+            self.model._last_step = self.now
+        return self.model._betweenness[node]
+
 
 class TrainingAreaModel(FSM, Geo):
     """
@@ -95,17 +149,20 @@ class TrainingAreaModel(FSM, Geo):
 
     def __init__(self, model=None, unique_id=0, state=()):
         super().__init__(model=model, unique_id=unique_id, state=state)
-        self.training_influence = model.environment_params['training_influence']
-        if 'min_vulnerability' in model.environment_params:
-            self.min_vulnerability = model.environment_params['min_vulnerability']
-        else: self.min_vulnerability = 0
+        self.training_influence = model.environment_params["training_influence"]
+        if "min_vulnerability" in model.environment_params:
+            self.min_vulnerability = model.environment_params["min_vulnerability"]
+        else:
+            self.min_vulnerability = 0
 
     @default_state
     @state
     def terrorist(self):
-        for neighbour in self.get_neighboring_agents(agent_type=TerroristSpreadModel):
+        for neighbour in self.get_neighbors(agent_class=TerroristSpreadModel):
             if neighbour.vulnerability > self.min_vulnerability:
-                neighbour.vulnerability = neighbour.vulnerability ** ( 1 - self.training_influence )        
+                neighbour.vulnerability = neighbour.vulnerability ** (
+                    1 - self.training_influence
+                )
 
 
 class HavenModel(FSM, Geo):
@@ -122,14 +179,15 @@ class HavenModel(FSM, Geo):
 
     def __init__(self, model=None, unique_id=0, state=()):
         super().__init__(model=model, unique_id=unique_id, state=state)
-        self.haven_influence = model.environment_params['haven_influence']
-        if 'min_vulnerability' in model.environment_params:
-            self.min_vulnerability = model.environment_params['min_vulnerability']
-        else: self.min_vulnerability = 0
-        self.max_vulnerability = model.environment_params['max_vulnerability']
+        self.haven_influence = model.environment_params["haven_influence"]
+        if "min_vulnerability" in model.environment_params:
+            self.min_vulnerability = model.environment_params["min_vulnerability"]
+        else:
+            self.min_vulnerability = 0
+        self.max_vulnerability = model.environment_params["max_vulnerability"]
 
     def get_occupants(self, **kwargs):
-        return self.get_neighboring_agents(agent_type=TerroristSpreadModel, **kwargs)
+        return self.get_neighbors(agent_class=TerroristSpreadModel, **kwargs)
 
     @state
     def civilian(self):
@@ -139,14 +197,18 @@ class HavenModel(FSM, Geo):
 
         for neighbour in self.get_occupants():
             if neighbour.vulnerability > self.min_vulnerability:
-                neighbour.vulnerability = neighbour.vulnerability * ( 1 - self.haven_influence )
+                neighbour.vulnerability = neighbour.vulnerability * (
+                    1 - self.haven_influence
+                )
         return self.civilian
 
     @state
     def terrorist(self):
         for neighbour in self.get_occupants():
             if neighbour.vulnerability < self.max_vulnerability:
-                neighbour.vulnerability = neighbour.vulnerability ** ( 1 - self.haven_influence )
+                neighbour.vulnerability = neighbour.vulnerability ** (
+                    1 - self.haven_influence
+                )
         return self.terrorist
 
 
@@ -165,10 +227,10 @@ class TerroristNetworkModel(TerroristSpreadModel):
     def __init__(self, model=None, unique_id=0, state=()):
         super().__init__(model=model, unique_id=unique_id, state=state)
 
-        self.vision_range = model.environment_params['vision_range']
-        self.sphere_influence = model.environment_params['sphere_influence']
-        self.weight_social_distance = model.environment_params['weight_social_distance']
-        self.weight_link_distance = model.environment_params['weight_link_distance']
+        self.vision_range = model.environment_params["vision_range"]
+        self.sphere_influence = model.environment_params["sphere_influence"]
+        self.weight_social_distance = model.environment_params["weight_social_distance"]
+        self.weight_link_distance = model.environment_params["weight_link_distance"]
 
     @state
     def terrorist(self):
@@ -181,28 +243,49 @@ class TerroristNetworkModel(TerroristSpreadModel):
         return super().leader()
 
     def update_relationships(self):
-        if self.count_neighboring_agents(state_id=self.civilian.id) == 0:
-            close_ups = set(self.geo_search(radius=self.vision_range, agent_type=TerroristNetworkModel))
-            step_neighbours = set(self.ego_search(self.sphere_influence, agent_type=TerroristNetworkModel, center=False))
-            neighbours = set(agent.id for agent in self.get_neighboring_agents(agent_type=TerroristNetworkModel))
+        if self.count_neighbors(state_id=self.civilian.id) == 0:
+            close_ups = set(
+                self.geo_search(
+                    radius=self.vision_range, agent_class=TerroristNetworkModel
+                )
+            )
+            step_neighbours = set(
+                self.ego_search(
+                    self.sphere_influence,
+                    agent_class=TerroristNetworkModel,
+                    center=False,
+                )
+            )
+            neighbours = set(
+                agent.id
+                for agent in self.get_neighbors(
+                    agent_class=TerroristNetworkModel
+                )
+            )
             search = (close_ups | step_neighbours) - neighbours
             for agent in self.get_agents(search):
                 social_distance = 1 / self.shortest_path_length(agent.id)
-                spatial_proximity = ( 1 - self.get_distance(agent.id) )
-                prob_new_interaction = self.weight_social_distance * social_distance + self.weight_link_distance * spatial_proximity
-                if agent['id'] == agent.civilian.id and random.random() < prob_new_interaction:
+                spatial_proximity = 1 - self.get_distance(agent.id)
+                prob_new_interaction = (
+                    self.weight_social_distance * social_distance
+                    + self.weight_link_distance * spatial_proximity
+                )
+                if (
+                    agent["id"] == agent.civilian.id
+                    and self.random.random() < prob_new_interaction
+                ):
                     self.add_edge(agent)
                     break
 
     def get_distance(self, target):
-        source_x, source_y = nx.get_node_attributes(self.topology, 'pos')[self.id]
-        target_x, target_y = nx.get_node_attributes(self.topology, 'pos')[target]
-        dx = abs( source_x - target_x )
-        dy = abs( source_y - target_y )
-        return ( dx ** 2 + dy ** 2 ) ** ( 1 / 2 )
+        source_x, source_y = nx.get_node_attributes(self.G, "pos")[self.id]
+        target_x, target_y = nx.get_node_attributes(self.G, "pos")[target]
+        dx = abs(source_x - target_x)
+        dy = abs(source_y - target_y)
+        return (dx**2 + dy**2) ** (1 / 2)
 
     def shortest_path_length(self, target):
         try:
-            return nx.shortest_path_length(self.topology, self.id, target)
+            return nx.shortest_path_length(self.G, self.id, target)
         except nx.NetworkXNoPath:
-            return float('inf')
+            return float("inf")

examples/terrorism/TerroristNetworkModel.yml

@@ -1,32 +1,31 @@
 name: TerroristNetworkModel_sim
-load_module: TerroristNetworkModel
-max_time: 150 
+max_steps: 150 
 num_trials: 1
-network_params:
-  generator: random_geometric_graph
-  radius: 0.2
-  # generator: geographical_threshold_graph
-  # theta: 20
-  n: 100
-network_agents:
-  - agent_type: TerroristNetworkModel
-    weight: 0.8
-    state:
-      id: civilian  # Civilians
-  - agent_type: TerroristNetworkModel
-    weight: 0.1
-    state:
-      id: leader    # Leaders
-  - agent_type: TrainingAreaModel
-    weight: 0.05
-    state:
-      id: terrorist # Terrorism
-  - agent_type: HavenModel
-    weight: 0.05
-    state:
-      id: civilian  # Civilian
+model_params:
+  network_params:
+    generator: random_geometric_graph
+    radius: 0.2
+    # generator: geographical_threshold_graph
+    # theta: 20
+    n: 100
+  network_agents:
+    - agent_class: TerroristNetworkModel.TerroristNetworkModel
+      weight: 0.8
+      state:
+        id: civilian  # Civilians
+    - agent_class: TerroristNetworkModel.TerroristNetworkModel
+      weight: 0.1
+      state:
+        id: leader    # Leaders
+    - agent_class: TerroristNetworkModel.TrainingAreaModel
+      weight: 0.05
+      state:
+        id: terrorist # Terrorism
+    - agent_class: TerroristNetworkModel.HavenModel
+      weight: 0.05
+      state:
+        id: civilian  # Civilian
 
-environment_params:
   # TerroristSpreadModel
   information_spread_intensity: 0.7
   terrorist_additional_influence: 0.035

examples/torvalds.yml

@@ -1,14 +1,15 @@
 ---
 name: torvalds_example
-max_time: 10
+max_steps: 10
 interval: 2
-agent_type: CounterModel
-default_state:
-  skill_level: 'beginner'
-network_params:
-  path: 'torvalds.edgelist'
-states:
-  Torvalds:
-    skill_level: 'God'
-  balkian:
-    skill_level: 'developer'
+model_params:
+  agent_class: CounterModel
+  default_state:
+    skill_level: 'beginner'
+  network_params:
+    path: 'torvalds.edgelist'
+  states:
+    Torvalds:
+      skill_level: 'God'
+    balkian:
+      skill_level: 'developer'

examples/tutorial/soil_tutorial.html

@@ -12330,11 +12330,11 @@ Notice how node 0 is the only one with a TV.</p>
 <span class="n">sim</span> <span class="o">=</span> <span class="n">soil</span><span class="o">.</span><span class="n">Simulation</span><span class="p">(</span><span class="n">topology</span><span class="o">=</span><span class="n">G</span><span class="p">,</span>
                                      <span class="n">num_trials</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span>
                                      <span class="n">max_time</span><span class="o">=</span><span class="n">MAX_TIME</span><span class="p">,</span>
-                                     <span class="n">environment_agents</span><span class="o">=</span><span class="p">[{</span><span class="s1">&#39;agent_type&#39;</span><span class="p">:</span> <span class="n">NewsEnvironmentAgent</span><span class="p">,</span>
+                                     <span class="n">environment_agents</span><span class="o">=</span><span class="p">[{</span><span class="s1">&#39;agent_class&#39;</span><span class="p">:</span> <span class="n">NewsEnvironmentAgent</span><span class="p">,</span>
                                                          <span class="s1">&#39;state&#39;</span><span class="p">:</span> <span class="p">{</span>
                                                              <span class="s1">&#39;event_time&#39;</span><span class="p">:</span> <span class="n">EVENT_TIME</span>
                                                          <span class="p">}}],</span>
-                                     <span class="n">network_agents</span><span class="o">=</span><span class="p">[{</span><span class="s1">&#39;agent_type&#39;</span><span class="p">:</span> <span class="n">NewsSpread</span><span class="p">,</span>
+                                     <span class="n">network_agents</span><span class="o">=</span><span class="p">[{</span><span class="s1">&#39;agent_class&#39;</span><span class="p">:</span> <span class="n">NewsSpread</span><span class="p">,</span>
                                                       <span class="s1">&#39;weight&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">}],</span>
                                      <span class="n">states</span><span class="o">=</span><span class="p">{</span><span class="mi">0</span><span class="p">:</span> <span class="p">{</span><span class="s1">&#39;has_tv&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">}},</span>
                                      <span class="n">default_state</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;has_tv&#39;</span><span class="p">:</span> <span class="kc">False</span><span class="p">},</span>
@@ -12468,14 +12468,14 @@ For this demo, we will use a python dictionary:</p>
     <span class="p">},</span>
     <span class="s1">&#39;network_agents&#39;</span><span class="p">:</span> <span class="p">[</span>
         <span class="p">{</span>
-            <span class="s1">&#39;agent_type&#39;</span><span class="p">:</span> <span class="n">NewsSpread</span><span class="p">,</span>
+            <span class="s1">&#39;agent_class&#39;</span><span class="p">:</span> <span class="n">NewsSpread</span><span class="p">,</span>
             <span class="s1">&#39;weight&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>
             <span class="s1">&#39;state&#39;</span><span class="p">:</span> <span class="p">{</span>
                 <span class="s1">&#39;has_tv&#39;</span><span class="p">:</span> <span class="kc">False</span>
             <span class="p">}</span>
         <span class="p">},</span>
         <span class="p">{</span>
-            <span class="s1">&#39;agent_type&#39;</span><span class="p">:</span> <span class="n">NewsSpread</span><span class="p">,</span>
+            <span class="s1">&#39;agent_class&#39;</span><span class="p">:</span> <span class="n">NewsSpread</span><span class="p">,</span>
             <span class="s1">&#39;weight&#39;</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span>
             <span class="s1">&#39;state&#39;</span><span class="p">:</span> <span class="p">{</span>
                 <span class="s1">&#39;has_tv&#39;</span><span class="p">:</span> <span class="kc">True</span>
@@ -12483,7 +12483,7 @@ For this demo, we will use a python dictionary:</p>
         <span class="p">}</span>
     <span class="p">],</span>
     <span class="s1">&#39;environment_agents&#39;</span><span class="p">:[</span>
-        <span class="p">{</span><span class="s1">&#39;agent_type&#39;</span><span class="p">:</span> <span class="n">NewsEnvironmentAgent</span><span class="p">,</span>
+        <span class="p">{</span><span class="s1">&#39;agent_class&#39;</span><span class="p">:</span> <span class="n">NewsEnvironmentAgent</span><span class="p">,</span>
          <span class="s1">&#39;state&#39;</span><span class="p">:</span> <span class="p">{</span>
              <span class="s1">&#39;event_time&#39;</span><span class="p">:</span> <span class="mi">10</span>
          <span class="p">}</span>

requirements.txt

@@ -2,8 +2,9 @@ networkx>=2.5
 numpy
 matplotlib
 pyyaml>=5.1
-pandas>=0.23
+pandas>=1
 SALib>=1.3
 Jinja2
-Mesa>=0.8
-tsih>=0.1.9
+Mesa>=1.1
+pydantic>=1.9
+sqlalchemy>=1.4

setup.py

@@ -49,9 +49,10 @@ setup(
     extras_require=extras_require,
     tests_require=test_reqs,
     setup_requires=['pytest-runner', ],
+    pytest_plugins = ['pytest_profiling'],
     include_package_data=True,
     entry_points={
         'console_scripts':
-        ['soil = soil.__init__:main',
+        ['soil = soil.__main__:main',
         'soil-web = soil.web.__init__:main']
     })

soil/VERSION

@@ -1 +1 @@
-0.20.8
+0.30.0rc2

soil/__init__.py

@@ -1,8 +1,11 @@
+from __future__ import annotations
+
 import importlib
 import sys
 import os
-import pdb
 import logging
+import traceback
+from contextlib import contextmanager
 
 from .version import __version__
 
@@ -14,86 +17,231 @@ except NameError:
 from .agents import *
 from . import agents
 from .simulation import *
-from .environment import Environment
+from .environment import Environment, EventedEnvironment
 from . import serialization
-from . import analysis
 from .utils import logger
 from .time import *
 
-def main():
+
+def main(
+    cfg="simulation.yml",
+    exporters=None,
+    parallel=None,
+    output="soil_output",
+    *,
+    do_run=False,
+    debug=False,
+    pdb=False,
+    **kwargs,
+):
+
+    if isinstance(cfg, Simulation):
+        sim = cfg
     import argparse
     from . import simulation
 
-    logger.info('Running SOIL version: {}'.format(__version__))
+    logger.info("Running SOIL version: {}".format(__version__))
 
-    parser = argparse.ArgumentParser(description='Run a SOIL simulation')
-    parser.add_argument('file', type=str,
-                        nargs="?",
-                        default='simulation.yml',
-                        help='Configuration file for the simulation (e.g., YAML or JSON)')
-    parser.add_argument('--version', action='store_true',
-                        help='Show version info and exit')
-    parser.add_argument('--module', '-m', type=str,
-                        help='file containing the code of any custom agents.')
-    parser.add_argument('--dry-run', '--dry', action='store_true',
-                        help='Do not store the results of the simulation.')
-    parser.add_argument('--pdb', action='store_true',
-                        help='Use a pdb console in case of exception.')
-    parser.add_argument('--graph', '-g', action='store_true',
-                        help='Dump GEXF graph. Defaults to false.')
-    parser.add_argument('--csv', action='store_true',
-                        help='Dump history in CSV format. Defaults to false.')
-    parser.add_argument('--level', type=str,
-                        help='Logging level')
-    parser.add_argument('--output', '-o', type=str, default="soil_output",
-                        help='folder to write results to. It defaults to the current directory.')
-    parser.add_argument('--synchronous', action='store_true',
-                        help='Run trials serially and synchronously instead of in parallel. Defaults to false.')
-    parser.add_argument('-e', '--exporter', action='append',
-                        help='Export environment and/or simulations using this exporter')
+    parser = argparse.ArgumentParser(description="Run a SOIL simulation")
+    parser.add_argument(
+        "file",
+        type=str,
+        nargs="?",
+        default=cfg if sim is None else '',
+        help="Configuration file for the simulation (e.g., YAML or JSON)",
+    )
+    parser.add_argument(
+        "--version", action="store_true", help="Show version info and exit"
+    )
+    parser.add_argument(
+        "--module",
+        "-m",
+        type=str,
+        help="file containing the code of any custom agents.",
+    )
+    parser.add_argument(
+        "--dry-run",
+        "--dry",
+        action="store_true",
+        help="Do not store the results of the simulation to disk, show in terminal instead.",
+    )
+    parser.add_argument(
+        "--pdb", action="store_true", help="Use a pdb console in case of exception."
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Run a customized version of a pdb console to debug a simulation.",
+    )
+    parser.add_argument(
+        "--graph",
+        "-g",
+        action="store_true",
+        help="Dump each trial's network topology as a GEXF graph. Defaults to false.",
+    )
+    parser.add_argument(
+        "--csv",
+        action="store_true",
+        help="Dump all data collected in CSV format. Defaults to false.",
+    )
+    parser.add_argument("--level", type=str, help="Logging level")
+    parser.add_argument(
+        "--output",
+        "-o",
+        type=str,
+        default=output or "soil_output",
+        help="folder to write results to. It defaults to the current directory.",
+    )
+    if parallel is None:
+        parser.add_argument(
+            "--synchronous",
+            action="store_true",
+            help="Run trials serially and synchronously instead of in parallel. Defaults to false.",
+        )
+
+    parser.add_argument(
+        "-e",
+        "--exporter",
+        action="append",
+        default=[],
+        help="Export environment and/or simulations using this exporter",
+    )
+
+    parser.add_argument(
+        "--only-convert",
+        "--convert",
+        action="store_true",
+        help="Do not run the simulation, only convert the configuration file(s) and output them.",
+    )
+
+    parser.add_argument(
+        "--set",
+        metavar="KEY=VALUE",
+        action="append",
+        help="Set a number of parameters that will be passed to the simulation."
+        "(do not put spaces before or after the = sign). "
+        "If a value contains spaces, you should define "
+        "it with double quotes: "
+        'foo="this is a sentence". Note that '
+        "values are always treated as strings.",
+    )
 
     args = parser.parse_args()
-    logging.basicConfig(level=getattr(logging, (args.level or 'INFO').upper()))
+    logger.setLevel(getattr(logging, (args.level or "INFO").upper()))
 
     if args.version:
         return
 
+    if parallel is None:
+        parallel = not args.synchronous
+
+    exporters = exporters or [
+        "default",
+    ]
+    for exp in args.exporter:
+        if exp not in exporters:
+            exporters.append(exp)
+    if args.csv:
+        exporters.append("csv")
+    if args.graph:
+        exporters.append("gexf")
+
     if os.getcwd() not in sys.path:
         sys.path.append(os.getcwd())
     if args.module:
         importlib.import_module(args.module)
+    if output is None:
+        output = args.output
 
-    logger.info('Loading config file: {}'.format(args.file))
+    debug = debug or args.debug
 
-    if args.pdb:
+    if args.pdb or debug:
         args.synchronous = True
+        os.environ["SOIL_POSTMORTEM"] = "true"
 
-
+    res = []
     try:
-        exporters = list(args.exporter or ['default', ])
-        if args.csv:
-            exporters.append('csv')
-        if args.graph:
-            exporters.append('gexf')
         exp_params = {}
-        if args.dry_run:
-            exp_params['copy_to'] = sys.stdout
 
-        if not os.path.exists(args.file):
-            logger.error('Please, input a valid file')
-            return
-        simulation.run_from_config(args.file,
-                                   dry_run=args.dry_run,
-                                   exporters=exporters,
-                                   parallel=(not args.synchronous),
-                                   outdir=args.output,
-                                   exporter_params=exp_params)
-    except Exception:
+        if sim:
+            logger.info("Loading simulation instance")
+            sim.dry_run = args.dry_run
+            sim.exporters = exporters
+            sim.parallel = parallel
+            sim.outdir = output
+            sims = [sim, ]
+        else:
+            logger.info("Loading config file: {}".format(args.file))
+            if not os.path.exists(args.file):
+                logger.error("Please, input a valid file")
+                return
+
+            sims = list(simulation.iter_from_config(
+                args.file,
+                dry_run=args.dry_run,
+                exporters=exporters,
+                parallel=parallel,
+                outdir=output,
+                exporter_params=exp_params,
+                **kwargs,
+            ))
+
+        for sim in sims:
+
+            if args.set:
+                for s in args.set:
+                    k, v = s.split("=", 1)[:2]
+                    v = eval(v)
+                    tail, *head = k.rsplit(".", 1)[::-1]
+                    target = sim
+                    if head:
+                        for part in head[0].split("."):
+                            try:
+                                target = getattr(target, part)
+                            except AttributeError:
+                                target = target[part]
+                    try:
+                        setattr(target, tail, v)
+                    except AttributeError:
+                        target[tail] = v
+
+            if args.only_convert:
+                print(sim.to_yaml())
+                continue
+            if do_run:
+                res.append(sim.run())
+            else:
+                print("not running")
+                res.append(sim)
+
+    except Exception as ex:
         if args.pdb:
-            pdb.post_mortem()
+            from .debugging import post_mortem
+
+            print(traceback.format_exc())
+            post_mortem()
         else:
             raise
+    if debug:
+        from .debugging import set_trace
+
+        os.environ["SOIL_DEBUG"] = "true"
+        set_trace()
+    return res
 
 
-if __name__ == '__main__':
-    main()
+@contextmanager
+def easy(cfg, pdb=False, debug=False, **kwargs):
+    try:
+        yield main(cfg, debug=debug, pdb=pdb, **kwargs)[0]
+    except Exception as e:
+        if os.environ.get("SOIL_POSTMORTEM"):
+            from .debugging import post_mortem
+
+            print(traceback.format_exc())
+            post_mortem()
+        raise
+
+
+if __name__ == "__main__":
+    main(do_run=True)

soil/__main__.py

@@ -1,4 +1,9 @@
-from . import main
+from . import main as init_main
 
-if __name__ == '__main__':
-    main()
+
+def main():
+    init_main(do_run=True)
+
+
+if __name__ == "__main__":
+    init_main(do_run=True)