Add module-level docstring to experimental features (#2532)

EwoutH · web-flow · commit aa839b97f133 · 2024-12-04T20:37:28.000+01:00
* Extend DEVS module-level docstring
* Extend Observables module-level docstring
* Extend Cell Space module-level docstring
* Add Experimental module-level docstring
diff --git a/.codespellignore b/.codespellignore
@@ -7,3 +7,4 @@ ue
 fpr
 falsy
 assertIn
+nD
diff --git a/mesa/experimental/__init__.py b/mesa/experimental/__init__.py
@@ -1,4 +1,19 @@
-"""Experimental init."""
+"""Experimental features package for Mesa.
+
+This package contains modules that are under active development and testing. These
+features are provided to allow early access and feedback from the Mesa community, but
+their APIs may change between releases without following semantic versioning.
+
+Current experimental modules:
+    cell_space: Alternative API for discrete spaces with cell-centric functionality
+    devs: Discrete event simulation system for scheduling events at arbitrary times
+    mesa_signals: Reactive programming capabilities for tracking state changes
+
+Notes:
+    - Features in this package may be changed or removed without notice
+    - APIs are not guaranteed to be stable between releases
+    - Features graduate from experimental status once their APIs are stabilized
+"""
 
 from mesa.experimental import cell_space, devs, mesa_signals
 
diff --git a/mesa/experimental/cell_space/__init__.py b/mesa/experimental/cell_space/__init__.py
@@ -1,8 +1,18 @@
-"""Cell spaces.
+"""Cell spaces for active, property-rich spatial modeling in Mesa.
 
-Cell spaces offer an alternative API for discrete spaces. It is experimental and under development. The API is more
-expressive that the default grids available in `mesa.space`.
+Cell spaces extend Mesa's spatial modeling capabilities by making the space itself active -
+each position (cell) can have properties and behaviors rather than just containing agents.
+This enables more sophisticated environmental modeling and agent-environment interactions.
 
+Key components:
+- Cells: Active positions that can have properties and contain agents
+- CellAgents: Agents that understand how to interact with cells
+- Spaces: Different cell organization patterns (grids, networks, etc.)
+- PropertyLayers: Efficient property storage and manipulation
+
+This is particularly useful for models where the environment plays an active role,
+like resource growth, pollution diffusion, or infrastructure networks. The cell
+space system is experimental and under active development.
 """
 
 from mesa.experimental.cell_space.cell import Cell
diff --git a/mesa/experimental/cell_space/cell.py b/mesa/experimental/cell_space/cell.py
@@ -1,4 +1,16 @@
-"""The Cell in a cell space."""
+"""Cells are positions in space that can have properties and contain agents.
+
+A cell represents a location that can:
+- Have properties (like temperature or resources)
+- Track and limit the agents it contains
+- Connect to neighboring cells
+- Provide neighborhood information
+
+Cells form the foundation of the cell space system, enabling rich spatial
+environments where both location properties and agent behaviors matter. They're
+useful for modeling things like varying terrain, infrastructure capacity, or
+environmental conditions.
+"""
 
 from __future__ import annotations
 
diff --git a/mesa/experimental/cell_space/cell_agent.py b/mesa/experimental/cell_space/cell_agent.py
@@ -1,4 +1,15 @@
-"""An agent with movement methods for cell spaces."""
+"""Agents that understand how to exist in and move through cell spaces.
+
+Provides specialized agent classes that handle cell occupation, movement, and
+proper registration:
+- CellAgent: Mobile agents that can move between cells
+- FixedAgent: Immobile agents permanently fixed to cells
+- Grid2DMovingAgent: Agents with grid-specific movement capabilities
+
+These classes ensure consistent agent-cell relationships and proper state management
+as agents move through the space. They can be used directly or as examples for
+creating custom cell-aware agents.
+"""
 
 from __future__ import annotations
 
diff --git a/mesa/experimental/cell_space/cell_collection.py b/mesa/experimental/cell_space/cell_collection.py
@@ -1,4 +1,17 @@
-"""CellCollection class."""
+"""Collection class for managing and querying groups of cells.
+
+The CellCollection class provides a consistent interface for operating on multiple
+cells, supporting:
+- Filtering and selecting cells based on conditions
+- Random cell and agent selection
+- Access to contained agents
+- Group operations
+
+This is useful for implementing area effects, zones, or any operation that needs
+to work with multiple cells as a unit. The collection handles efficient iteration
+and agent access across cells. The class is used throughout the cell space
+implementation to represent neighborhoods, selections, and other cell groupings.
+"""
 
 from __future__ import annotations
 
diff --git a/mesa/experimental/cell_space/discrete_space.py b/mesa/experimental/cell_space/discrete_space.py
@@ -1,4 +1,17 @@
-"""DiscreteSpace base class."""
+"""Base class for building cell-based spatial environments.
+
+DiscreteSpace provides the core functionality needed by all cell-based spaces:
+- Cell creation and tracking
+- Agent-cell relationship management
+- Property layer support
+- Random selection capabilities
+- Capacity management
+
+This serves as the foundation for specific space implementations like grids
+and networks, ensuring consistent behavior and shared functionality across
+different space types. All concrete cell space implementations (grids, networks, etc.)
+inherit from this class.
+"""
 
 from __future__ import annotations
 
diff --git a/mesa/experimental/cell_space/grid.py b/mesa/experimental/cell_space/grid.py
@@ -1,4 +1,15 @@
-"""Various Grid Spaces."""
+"""Grid-based cell space implementations with different connection patterns.
+
+Provides several grid types for organizing cells:
+- OrthogonalMooreGrid: 8 neighbors in 2D, (3^n)-1 in nD
+- OrthogonalVonNeumannGrid: 4 neighbors in 2D, 2n in nD
+- HexGrid: 6 neighbors in hexagonal pattern (2D only)
+
+Each grid type supports optional wrapping (torus) and cell capacity limits.
+Choose based on how movement and connectivity should work in your model -
+Moore for unrestricted movement, Von Neumann for orthogonal-only movement,
+or Hex for more uniform distances.
+"""
 
 from __future__ import annotations
 
diff --git a/mesa/experimental/cell_space/network.py b/mesa/experimental/cell_space/network.py
@@ -1,4 +1,16 @@
-"""A Network grid."""
+"""Network-based cell space using arbitrary connection patterns.
+
+Creates spaces where cells connect based on network relationships rather than
+spatial proximity. Built on NetworkX graphs, this enables:
+- Arbitrary connectivity patterns between cells
+- Graph-based neighborhood definitions
+- Logical rather than physical distances
+- Dynamic connectivity changes
+- Integration with NetworkX's graph algorithms
+
+Useful for modeling systems like social networks, transportation systems,
+or any environment where connectivity matters more than physical location.
+"""
 
 from random import Random
 from typing import Any
diff --git a/mesa/experimental/cell_space/property_layer.py b/mesa/experimental/cell_space/property_layer.py
@@ -1,4 +1,19 @@
-"""This module provides functionality for working with property layers in grids."""
+"""Efficient storage and manipulation of cell properties across spaces.
+
+PropertyLayers provide a way to associate properties with cells in a space efficiently.
+The module includes:
+- PropertyLayer class for managing grid-wide properties
+- Property access descriptors for cells
+- Batch operations for property modification
+- Property-based cell selection
+- Integration with numpy for efficient operations
+
+This system separates property storage from cells themselves, enabling
+fast bulk operations and sophisticated property-based behaviors while
+maintaining an intuitive interface through cell attributes. Properties
+can represent environmental factors, cell states, or any other grid-wide
+attributes.
+"""
 
 import warnings
 from collections.abc import Callable, Sequence
diff --git a/mesa/experimental/cell_space/voronoi.py b/mesa/experimental/cell_space/voronoi.py
@@ -1,4 +1,16 @@
-"""Support for Voronoi meshed grids."""
+"""Cell spaces based on Voronoi tessellation around seed points.
+
+Creates irregular spatial divisions by building cells around seed points,
+where each cell contains the area closer to its seed than any other.
+Features:
+- Organic-looking spaces from point sets
+- Automatic neighbor determination
+- Area-based cell capacities
+- Natural regional divisions
+
+Useful for models requiring irregular but mathematically meaningful spatial
+divisions, like territories, service areas, or natural regions.
+"""
 
 from collections.abc import Sequence
 from itertools import combinations
diff --git a/mesa/experimental/devs/__init__.py b/mesa/experimental/devs/__init__.py
@@ -1,4 +1,22 @@
-"""Support for event scheduling."""
+"""Core event management functionality for Mesa's discrete event simulation system.
+
+This module provides the foundational data structures and classes needed for event-based
+simulation in Mesa. The EventList class is a priority queue implementation that maintains
+simulation events in chronological order while respecting event priorities. Key features:
+
+- Priority-based event ordering
+- Weak references to prevent memory leaks from canceled events
+- Efficient event insertion and removal using a heap queue
+- Support for event cancellation without breaking the heap structure
+
+The module contains three main components:
+- Priority: An enumeration defining event priority levels (HIGH, DEFAULT, LOW)
+- SimulationEvent: A class representing individual events with timing and execution details
+- EventList: A heap-based priority queue managing the chronological ordering of events
+
+The implementation supports both pure discrete event simulation and hybrid approaches
+combining agent-based modeling with event scheduling.
+"""
 
 from .eventlist import Priority, SimulationEvent
 from .simulator import ABMSimulator, DEVSimulator
diff --git a/mesa/experimental/devs/eventlist.py b/mesa/experimental/devs/eventlist.py
@@ -1,4 +1,22 @@
-"""Eventlist which is at the core of event scheduling."""
+"""Core event management functionality for Mesa's discrete event simulation system.
+
+This module provides the foundational data structures and classes needed for event-based
+simulation in Mesa. The EventList class is a priority queue implementation that maintains
+simulation events in chronological order while respecting event priorities. Key features:
+
+- Priority-based event ordering
+- Weak references to prevent memory leaks from canceled events
+- Efficient event insertion and removal using a heap queue
+- Support for event cancellation without breaking the heap structure
+
+The module contains three main components:
+- Priority: An enumeration defining event priority levels (HIGH, DEFAULT, LOW)
+- SimulationEvent: A class representing individual events with timing and execution details
+- EventList: A heap-based priority queue managing the chronological ordering of events
+
+The implementation supports both pure discrete event simulation and hybrid approaches
+combining agent-based modeling with event scheduling.
+"""
 
 from __future__ import annotations
 
diff --git a/mesa/experimental/devs/simulator.py b/mesa/experimental/devs/simulator.py
@@ -1,8 +1,23 @@
-"""Provides several simulator classes.
-
-A Simulator is responsible for executing a simulation model. It controls time advancement and enables event scheduling.
-
-
+"""Simulator implementations for different time advancement approaches in Mesa.
+
+This module provides simulator classes that control how simulation time advances and how
+events are executed. It supports both discrete-time and continuous-time simulations through
+three main classes:
+
+- Simulator: Base class defining the core simulation control interface
+- ABMSimulator: A simulator for agent-based models that combines fixed time steps with
+  event scheduling. Uses integer time units and automatically schedules model.step()
+- DEVSimulator: A pure discrete event simulator using floating-point time units for
+  continuous time simulation
+
+Key features:
+- Flexible time units (integer or float)
+- Event scheduling using absolute or relative times
+- Priority-based event execution
+- Support for running simulations for specific durations or until specific end times
+
+The simulators enable Mesa models to use traditional time-step based approaches, pure
+event-driven approaches, or hybrid combinations of both.
 """
 
 from __future__ import annotations
diff --git a/mesa/experimental/mesa_signals/__init__.py b/mesa/experimental/mesa_signals/__init__.py
@@ -1,4 +1,14 @@
-"""Functionality for Observables."""
+"""Mesa Signals (Observables) package that provides reactive programming capabilities.
+
+This package enables tracking changes to properties and state in Mesa models through a
+reactive programming paradigm. It enables building models where components can observe
+and react to changes in other components' state.
+
+The package provides the core Observable classes and utilities needed to implement
+reactive patterns in agent-based models. This includes capabilities for watching changes
+to attributes, computing derived values, and managing collections that emit signals
+when modified.
+"""
 
 from .mesa_signal import All, Computable, Computed, HasObservables, Observable
 from .observable_collections import ObservableList
diff --git a/mesa/experimental/mesa_signals/mesa_signal.py b/mesa/experimental/mesa_signals/mesa_signal.py
@@ -1,4 +1,19 @@
-"""Core classes for Observables."""
+"""Core implementation of Mesa's reactive programming system.
+
+This module provides the foundational classes for Mesa's observable/reactive programming
+functionality:
+
+- BaseObservable: Abstract base class defining the interface for all observables
+- Observable: Main class for creating observable properties that emit change signals
+- Computable: Class for properties that automatically update based on other observables
+- HasObservables: Mixin class that enables an object to contain and manage observables
+- All: Helper class for subscribing to all signals from an observable
+
+The module implements a robust reactive system where changes to observable properties
+automatically trigger updates to dependent computed values and notify subscribed
+observers. This enables building models with complex interdependencies while maintaining
+clean separation of concerns.
+"""
 
 from __future__ import annotations
 
diff --git a/mesa/experimental/mesa_signals/observable_collections.py b/mesa/experimental/mesa_signals/observable_collections.py
@@ -1,8 +1,15 @@
-"""This module defines observable collections classes.
+"""Observable collection types that emit signals when modified.
 
-Observable collections behave like Observable but then for collections.
+This module extends Mesa's reactive programming capabilities to collection types like
+lists. Observable collections emit signals when items are added, removed, or modified,
+allowing other components to react to changes in the collection's contents.
 
+The module provides:
+- ObservableList: A list descriptor that emits signals on modifications
+- SignalingList: The underlying list implementation that manages signal emission
 
+These classes enable building models where components need to track and react to
+changes in collections of agents, resources, or other model elements.
 """
 
 from collections.abc import Iterable, MutableSequence
diff --git a/mesa/experimental/mesa_signals/signals_util.py b/mesa/experimental/mesa_signals/signals_util.py
@@ -1,4 +1,13 @@
-"""helper functions and classes for mesa signals."""
+"""Utility functions and classes for Mesa's signals implementation.
+
+This module provides helper functionality used by Mesa's reactive programming system:
+
+- AttributeDict: A dictionary subclass that allows attribute-style access to its contents
+- create_weakref: Helper function to properly create weak references to different types
+
+These utilities support the core signals implementation by providing reference
+management and convenient data structures used throughout the reactive system.
+"""
 
 import weakref
 

-Original file line number
+Diff line change
 fpr
 falsy
 assertIn
 +nD