modelly-abm 1.0.0__py3-none-any.whl

modelly/__init__.py

@@ -0,0 +1,37 @@
+"""Modelly Agent-Based Modeling Framework.
+
+Core Objects: Model, and Agent.
+"""
+
+import datetime
+
+import modelly.discrete_space as discrete_space
+import modelly.experimental as experimental
+import modelly.time as time
+from modelly.agent import Agent
+from modelly.batch import run_batch, run_grid
+from modelly.cohorts import CohortTable
+from modelly.columns import Column
+from modelly.datacollection import DataCollector
+from modelly.model import Model
+from modelly.rng import FastRandom
+
+__all__ = [
+    "Agent",
+    "CohortTable",
+    "Column",
+    "DataCollector",
+    "FastRandom",
+    "Model",
+    "discrete_space",
+    "experimental",
+    "run_batch",
+    "run_grid",
+    "time",
+]
+
+__title__ = "modelly"
+__version__ = "1.0.0"
+__license__ = "Apache 2.0"
+_this_year = datetime.datetime.now(tz=datetime.UTC).date().year
+__copyright__ = f"Copyright {_this_year} Modelly Team"

modelly/agent.py

@@ -0,0 +1,282 @@
+"""Agent related classes.
+
+Core Objects: Agent.
+"""
+
+# Postpone annotation evaluation to avoid NameError from forward references (PEP 563). Remove once Python 3.14+ is required.
+from __future__ import annotations
+
+import itertools
+from random import Random
+from typing import TYPE_CHECKING, ClassVar
+
+import numpy as np
+import pandas as pd
+
+if TYPE_CHECKING:
+    from modelly.model import Model
+
+from modelly.agentset import AgentSet, _resolve_per_agent_values
+from modelly.column_access import collect_column_specs, install_column_properties
+from modelly.columns import Column
+
+
+class Agent[M: Model]:
+    """Base class for a model agent in Modelly.
+
+    Attributes:
+        model (Model): A reference to the model instance.
+        unique_id (int): A unique identifier for this agent.
+
+    Notes:
+        Agents must be hashable to be used in an AgentSet.
+        In Python 3, defining `__eq__` without `__hash__` makes an object unhashable,
+        which will break AgentSet usage.
+        unique_id is unique relative to a model instance and starts from 1
+
+    """
+
+    _datasets: ClassVar = set()
+    _column_specs: ClassVar[dict[str, Column]] = {}
+    _column_row: int = -1  # instance attribute once the agent has a column row
+    # True when no class after Agent in the MRO defines __init__, so the
+    # cooperative super().__init__() would only reach object.__init__.
+    _plain_init: ClassVar[bool] = True
+    # True when the class has columns or datasets to update on birth and death.
+    _extra_hooks: ClassVar[bool] = False
+    _repr_excluded_fields: ClassVar[set[str]] = {
+        "model",
+        "current_action",
+        "unique_id",
+        "_column_table",
+        "_column_row",
+    }
+
+    def __init_subclass__(cls, **kwargs):
+        """Called when Agent is subclassed, giving each subclass its own dataset set."""
+        super().__init_subclass__(**kwargs)
+        # Each subclass gets its own dataset set
+        # we use strings on this to avoid memory leaks
+        # and ensure the retrieved dataset belongs to the same
+        # model instance as the agent
+        cls._datasets = set()
+        # Columns declared on this class or inherited, in MRO order; each one is
+        # replaced on the class by a fast property (see modelly.column_access).
+        specs = collect_column_specs(cls)
+        cls._column_specs = specs
+        install_column_properties(cls, specs)
+        after_agent = cls.__mro__[cls.__mro__.index(Agent) + 1 : -1]
+        cls._plain_init = not any("__init__" in vars(base) for base in after_agent)
+        cls._extra_hooks = bool(specs)
+
+    def __init__(self, model: M, *args, **kwargs) -> None:
+        """Create a new agent.
+
+        Args:
+            model (Model): The model instance in which the agent exists.
+            args: Passed on to super.
+            kwargs: Passed on to super.
+
+        Notes:
+            to make proper use of python's super, in each class remove the arguments and
+            keyword arguments you need and pass on the rest to super
+        """
+        if args or kwargs:
+            super().__init__(*args, **kwargs)
+        elif not self._plain_init:
+            super().__init__()  # a cooperative base class needs the call
+
+        self.model: M = model
+        if model._quiet:
+            # Model.register_agent written out for the common case (default
+            # registry, nobody listening): a birth is the hottest path in
+            # lifecycle-heavy models. Kept in sync with it (tested).
+            model._all_agents[self] = None
+            self.unique_id = model.agent_id_counter
+            model.agent_id_counter += 1
+            try:
+                model._agents_by_type[type(self)][self] = None
+            except KeyError:
+                model._register_new_type(self)
+        else:
+            self.unique_id = None
+            model.register_agent(self)
+        if self._extra_hooks:
+            if self._column_specs:
+                model.columns.register(self)
+            for dataset in self._datasets:
+                model.data_registry[dataset].add_agent(self)
+
+    @classmethod
+    def column_specs(cls) -> dict[str, Column]:
+        """The ``Column`` declarations of this class (name to column), in table order.
+
+        On the class, a column attribute is the fast property that reads the
+        agent's row; this returns the declarations themselves (dtype, default).
+        """
+        return dict(cls._column_specs)
+
+    def remove(self) -> None:
+        """Remove and delete the agent from the model."""
+        # try/except rather than contextlib.suppress: the context manager costs
+        # about 300 ns per call and this runs on every agent death.
+        model = self.model
+        try:
+            if model._quiet:
+                # Model.deregister_agent written out; see __init__.
+                del model._agents_by_type[type(self)][self]
+                del model._all_agents[self]
+            else:
+                model.deregister_agent(self)
+        except KeyError:
+            pass  # already removed
+        if self._extra_hooks:
+            if self._column_specs and self._column_row >= 0:
+                model.columns.unregister(self)
+            # ensures models are also removed from datasets
+            for dataset in self._datasets:
+                model.data_registry[dataset].remove_agent(self)
+
+    def step(self) -> None:
+        """A single step of the agent."""
+
+    def advance(self) -> None:  # noqa: D102
+        pass
+
+    @classmethod
+    def create_agents[T: Agent](
+        cls: type[T], model: Model, n: int, *args, **kwargs
+    ) -> AgentSet[T]:
+        """Create N agents.
+
+        Args:
+            model: the model to which the agents belong
+            args: arguments to pass onto agent instances
+                  each arg is either a single object or a sequence of length n
+            n: the number of agents to create
+            kwargs: keyword arguments to pass onto agent instances
+                   each keyword arg is either a single object or a sequence of length n
+
+        Returns:
+            AgentSet containing the agents created.
+
+        Warning:
+            A list, tuple, ndarray, or pandas Series argument is treated as one
+            value per agent and must have length n; a length mismatch raises
+            ValueError. This is especially easy to hit with coordinate tuples:
+            create_agents(model, 2, pos=(10, 20)) does NOT give both agents
+            pos=(10, 20); it gives agent 0 pos=10 and agent 1 pos=20, since the
+            tuple's length (2) matches n (2).
+
+            To assign the same sequence value to every agent, broadcast it
+            explicitly as a length-n list of that value, e.g.:
+            create_agents(model, 2, pos=[(10, 20)] * 2)
+
+        Raises:
+            ValueError: If a sequence argument's length does not match n.
+
+        """
+        agents = []
+
+        if not args and not kwargs:
+            for _ in range(n):
+                agents.append(cls(model))
+            return AgentSet(agents, random=model.random)
+
+        # Prepare positional argument iterators. A sequence must have length n
+        # (assigned per agent); a length mismatch raises. Anything else is broadcast.
+        arg_iters = [_resolve_per_agent_values(arg, n) for arg in args]
+
+        # Prepare keyword argument iterators
+        kw_keys = list(kwargs.keys())
+        kw_val_iters = [_resolve_per_agent_values(v, n) for v in kwargs.values()]
+
+        # If arg_iters is empty, zip(*[]) returns nothing, so we use repeat(())
+        pos_iter = zip(*arg_iters) if arg_iters else itertools.repeat(())
+
+        kw_iter = zip(*kw_val_iters) if kw_val_iters else itertools.repeat(())
+
+        # We rely on range(n) to drive the loop length
+        if kwargs:
+            for _, p_args, k_vals in zip(range(n), pos_iter, kw_iter):
+                agents.append(cls(model, *p_args, **dict(zip(kw_keys, k_vals))))
+        else:
+            for _, p_args in zip(range(n), pos_iter):
+                agents.append(cls(model, *p_args))
+
+        return AgentSet(agents, random=model.random)
+
+    @classmethod
+    def from_dataframe[T: Agent](
+        cls: type[T], model: Model, df: pd.DataFrame, **kwargs
+    ) -> AgentSet[T]:
+        """Create agents from a pandas DataFrame.
+
+        Each row of the DataFrame represents one agent. The DataFrame columns are
+        mapped to the agent's constructor as keyword arguments. Additional keyword
+        arguments (`**kwargs`) can be used to set constant attributes for all agents.
+
+        Args:
+            model: The model instance.
+            df: The pandas DataFrame. Each row represents an agent.
+            **kwargs: Constant values to pass to every agent's constructor.
+                Only non-sequence data is allowed in kwargs to avoid ambiguity
+                with DataFrame columns.
+
+        Returns:
+            AgentSet containing the agents created.
+
+        Note:
+            If you need to pass variable data or sequences, add them as columns
+            to the DataFrame before calling this method.
+        """
+        for key, value in kwargs.items():
+            if isinstance(value, (list, np.ndarray, tuple, pd.Series)):
+                raise TypeError(
+                    f"from_dataframe does not support sequence data in kwargs ('{key}'). "
+                    "Please add this data to the DataFrame before calling from_dataframe."
+                )
+
+        agents = [
+            cls(model, **{**record, **kwargs})
+            for record in df.to_dict(orient="records")
+        ]
+
+        return AgentSet(agents, random=model.random)
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation of the agent."""
+        return f"{self.__class__.__name__}, agent_id = {self.unique_id}"
+
+    def __repr__(self) -> str:
+        """Return an unambiguous string representation including agent state."""
+        # Get excluded fields (allows subclasses to override)
+        excluded = self._repr_excluded_fields
+
+        # Get user-defined attributes (exclude private and Modelly fields)
+        user_attrs = {
+            k: v
+            for k, v in self.__dict__.items()
+            if not k.startswith("_") and k not in excluded
+        }
+
+        if user_attrs:
+            attr_str = ", ".join(f"{k}={v!r}" for k, v in user_attrs.items())
+            return f"<{self.__class__.__name__} id={self.unique_id} {attr_str}>"
+        else:
+            return f"<{self.__class__.__name__} id={self.unique_id}>"
+
+    @property
+    def random(self) -> Random:
+        """Return a seeded stdlib rng."""
+        return self.model.random
+
+    @property
+    def rng(self) -> np.random.Generator:
+        """Return a seeded np.random rng."""
+        return self.model.rng
+
+    @property
+    def scenario(self):
+        """Return the scenario associated with the model."""
+        return self.model.scenario

modelly/agentset/__init__.py

@@ -0,0 +1,36 @@
+"""AgentSet related classes.
+
+Core Objects: AgentSet, AbstractAgentSet, _HardKeyAgentSet, GroupBy.
+
+Storage model
+-------------
+Both concrete sets are *ordered sets* backed by a ``dict`` whose values are
+always ``None``; the dict gives O(1) membership and removal while preserving
+insertion order (so shuffles and sorts are stable and reproducible).
+
+* :class:`AgentSet` keys the dict on ``weakref.ref`` objects. A removed agent
+  that nothing else references disappears from every ``AgentSet`` on its own.
+  This is the type every *view* (select, shuffle, sort, groupby, ...) returns.
+* :class:`_HardKeyAgentSet` keys the dict on the agents themselves. It is used
+  only for the registries owned by :class:`~modelly.model.Model` whose lifecycle
+  is explicit (``Agent.__init__`` / ``Agent.remove``).
+
+Every bulk operation first takes a C-level snapshot (``list(dict)``) and then
+walks the snapshot, so user code that adds or removes agents mid-iteration can
+never corrupt the dict being walked.
+"""
+
+from modelly.agentset._utils import _resolve_per_agent_values, _resolve_weights
+from modelly.agentset.abstract import AbstractAgentSet
+from modelly.agentset.groupby import GroupBy
+from modelly.agentset.strong import _HardKeyAgentSet
+from modelly.agentset.weak import AgentSet
+
+__all__ = [
+    "AbstractAgentSet",
+    "AgentSet",
+    "GroupBy",
+    "_HardKeyAgentSet",
+    "_resolve_per_agent_values",
+    "_resolve_weights",
+]

modelly/agentset/_utils.py

@@ -0,0 +1,132 @@
+"""Helpers shared by the AgentSet implementations."""
+
+from __future__ import annotations
+
+import itertools
+import math
+import warnings
+from collections.abc import Callable, Iterable, Sequence
+from random import Random
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+import pandas as pd
+
+if TYPE_CHECKING:
+    from modelly.agent import Agent
+
+
+_MISSING = object()
+_INF = float("inf")
+
+
+def _resolve_weights(
+    agents: Sequence[Agent],
+    weights: str | Callable[[Agent], float] | Sequence[float],
+) -> list[float]:
+    """Extract and validate numerical weights for a sequence of agents.
+
+    Args:
+        agents: The sequence of agents to extract weights for.
+        weights: Agent attribute name (str), weight callable, or sequence of floats.
+
+    Returns:
+        list[float]: Validated list of non-negative weights with positive sum.
+
+    Raises:
+        TypeError: If weights is of an unsupported type.
+        ValueError: If sequence length does not match, if any weight is negative, or if total sum <= 0.
+    """
+    if isinstance(weights, str):
+        w = [getattr(agent, weights) for agent in agents]
+    elif callable(weights):
+        w = [weights(agent) for agent in agents]
+    elif isinstance(weights, Sequence):
+        if len(weights) != len(agents):
+            raise ValueError(
+                f"Length of weights ({len(weights)}) does not match AgentSet length ({len(agents)})"
+            )
+        w = list(weights)
+    else:
+        raise TypeError(
+            f"Unsupported weights type: {type(weights).__name__}. "
+            "Expected str, Callable, Sequence[float], or None."
+        )
+
+    if not all(map(math.isfinite, w)):
+        raise ValueError("All weights must be finite.")
+    if any(x < 0 for x in w):
+        raise ValueError("All weights must be non-negative.")
+    if sum(w) <= 0:
+        raise ValueError("Sum of weights must be strictly positive.")
+
+    return w
+
+
+def _resolve_per_agent_values(value: Any, n: int, *, strict: bool = True) -> Iterable:
+    """Resolve ``value`` into an iterable of ``n`` per-agent values.
+
+    A ``list``, ``tuple``, ``numpy.ndarray`` or ``pandas.Series`` of length ``n``
+    is treated as one value per agent. Any other value (a scalar, a string, or a
+    non-sequence) is broadcast to all ``n`` agents.
+
+    Args:
+        value: The value(s) to assign, either one per agent or broadcast.
+        n: The number of agents to produce values for.
+        strict: If True (the default), a sequence whose length is not ``n`` raises
+            ValueError. If False, such a sequence is broadcast to every agent (the
+            whole sequence becomes each agent's value).
+
+    Returns:
+        An iterable yielding exactly ``n`` values.
+
+    Raises:
+        ValueError: If ``strict`` and ``value`` is a sequence whose length is
+            not ``n``.
+    """
+    if isinstance(value, (list, tuple, np.ndarray, pd.Series)):
+        if len(value) == n:
+            return value
+        if strict:
+            raise ValueError(
+                f"sequence of length {len(value)} does not match the number "
+                f"of agents ({n})"
+            )
+    return itertools.repeat(value, n)
+
+
+def _resolve_random(random: Random | None, first_agent: Agent | None) -> Random:
+    """Pick the rng for a new set: the one given, else the first agent's model rng.
+
+    Falls back to a fresh, unseeded ``Random`` (with a warning) when the set is
+    empty and no rng was given, since there is then nothing to derive one from.
+    """
+    if random is not None:
+        return random
+    if first_agent is not None:
+        # all agents in an AgentSet should share the same model, just take it from first
+        return first_agent.model.random
+    warnings.warn(
+        "No Agents specified in creation of AgentSet and no random number generator specified. "
+        "This can make models non-reproducible. Please pass a random number generator explicitly",
+        UserWarning,
+        stacklevel=3,
+    )
+    return Random()
+
+
+def _validate_at_most(at_most: int | float, size: int) -> int | float:
+    """Validate ``at_most`` for select-like methods and resolve fractions to counts."""
+    if isinstance(at_most, bool) or not isinstance(at_most, (int, float)):
+        raise TypeError(
+            f"at_most must be an integer or float, got {type(at_most).__name__}."
+        )
+    if isinstance(at_most, float) and at_most != _INF:
+        if not (0.0 < at_most <= 1.0):
+            raise ValueError(
+                f"Fractional at_most must be in the range (0.0, 1.0], got {at_most}."
+            )
+        return int(size * at_most)  # Note that it rounds down (floor)
+    if isinstance(at_most, int) and at_most < 0:
+        raise ValueError(f"Integer at_most must be non-negative, got {at_most}.")
+    return at_most