Mesa 3.0.0__py3-none-any.whl → 3.0.0a0__py3-none-any.whl

mesa/experimental/devs/examples/wolf_sheep.py

@@ -1,40 +1,36 @@
-"""Example of using ABM simulator for Wolf-Sheep Predation Model."""
+"""
+Wolf-Sheep Predation Model
+================================
+
+Replication of the model found in NetLogo:
+    Wilensky, U. (1997). NetLogo Wolf Sheep Predation model.
+    http://ccl.northwestern.edu/netlogo/models/WolfSheepPredation.
+    Center for Connected Learning and Computer-Based Modeling,
+    Northwestern University, Evanston, IL.
+"""
 
 import mesa
-from mesa.experimental.cell_space import FixedAgent
 from mesa.experimental.devs.simulator import ABMSimulator
 
 
 class Animal(mesa.Agent):
-    """Base Animal class."""
-
-    def __init__(self, model, moore, energy, p_reproduce, energy_from_food):
-        """Initialize Animal instance.
-
-        Args:
-            model: a model instance
-            moore: using moore grid or not
-            energy: initial energy
-            p_reproduce: probability of reproduction
-            energy_from_food: energy gained from 1 unit of food
-        """
-        super().__init__(model)
+    def __init__(self, unique_id, model, moore, energy, p_reproduce, energy_from_food):
+        super().__init__(unique_id, model)
         self.energy = energy
         self.p_reproduce = p_reproduce
         self.energy_from_food = energy_from_food
         self.moore = moore
 
     def random_move(self):
-        """Move to random neighboring cell."""
         next_moves = self.model.grid.get_neighborhood(self.pos, self.moore, True)
         next_move = self.random.choice(next_moves)
         # Now move:
         self.model.grid.move_agent(self, next_move)
 
     def spawn_offspring(self):
-        """Create offspring."""
         self.energy /= 2
         offspring = self.__class__(
+            self.model.next_id(),
             self.model,
             self.moore,
             self.energy,
@@ -43,15 +39,13 @@ class Animal(mesa.Agent):
         )
         self.model.grid.place_agent(offspring, self.pos)
 
-    def feed(self): ...  # noqa: D102
+    def feed(self): ...
 
     def die(self):
-        """Die."""
         self.model.grid.remove_agent(self)
         self.remove()
 
     def step(self):
-        """Execute one step of the agent."""
         self.random_move()
         self.energy -= 1
 
@@ -64,10 +58,13 @@ class Animal(mesa.Agent):
 
 
 class Sheep(Animal):
-    """A sheep that walks around, reproduces (asexually) and gets eaten."""
+    """
+    A sheep that walks around, reproduces (asexually) and gets eaten.
+
+    The init is the same as the RandomWalker.
+    """
 
     def feed(self):
-        """Eat grass and gain energy."""
         # If there is grass available, eat it
         agents = self.model.grid.get_cell_list_contents(self.pos)
         grass_patch = next(obj for obj in agents if isinstance(obj, GrassPatch))
@@ -77,10 +74,11 @@ class Sheep(Animal):
 
 
 class Wolf(Animal):
-    """A wolf that walks around, reproduces (asexually) and eats sheep."""
+    """
+    A wolf that walks around, reproduces (asexually) and eats sheep.
+    """
 
     def feed(self):
-        """Eat wolf and gain energy."""
         agents = self.model.grid.get_cell_list_contents(self.pos)
         sheep = [obj for obj in agents if isinstance(obj, Sheep)]
         if len(sheep) > 0:
@@ -91,11 +89,13 @@ class Wolf(Animal):
             sheep_to_eat.die()
 
 
-class GrassPatch(FixedAgent):
-    """A patch of grass that grows at a fixed rate and it is eaten by sheep."""
+class GrassPatch(mesa.Agent):
+    """
+    A patch of grass that grows at a fixed rate and it is eaten by sheep
+    """
 
     @property
-    def fully_grown(self) -> bool:  # noqa: D102
+    def fully_grown(self) -> bool:
         return self._fully_grown
 
     @fully_grown.setter
@@ -109,16 +109,15 @@ class GrassPatch(FixedAgent):
                 function_args=[self, "fully_grown", True],
             )
 
-    def __init__(self, model, fully_grown, countdown, grass_regrowth_time):
-        """Creates a new patch of grass.
+    def __init__(self, unique_id, model, fully_grown, countdown, grass_regrowth_time):
+        """
+        Creates a new patch of grass
 
         Args:
-            model: a model instance
-            fully_grown: (boolean) Whether the patch of grass is fully grown or not
+            grown: (boolean) Whether the patch of grass is fully grown or not
             countdown: Time for the patch of grass to be fully grown again
-            grass_regrowth_time: regrowth time for the grass
         """
-        super().__init__(model)
+        super().__init__(unique_id, model)
         self._fully_grown = fully_grown
         self.grass_regrowth_time = grass_regrowth_time
 
@@ -127,12 +126,13 @@ class GrassPatch(FixedAgent):
                 setattr, countdown, function_args=[self, "fully_grown", True]
             )
 
-    def set_fully_grown(self):  # noqa
+    def set_fully_grown(self):
         self.fully_grown = True
 
 
 class WolfSheep(mesa.Model):
-    """Wolf-Sheep Predation Model.
+    """
+    Wolf-Sheep Predation Model
 
     A model for simulating wolf and sheep (predator-prey) ecosystem modelling.
     """
@@ -152,11 +152,10 @@ class WolfSheep(mesa.Model):
         simulator=None,
         seed=None,
     ):
-        """Create a new Wolf-Sheep model with the given parameters.
+        """
+        Create a new Wolf-Sheep model with the given parameters.
 
         Args:
-            height: height of the grid
-            width: width of the grid
             initial_sheep: Number of sheep to start with
             initial_wolves: Number of wolves to start with
             sheep_reproduce: Probability of each sheep reproducing each step
@@ -166,9 +165,7 @@ class WolfSheep(mesa.Model):
             grass_regrowth_time: How long it takes for a grass patch to regrow
                                  once it is eaten
             sheep_gain_from_food: Energy sheep gain from grass, if enabled.
-            moore: whether to use moore or von Neumann grid
-            simulator: Simulator to use for simulating wolf and sheep
-            seed: Random seed
+            moore:
         """
         super().__init__(seed=seed)
         # Set parameters
@@ -194,6 +191,7 @@ class WolfSheep(mesa.Model):
             )
             energy = self.random.randrange(2 * sheep_gain_from_food)
             sheep = Sheep(
+                self.next_id(),
                 self,
                 moore,
                 energy,
@@ -210,6 +208,7 @@ class WolfSheep(mesa.Model):
             )
             energy = self.random.randrange(2 * wolf_gain_from_food)
             wolf = Wolf(
+                self.next_id(),
                 self,
                 moore,
                 energy,
@@ -226,13 +225,14 @@ class WolfSheep(mesa.Model):
                 countdown = grass_regrowth_time
             else:
                 countdown = self.random.randrange(grass_regrowth_time)
-            patch = GrassPatch(self, fully_grown, countdown, grass_regrowth_time)
+            patch = GrassPatch(
+                self.next_id(), self, fully_grown, countdown, grass_regrowth_time
+            )
             self.grid.place_agent(patch, pos)
 
     def step(self):
-        """Perform one step of the model."""
-        self.agents_by_type[Sheep].shuffle_do("step")
-        self.agents_by_type[Wolf].shuffle_do("step")
+        self.get_agents_of_type(Sheep).shuffle(inplace=True).do("step")
+        self.get_agents_of_type(Wolf).shuffle(inplace=True).do("step")
 
 
 if __name__ == "__main__":

mesa/experimental/devs/simulator.py

@@ -1,10 +1,3 @@
-"""Provides several simulator classes.
-
-A Simulator is responsible for executing a simulation model. It controls time advancement and enables event scheduling.
-
-
-"""
-
 from __future__ import annotations
 
 import numbers
@@ -34,12 +27,6 @@ class Simulator:
     # TODO: add experimentation support
 
     def __init__(self, time_unit: type, start_time: int | float):
-        """Initialize a Simulator instance.
-
-        Args:
-            time_unit: type of the smulaiton time
-            start_time: the starttime of the simulator
-        """
         # should model run in a separate thread,
         # and we can then interact with start, stop, run_until, and step?
         self.event_list = EventList()
@@ -49,10 +36,10 @@ class Simulator:
         self.time = self.start_time
         self.model = None
 
-    def check_time_unit(self, time: int | float) -> bool: ...  # noqa: D102
+    def check_time_unit(self, time: int | float) -> bool: ...
 
     def setup(self, model: Model) -> None:
-        """Set up the simulator with the model to simulate.
+        """Set up the simulator with the model to simulate
 
         Args:
             model (Model): The model to simulate
@@ -62,13 +49,12 @@ class Simulator:
         self.model = model
 
     def reset(self):
-        """Reset the simulator by clearing the event list and removing the model to simulate."""
+        """Reset the simulator by clearing the event list and removing the model to simulate"""
         self.event_list.clear()
         self.model = None
         self.time = self.start_time
 
     def run_until(self, end_time: int | float) -> None:
-        """Run the simulator until the end time."""
         while True:
             try:
                 event = self.event_list.pop_event()
@@ -85,7 +71,7 @@ class Simulator:
                 break
 
     def run_for(self, time_delta: int | float):
-        """Run the simulator for the specified time delta.
+        """run the simulator for the specified time delta
 
         Args:
             time_delta (float| int): The time delta. The simulator is run from the current time to the current time
@@ -102,7 +88,7 @@ class Simulator:
         function_args: list[Any] | None = None,
         function_kwargs: dict[str, Any] | None = None,
     ) -> SimulationEvent:
-        """Schedule event for the current time instant.
+        """Schedule event for the current time instant
 
         Args:
             function (Callable): The callable to execute for this event
@@ -130,7 +116,7 @@ class Simulator:
         function_args: list[Any] | None = None,
         function_kwargs: dict[str, Any] | None = None,
     ) -> SimulationEvent:
-        """Schedule event for the specified time instant.
+        """Schedule event for the specified time instant
 
         Args:
             function (Callable): The callable to execute for this event
@@ -164,7 +150,7 @@ class Simulator:
         function_args: list[Any] | None = None,
         function_kwargs: dict[str, Any] | None = None,
     ) -> SimulationEvent:
-        """Schedule event for the current time plus the time delta.
+        """Schedule event for the current time plus the time delta
 
         Args:
             function (Callable): The callable to execute for this event
@@ -188,12 +174,13 @@ class Simulator:
         return event
 
     def cancel_event(self, event: SimulationEvent) -> None:
-        """Remove the event from the event list.
+        """remove the event from the event list
 
         Args:
             event (SimulationEvent): The simulation event to remove
 
         """
+
         self.event_list.remove(event)
 
     def _schedule_event(self, event: SimulationEvent):
@@ -217,29 +204,13 @@ class ABMSimulator(Simulator):
     """
 
     def __init__(self):
-        """Initialize a ABM simulator."""
         super().__init__(int, 0)
 
     def setup(self, model):
-        """Set up the simulator with the model to simulate.
-
-        Args:
-            model (Model): The model to simulate
-
-        """
         super().setup(model)
         self.schedule_event_now(self.model.step, priority=Priority.HIGH)
 
     def check_time_unit(self, time) -> bool:
-        """Check whether the time is of the correct unit.
-
-        Args:
-            time (int | float): the time
-
-        Returns:
-            bool: whether the time is of the correct unit
-
-        """
         if isinstance(time, int):
             return True
         if isinstance(time, float):
@@ -254,9 +225,9 @@ class ABMSimulator(Simulator):
         function_args: list[Any] | None = None,
         function_kwargs: dict[str, Any] | None = None,
     ) -> SimulationEvent:
-        """Schedule a SimulationEvent for the next tick.
+        """Schedule a SimulationEvent for the next tick
 
-        Args:
+        Args
             function (Callable): the callable to execute
             priority (Priority): the priority of the event
             function_args (List[Any]): List of arguments to pass to the callable
@@ -272,7 +243,7 @@ class ABMSimulator(Simulator):
         )
 
     def run_until(self, end_time: int) -> None:
-        """Run the simulator up to and included the specified end time.
+        """run the simulator up to and included the specified end time
 
         Args:
             end_time (float| int): The end_time delta. The simulator is until the specified end time
@@ -299,7 +270,7 @@ class ABMSimulator(Simulator):
                 break
 
     def run_for(self, time_delta: int):
-        """Run the simulator for the specified time delta.
+        """run the simulator for the specified time delta
 
         Args:
             time_delta (float| int): The time delta. The simulator is run from the current time to the current time
@@ -311,24 +282,13 @@ class ABMSimulator(Simulator):
 
 
 class DEVSimulator(Simulator):
-    """A simulator where the unit of time is a float.
-
-    Can be used for full-blown discrete event simulating using event scheduling.
+    """A simulator where the unit of time is a float. Can be used for full-blown discrete event simulating using
+    event scheduling.
 
     """
 
     def __init__(self):
-        """Initialize a DEVS simulator."""
         super().__init__(float, 0.0)
 
     def check_time_unit(self, time) -> bool:
-        """Check whether the time is of the correct unit.
-
-        Args:
-            time (float): the time
-
-        Returns:
-        bool: whether the time is of the correct unit
-
-        """
         return isinstance(time, numbers.Number)

mesa/main.py

@@ -0,0 +1,63 @@
+import os
+import sys
+from pathlib import Path
+from subprocess import call
+
+import click
+
+from mesa import __version__
+
+PROJECT_PATH = click.Path(
+    exists=True, file_okay=False, dir_okay=True, resolve_path=True
+)
+COOKIECUTTER_DIR = "mesa/cookiecutter-mesa"
+SCRIPTS_DIR = os.path.dirname(os.path.abspath(__file__))
+COOKIECUTTER_PATH = os.path.join(os.path.dirname(SCRIPTS_DIR), COOKIECUTTER_DIR)
+
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+@click.group(context_settings=CONTEXT_SETTINGS)
+def cli():
+    "Manage Mesa projects"
+
+
+@cli.command()
+@click.argument("project", type=PROJECT_PATH, default=".")
+def runserver(project):
+    """Run mesa project PROJECT
+
+    PROJECT is the path to the directory containing `run.py`, or the current
+    directory if not specified.
+    """
+    run_files = ["run.py", "server.py"]
+    for run_file in run_files:
+        run_path = Path(project) / run_file
+        if not run_path.exists():
+            continue
+        args = [sys.executable, str(run_path)]
+        call(args)
+    sys.exit(f"ERROR: file run.py or server.py (in {Path(project)}) does not exist")
+
+
+@click.command()
+@click.option(
+    "--no-input", is_flag=True, help="Do not prompt user for custom mesa model input."
+)
+def startproject(no_input):
+    """Create a new mesa project"""
+    args = ["cookiecutter", COOKIECUTTER_PATH]
+    if no_input:
+        args.append("--no-input")
+    call(args)
+
+
+@click.command()
+def version():
+    """Show the version of mesa"""
+    print(f"mesa {__version__}")
+
+
+cli.add_command(runserver)
+cli.add_command(startproject)
+cli.add_command(version)