paper: Add code examples and clarify terminology

paper/paper.md

@@ -96,8 +96,31 @@ Mesa follows a two-track development model where new features are first released
 ### Model
 The central class in Mesa is the Model. To build a model, the user instantiates a model object, creates a space within it, and populates the space with agent instances. Since ABMs are typically stochastic simulations, Mesa includes a random number generator and, for reproducibility purposes, allows the user to pass a seed.
 
+```python
+class SimpleModel(mesa.Model):
+    def __init__(self, n_agents=10, seed=42):
+        super().__init__(seed=seed)  # Initialize Mesa model with random seed
+
+        SimpleAgent.create_agents(self, n_agents, energy=100)
+
+    def step(self):
+        self.agents.shuffle_do("step")  # Activate all agents in random order
+```
+
 ### Agents
-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.
+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. Sometimes an agent subclass is referred to as a "type" of agent.
+
+```python
+class SimpleAgent(mesa.Agent):
+    def __init__(self, model, energy):
+        super().__init__(model)  # Initialize Mesa agent
+        self.energy = energy
+
+    def step(self):
+        self.energy -= 1
+        if self.energy <= 0:
+            self.remove()
+```
 
 ### 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.
@@ -118,7 +141,7 @@ Mesa 3 provides both discrete (cell-based) and continuous space implementations.
 
 - Grid-based: `OrthogonalMooreGrid`, `OrthogonalVonNeumanGrid`, and `HexGrid`
 - Network-based: `Network` for graph-based topologies
-- Voronoi-based: `VoronoiMesh` for irregular tessellations
+- Voronoi-based: `VoronoiMesh` for irregular tessellations (where space is divided into cells based on proximity to seed points)
 
 Example grid creation:
 
@@ -152,7 +175,9 @@ from mesa.experimental.cell_space ...
 ```
 
 ### Time advancement
-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.
+Mesa supports two primary approaches to advancing time in simulations: incremental-time progression (tick-based) and next-event time progression
+
+Typically, ABMs represent time in discrete steps (often called "ticks"). For each tick, the model's step method is called, and 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)
@@ -161,7 +186,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 removal of the Scheduler API and its previously available fixed patterns.
+Before Mesa 3, all agents were activated within the step method of the model using predefined schedulers. 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
@@ -185,7 +210,7 @@ Mesa also includes experimental support for next-event time progression through
     model = Model(seed=42, simulator=simulator)
     simulator.schedule_event_relative(some_function, 3.1415)
 
-    # Hybrid time-step and event scheduling (experimental)
+    # Hybrid incremental time and next-event time progression (experimental)
     model = Model(seed=42, simulator=ABMSimulator())
     model.simulator.schedule_event_next_tick(some_function)
 ```
@@ -195,13 +220,13 @@ Mesa’s visualization module, [SolaraViz](https://mesa.readthedocs.io/latest/tu
 
 ```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=model,
+        components=[
+            make_space_component(wolf_sheep_portrayal),          # Grid visualization
+            make_plot_component(["Wolves", "Sheep", "Grass"]),   # Population plot
+            lambda m: f"Step {m.steps}: {len(m.agents)} agents"  # Text display
         ],
-        model_params=parameter_controls
+        model_params=model_params
     )
 ```
 
@@ -248,7 +273,7 @@ Mesa supports systematic parameter exploration:
 ```
 
 # Community and ecosystem
-Mesa has grown into a complete ecosystem with extensions including:
+Mesa has grown into a complete ecosystem with [extensions](https://mesa.readthedocs.io/latest/mesa_extension.html) including:
 
 - [Mesa-Geo](https://github.com/projectmesa/mesa-geo) for geospatial modeling [@wang2022mesa]
 - [Mesa-Frames](https://github.com/projectmesa/mesa-frames) for high-performance simulations
@@ -258,6 +283,6 @@ Mesa has grown into a complete ecosystem with extensions including:
 Mesa 3 introduces significant advancements to the Python ABM framework, enhancing the core toolkit with greater control, interactivity, and speed for researchers. These notable improvements, paired with its foundational integration with the scientific Python ecosystem, modular architecture, and active community, make it an indispensable tool for researchers across disciplines working in Python who want to create and analyze agent-based models.
 
 # Acknowledgements
-The advancements leading to Mesa 3 were developed by six maintainers (the authors) and an active community with over 140 [contributors](https://github.com/projectmesa/mesa/graphs/contributors). We would especially like to thank [David Masad](https://github.com/dmasad) for his foundational work on Mesa.
+The advancements leading to Mesa 3 were developed by seven maintainers (the authors) and an active community with over 140 [contributors](https://github.com/projectmesa/mesa/graphs/contributors). We would especially like to thank [David Masad](https://github.com/dmasad) for his foundational work on Mesa.
 
 # References