Add ContinuousStates and -Observables

[EwoutH]

Summary

Adds ContinuousObservable to mesa_signals, enabling agent states that change continuously over time with automatic threshold detection and signal emission. Demonstrates the feature with an enhanced Wolf-Sheep predator-prey model where energy depletes continuously rather than at discrete time steps.

Motive

Agent-based models often need to represent continuously changing states like energy depletion, resource growth, or temperature changes. Currently, modelers must manually calculate state changes at each step or schedule discrete update events, leading to:

• Balancing trade-offs between update frequency and performance
• Difficulty detecting exact threshold crossings
• No standardized patterns for time-varying states
• Complex coordination of multiple changing states

This addresses discussion #2529 (Continuous States) and provides a foundational building block toward the behavioral framework outlined in discussion #2538, enabling more realistic agent behaviors driven by internal state dynamics.

Implementation

Core Components:

1. ContinuousObservable descriptor: Extends Observable to track values that change over time according to a rate function. Uses lazy evaluation - values are only recalculated when accessed, making it efficient even with many agents.

2. ContinuousState helper class: Internal state tracker storing the current value, last update time, rate function, and threshold set. Handles time-based calculation and threshold crossing detection.

3. Threshold management: HasObservables.add_threshold() provides a clean API for registering callbacks when values cross specific thresholds (upward or downward). Uses the existing signal/observer pattern - thresholds emit "threshold_crossed" signals.

4. Time integration: Automatically detects time source from model.simulator.time, model.time, or falls back to model.steps. Works with both DEVSimulator (float time) and ABMSimulator (integer steps).

Key design decisions:

• Lazy evaluation prevents unnecessary calculations when states aren't accessed
• Threshold storage uses a set (values only), callbacks managed through signal subscriptions to avoid duplicate invocations
• Linear integration for simplicity; extensible to more complex methods
• Fully integrated with existing Computed properties and dependency tracking

API usage examples

# Continuous value with rate per time unit
energy = ContinuousObservable(initial_value: float, rate_func: (value, elapsed, agent) -> float)

# Set/adjust value (emits "change" + checks thresholds)
self.energy = 120.0
self.energy += 5.0

# Thresholds (fires "threshold_crossed" with signal.threshold, signal.direction)
self.add_threshold("energy", 0.0, callback)

# Subscribe to signals
self.observe("energy", "change", on_change)
self.observe("energy", "threshold_crossed", on_threshold)

# Computed properties that depend on observables
is_hungry = Computable()
self.is_hungry = Computed(lambda: self.energy < 50.0)

Usage Examples

Basic continuous energy depletion:

class Wolf(Agent, HasObservables):
    energy = ContinuousObservable(
        initial_value=100.0,
        rate_func=lambda value, elapsed, agent: -agent.metabolic_rate
    )
    
    def __init__(self, model):
        super().__init__(model)
        self.metabolic_rate = 0.5
        self.energy = 100.0
        
        # Die when energy reaches zero
        self.add_threshold("energy", 0.0, self._on_death)
    
    def _on_death(self, signal):
        if signal.direction == "down":
            self.remove()

Reactive behaviors with computed properties:

class Animal(Agent, HasObservables):
    energy = ContinuousObservable(
        initial_value=100.0,
        rate_func=lambda value, elapsed, agent: -agent.metabolic_rate
    )
    is_hungry = Computable()
    
    def __init__(self, model):
        super().__init__(model)
        self.energy = 100.0
        # Computed property automatically updates when energy changes
        self.is_hungry = Computed(lambda: self.energy < 50.0)
    
    def move(self):
        if self.is_hungry:
            # Hunt actively when hungry
            self.seek_food()
        else:
            # Conserve energy when not hungry
            self.wander()

Enhanced Wolf-Sheep model: The updated example demonstrates continuous energy dynamics, threshold-triggered death/starvation modes, and behavior switching based on computed hunger states. Energy depletes continuously between steps rather than in discrete chunks, creating more realistic predator-prey dynamics.

Additional Notes

• Tests: Comprehensive test suite (19 tests) covering basic functionality, signals, edge cases (numpy floats, zero elapsed time, exact thresholds), and integration scenarios
• Backward compatible: Existing mesa_signals code unchanged; ContinuousObservable is an additive feature
• Performance: Lazy evaluation ensures minimal overhead; states only recalculate when accessed
• Future extensions: Foundation for more complex behavioral patterns (needs-based architectures, homeostatic agents) discussed in Behavioral Framework #2538
• Time management: Uses TODO comment to reference The time variable in mesa.Model #2228 regarding universal time handling in Mesa
• Documentation: Wolf-Sheep example serves as practical demonstration; could expand docs with more use cases

This provides the first of two foundational building blocks identified for Mesa's behavioral framework: reactive state management with continuous dynamics. The second block (action/task scheduling) can build naturally on this foundation.

[EwoutH]

I'm a bit mentally exhausted, was a big push to get this finished. I will write up some review points and context later this weekend.

The individual commit messages hopefully contain useful details.

For now:

1. Maybe the new ContinuousObservable and ContinuousState classes should go into a separate file instead of mesa_signals.py.
2. Yes, I know using ContiniousStates with an ABMSimulator (in the wolf_sheep example) doesn't make that much sense in the current implementation. Future work.
3. We really should re-address The time variable in mesa.Model #2228 sooner than later. model.time always being accessible would make stuff much easier.

Curious on initial thoughts!

(CI test failures are unrelated, see widgetti/solara#1110)

[quaquel]

I think this idea is very cool. I hope to find time next week to take a closer look.

One quick question: how is threshold management squared with the lazy evaluation of ContinousStates/ContinuousObservables?

[EwoutH]

Great question:

how is threshold management squared with the lazy evaluation of ContinousStates/ContinuousObservables?

Lazy evaluation and threshold detection work together because thresholds are checked during value recalculation, not continuously. When someone accesses a ContinuousObservable (e.g., agent.energy), the system calculates how much time has elapsed since the last access, computes the new value, and then checks if any thresholds were crossed during that transition.

The key is that we check the range between old and new values, not discrete sample points. With linear integration (value + rate * elapsed_time), we can mathematically determine if a threshold was crossed even if we never computed the value at that exact moment. For example, if energy goes from 100 → 40 over 60 time units and there's a threshold at 50, we detect that crossing because old_value (100) > threshold (50) >= new_value (40).

Important to note: Thresholds fire when values are accessed, not at the exact simulation time they're crossed. If an agent's energy crosses zero at t=50 but nothing accesses it until t=100, the death threshold fires at t=100. This is a fundamental trade-off with lazy evaluation: efficiency in exchange for non-deterministic firing times.

In practice, this isn't an issue for most models because agents access their states during decision-making (e.g., checking is_hungry during movement) and data collectors sample states regularly. For the Wolf-Sheep example, agents effectively check their energy every step through computed properties and movement decisions.

An "eager mode" could be added in the future where registering a threshold automatically schedules a discrete event at the calculated crossing time, providing deterministic timing at the cost of additional event management overhead.

What we do need to enable is non-linear rate functions working with thresholds.

[quaquel]

just nitpicking, but this docstring can use some further elaboration beyond the one line summary. For example, it might be good to give a short explanation of what a treshold is and how it only applies to continuous observables.

[quaquel]

yes this really drives home the need for a proper solution.

Also, time should probably be observable, or easy to be made observable, in which case your ContinuousObservable becomes a subclass of Computable.

[quaquel]

can you indicate whether you are only interested in moving above or moving below, or do you get any crossing of the threshold?

[quaquel]

I don't see anything obviously wrong here. However, it's been a while since I looked at this code, so I might take another look at this PR annd the rest of signals next week. In the meantime, three clarifying questions.

[tpike3]

@EwoutH This is very cool! Thanks for this PR

[EwoutH]

Thanks for your early feedback! I will be in a night train Tuesday evening to Wednesday morning, I probably have some time to further look into it there.

[EwoutH]

Threshold detection for non-linear rate functions is absolutely not trivial. I explored some options here:

• Non-linear rate functions for ContinuousObservable #2854

I'm not sure which direction I'm leaning personally yet.