Commit a2fb25c1 authored by J. Fernando Sánchez's avatar J. Fernando Sánchez
Browse files

Version 0.30.0rc2

* Fix CLI arguments not being used when easy is passed a simulation instance
* Docs for `examples/events_and_messages/`
parent 5fcf6101
Pipeline #3859 failed with stages
......@@ -3,7 +3,7 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](, and this project adheres to [Semantic Versioning](
## [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
This example can be run like with command-line options, like this:
python --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.
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 import MultiGrid
from enum import Enum
# 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.
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 = None
passenger: Passenger
driver: Driver = None
class City(EventedEnvironment):
def __init__(self, *args, n_cars=1, height=100, width=100, n_passengers=10, agents=None, **kwargs):
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,
self.grid = MultiGrid(width=width, height=height, torus=False)
if agents is None:
agents = []
......@@ -24,53 +65,73 @@ class City(EventedEnvironment):
agents.append({'agent_class': Driver})
for i in range(n_passengers):
agents.append({'agent_class': Passenger})
super().__init__(*args, agents=agents, **kwargs)
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))
def total_earnings(self):
return sum(d.earnings for d in self.agents(agent_class=Driver))
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)"Passengers left {c}")
if not c:
def wandering(self):
'''Move around the city until a journey is accepted'''
target = None
self.journey = None
while self.journey is 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_messages() # This will call on_receive behind the scenes
yield Delta(30)
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
# 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 self.driving
def check_passengers(self):
c = self.count_agents(agent_class=Passenger)"Passengers left {c}")
if not c:
return self.driving
def driving(self):
'''The journey has been accepted. Pick them up and take them to their destination'''
while self.move_towards(self.journey.origin):
while self.move_towards(self.journey.destination, with_passenger=True):
self.earnings += self.journey.tip
return self.wandering
......@@ -97,6 +158,14 @@ class Driver(Evented, FSM):
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
def asking(self):
......@@ -121,11 +190,6 @@ class Passenger(Evented, FSM):
return self.driving_home
def on_receive(self, msg, sender):
if isinstance(msg, Journey):
self.journey = msg
return msg
def driving_home(self):
while self.pos[0] != self.journey.destination[0] or self.pos[1] != self.journey.destination[1]:
......@@ -134,7 +198,7 @@ class Passenger(Evented, FSM):
simulation = Simulation(model_class=City, model_params={'n_passengers': 2})
simulation = Simulation(name='RideHailing', model_class=City, model_params={'n_passengers': 2})
if __name__ == "__main__":
with easy(simulation) as s:
\ No newline at end of file
\ No newline at end of file
......@@ -153,8 +153,6 @@ def main(
if output is None:
output = args.output
debug = debug or args.debug
if args.pdb or debug:
......@@ -167,6 +165,10 @@ def main(
if sim:"Loading simulation instance")
sim.dry_run = args.dry_run
sim.exporters = exporters
sim.parallel = parallel
sim.outdir = output
sims = [sim, ]
else:"Loading config file: {}".format(args.file))
......@@ -231,7 +233,7 @@ def main(
def easy(cfg, pdb=False, debug=False, **kwargs):
yield main(cfg, **kwargs)[0]
yield main(cfg, debug=debug, pdb=pdb, **kwargs)[0]
except Exception as e:
if os.environ.get("SOIL_POSTMORTEM"):
from .debugging import post_mortem
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment