From d4d1924c276c55423fa763c044b87cefa8b66f97 Mon Sep 17 00:00:00 2001 From: Jackie Kazil Date: Thu, 9 Jan 2025 23:08:21 -0500 Subject: [PATCH 1/5] paper: Edit Time Advancement section. --- paper/paper.md | 46 ++++++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 22 deletions(-) diff --git a/paper/paper.md b/paper/paper.md index 8bd286b2eb0..d25b2be6b03 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -131,42 +131,44 @@ from mesa.experimental.cell_space ... ``` ### Time advancement -Typically, ABMs rely on incremental time progression or ticks. For each tick, the step method of the model is called. This activates the agents in some way. The most frequently implemented approach is shown below, which runs a model for 100 ticks. +Typically, ABMs represent time incrementally and call the units ticks. For each tick, the step method of the model is called, and the agents are activated to take their designated actions. The most frequently implemented approach is shown below, which runs a model for 100 ticks. ```python - model = Model(seed=42) + model = Model(seed=42) - for _ in range(100): - model.step() + + for _ in range(100): + model.step() ``` -Generally, within the step method of the model, one activates all the agents. The newly added `AgentSet` class provides a more flexible way to activate agents replacing the fixed patterns previously available. +Before Mesa 3+, all agents were activated within the step method of the model. However, the newly added `AgentSet` class provides a more flexible way to activate agents. These changes include the depreciation of the Scheduler API and replacing previously available fixed patterns. + ```python - model.agents.do("step") # Sequential activation + model.agents.do("step") # Sequential activation - model.agents.shuffle_do("step") # Random activation + model.agents.shuffle_do("step") # Random activation - # Multi-stage activation: - for stage in ["move", "eat", "reproduce"]: - model.agents.do(stage) + # Multi-stage activation: + for stage in ["move", "eat", "reproduce"]: + model.agents.do(stage) - # Activation by agent subclass: - for klass in model.agent_types: - model.agents_by_type[klass].do("step") + # Activation by agent subclass: + for klass in model.agent_types: + model.agents_by_type[klass].do("step") ``` -Mesa also supports next-event time progression, currently in experimental state. In this approach, the simulation consists of time-stamped events that are executed chronologically, with the simulation clock advancing to each event's timestamp. This enables both pure discrete event-based models and hybrid approaches combining incremental time progression with event scheduling on the ticks as shown below.. This latter hybrid approach allows combining traditional ABM time steps with the flexibility and potential performance benefits of event scheduling. +Next-event time progression is an additional feature, which is currently in an experimental state with plans for support in the future. In this approach, the simulation consists of time-stamped events executed chronologically, with the simulation clock advancing to each event's timestamp. This enables both pure discrete event-based models and hybrid approaches combining incremental time progression with event scheduling on the ticks, as shown below. The latter hybrid approach combines traditional ABM time steps with the flexibility and potential performance benefits of event scheduling. ```python - # Pure event-based scheduling - simulator = DiscreteEventSimulator() - model = Model(seed=42, simulator=simulator) - simulator.schedule_event_relative(some_function, 3.1415) - - # Hybrid time-step and event scheduling - model = Model(seed=42, simulator=ABMSimulator()) - model.simulator.schedule_event_next_tick(some_function) + # Pure event-based scheduling + simulator = DiscreteEventSimulator() + model = Model(seed=42, simulator=simulator) + simulator.schedule_event_relative(some_function, 3.1415) + + # Hybrid time-step and event scheduling + model = Model(seed=42, simulator=ABMSimulator()) + model.simulator.schedule_event_next_tick(some_function) ``` ## Visualization From 821193bccd5c776728627d330529221d8cf81e05 Mon Sep 17 00:00:00 2001 From: Jackie Kazil Date: Fri, 10 Jan 2025 01:30:06 -0500 Subject: [PATCH 2/5] paper: Standardizing on Mesa 3. --- paper/paper.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/paper/paper.md b/paper/paper.md index d25b2be6b03..c29c0595e4e 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -79,7 +79,7 @@ The central class in Mesa is the Model. To build a model, the user instantiates Central to ABMs are the autonomous heterogeneous agents. Mesa provides a variety of base agent classes which the user can subclass. In its most basic implementation, an agent subclass specifies the `__init__` and `step` method. Any subclass of the basic mesa agent subclass registers itself with the specified model instance, and via `agent.remove` it will remove itself from the model. It is strongly encouraged to rely on `remove`, and even extend it if needed to ensure agents are fully removed from the simulation. ### Agent management -One significant advancement of Mesa 3+ is expanded functionality around agent management. The new [`AgentSet`](https://mesa.readthedocs.io/latest/apis/agent.html#mesa.agent.AgentSet) class provides methods that allow users to filter, group, and analyze agents, making it easier to express complex model logic. +One significant advancement of Mesa 3 is expanded functionality around agent management. The new [`AgentSet`](https://mesa.readthedocs.io/latest/apis/agent.html#mesa.agent.AgentSet) class provides methods that allow users to filter, group, and analyze agents, making it easier to express complex model logic. ```python # Select wealthy agents and calculate average wealth @@ -141,7 +141,7 @@ Typically, ABMs represent time incrementally and call the units ticks. For each model.step() ``` -Before Mesa 3+, all agents were activated within the step method of the model. However, the newly added `AgentSet` class provides a more flexible way to activate agents. These changes include the depreciation of the Scheduler API and replacing previously available fixed patterns. +Before Mesa 3, all agents were activated within the step method of the model. However, the newly added `AgentSet` class provides a more flexible way to activate agents. These changes include the depreciation of the Scheduler API and replacing previously available fixed patterns. ```python From bd4964833de244035bdd5fea705c2d99c588a92f Mon Sep 17 00:00:00 2001 From: Jackie Kazil Date: Sun, 12 Jan 2025 16:51:48 -0500 Subject: [PATCH 3/5] paper: Update to visualization section. --- paper/paper.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/paper/paper.md b/paper/paper.md index c29c0595e4e..d7022019db8 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -172,28 +172,27 @@ Next-event time progression is an additional feature, which is currently in an e ``` ## Visualization -Mesa's visualization system, [SolaraViz](https://mesa.readthedocs.io/latest/tutorials/visualization_tutorial.html), provides interactive browser-based model exploration: +Mesa’s visualization module, [SolaraViz](https://mesa.readthedocs.io/latest/tutorials/visualization_tutorial.html, allows for interactive browser-based model exploration. Advancements with Mesa 3 update the visualization from harder-to-maintain custom code to Solara, a standardized library. Usage of the visualization module can be seen below: ```python - visualization = SolaraViz( - model, - [ - make_space_component(agent_portrayal), - make_plot_component(["population", "average_wealth"]), - lambda m: f"Step {m.steps}: {len(m.agents)} agents" - ], - model_params=parameter_controls - ) + visualization = SolaraViz( + model, + [ + make_space_component(agent_portrayal), + make_plot_component(["population", "average_wealth"]), + lambda m: f"Step {m.steps}: {len(m.agents)} agents" + ], + model_params=parameter_controls + ) ``` ![A screenshot of the WolfSheep Model in Mesa](../docs/images/wolf_sheep.png) Key features include: - - Interactive model controls - Real-time data visualization - Customizable agent and space portrayal -- Support for multiple visualization types including grids, networks, and charts +- Support for multiple visualization types, including grids, networks, and charts ## Experimentation and analysis From 2b5e4296d47c815f24826876f36972da52c10db6 Mon Sep 17 00:00:00 2001 From: Jackie Kazil Date: Sun, 12 Jan 2025 18:09:14 -0500 Subject: [PATCH 4/5] paper: Fix spacing. --- paper/paper.md | 71 +++++++++++++++++++++++++------------------------- 1 file changed, 35 insertions(+), 36 deletions(-) diff --git a/paper/paper.md b/paper/paper.md index d7022019db8..d854fdade42 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -102,7 +102,7 @@ Mesa 3 provides both discrete (cell-based) and continuous space implementations. Example grid creation: ```python - grid = OrthogonalVonNeumannGrid((width, height), torus=False, random=model.random) + grid = OrthogonalVonNeumannGrid((width, height), torus=False, random=model.random) ``` In Mesa 3, specialized agent classes for spatial interactions in discrete spaces were added: @@ -114,15 +114,15 @@ In Mesa 3, specialized agent classes for spatial interactions in discrete spaces All discrete spaces support PropertyLayers - efficient numpy-based arrays for storing cell-level properties. This newly added feature allows for agents to interact with spatial properties of the cell more easily: ```python - grid.create_property_layer("elevation", default_value=10) - high_ground = grid.elevation.select_cells(lambda x: x > 50) + grid.create_property_layer("elevation", default_value=10) + high_ground = grid.elevation.select_cells(lambda x: x > 50) ``` For models where agents need to move continuously through space rather than between discrete locations, `ContinuousSpace` allows agents to occupy any coordinate within defined boundaries: ```python - space = ContinuousSpace(x_max, y_max, torus=True) - space.move_agent(agent, (new_x, new_y)) + space = ContinuousSpace(x_max, y_max, torus=True) + space.move_agent(agent, (new_x, new_y)) ``` The space module is stable but under active development. The new cell-based spaces in Mesa 3 are currently being tested and considered feature-complete. The code snippets reflected in this paper are the future expected state of Mesa. Features not yet merged into core are imported from experimental: @@ -134,61 +134,60 @@ from mesa.experimental.cell_space ... Typically, ABMs represent time incrementally and call the units ticks. For each tick, the step method of the model is called, and the agents are activated to take their designated actions. The most frequently implemented approach is shown below, which runs a model for 100 ticks. ```python - model = Model(seed=42) + model = Model(seed=42) - - for _ in range(100): - model.step() + for _ in range(100): + model.step() ``` -Before Mesa 3, all agents were activated within the step method of the model. However, the newly added `AgentSet` class provides a more flexible way to activate agents. These changes include the depreciation of the Scheduler API and replacing previously available fixed patterns. - +Before Mesa 3, all agents were activated within the step method of the model. However, the newly added `AgentSet` class provides a more flexible way to activate agents. These changes include the depreciation of the Scheduler API and replacing previously available fixed patterns. ```python - model.agents.do("step") # Sequential activation + model.agents.do("step") # Sequential activation - model.agents.shuffle_do("step") # Random activation + model.agents.shuffle_do("step") # Random activation - # Multi-stage activation: - for stage in ["move", "eat", "reproduce"]: - model.agents.do(stage) + # Multi-stage activation: + for stage in ["move", "eat", "reproduce"]: + model.agents.do(stage) - # Activation by agent subclass: - for klass in model.agent_types: - model.agents_by_type[klass].do("step") + # Activation by agent subclass: + for klass in model.agent_types: + model.agents_by_type[klass].do("step") ``` Next-event time progression is an additional feature, which is currently in an experimental state with plans for support in the future. In this approach, the simulation consists of time-stamped events executed chronologically, with the simulation clock advancing to each event's timestamp. This enables both pure discrete event-based models and hybrid approaches combining incremental time progression with event scheduling on the ticks, as shown below. The latter hybrid approach combines traditional ABM time steps with the flexibility and potential performance benefits of event scheduling. ```python - # Pure event-based scheduling - simulator = DiscreteEventSimulator() - model = Model(seed=42, simulator=simulator) - simulator.schedule_event_relative(some_function, 3.1415) - - # Hybrid time-step and event scheduling - model = Model(seed=42, simulator=ABMSimulator()) - model.simulator.schedule_event_next_tick(some_function) + # Pure event-based scheduling + simulator = DiscreteEventSimulator() + model = Model(seed=42, simulator=simulator) + simulator.schedule_event_relative(some_function, 3.1415) + + # Hybrid time-step and event scheduling + model = Model(seed=42, simulator=ABMSimulator()) + model.simulator.schedule_event_next_tick(some_function) ``` ## Visualization Mesa’s visualization module, [SolaraViz](https://mesa.readthedocs.io/latest/tutorials/visualization_tutorial.html, allows for interactive browser-based model exploration. Advancements with Mesa 3 update the visualization from harder-to-maintain custom code to Solara, a standardized library. Usage of the visualization module can be seen below: ```python - visualization = SolaraViz( - model, - [ - make_space_component(agent_portrayal), - make_plot_component(["population", "average_wealth"]), - lambda m: f"Step {m.steps}: {len(m.agents)} agents" - ], - model_params=parameter_controls - ) + visualization = SolaraViz( + model, + [ + make_space_component(agent_portrayal), + make_plot_component(["population", "average_wealth"]), + lambda m: f"Step {m.steps}: {len(m.agents)} agents" + ], + model_params=parameter_controls + ) ``` ![A screenshot of the WolfSheep Model in Mesa](../docs/images/wolf_sheep.png) Key features include: + - Interactive model controls - Real-time data visualization - Customizable agent and space portrayal From be421725630f333d22b0e57025fbe3e69519ad2a Mon Sep 17 00:00:00 2001 From: Jackie Kazil Date: Mon, 13 Jan 2025 22:30:19 -0500 Subject: [PATCH 5/5] Update paper/paper.md Co-authored-by: Ewout ter Hoeven --- paper/paper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/paper/paper.md b/paper/paper.md index d854fdade42..f86a4dbdb6b 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -140,7 +140,7 @@ Typically, ABMs represent time incrementally and call the units ticks. For each model.step() ``` -Before Mesa 3, all agents were activated within the step method of the model. However, the newly added `AgentSet` class provides a more flexible way to activate agents. These changes include the depreciation of the Scheduler API and replacing previously available fixed patterns. +Before Mesa 3, all agents were activated within the step method of the model. However, the newly added `AgentSet` class provides a more flexible way to activate agents. These changes include the removal of the Scheduler API and its previously available fixed patterns. ```python model.agents.do("step") # Sequential activation