Summary

Adds a manual dirty-flag optimization to AgentDataSet to avoid repeated data extraction within the same simulation instant. This is implemented as a pull-based caching mechanism that recomputes only when explicitly invalidated.

Adds the dirty flag function mentioned in #3341

Motive

AgentDataSet.data currently recomputes the snapshot on every access. When datasets are reused within the same simulation instant, this results in redundant extraction work. This change introduces a manual set_dirty_flag() method so model code can explicitly mark the dataset as stale when needed.

Implementation

Added two internal attributes to AgentDataSet, _is_dirty and _cache and modified .data to recompute only if _is_dirty is True or _cache is None, otherwise return cached snapshot

Added a function,

def set_dirty_flag(self) -> None

which marks the dataset as dirty for the next access.

Usage Examples

dataset = AgentDataSet("wealth", model.agents, fields="wealth")

# First access computes snapshot
snapshot = dataset.data

# Reuse within same instant (cached)
snapshot_again = dataset.data

# After model mutation
dataset.set_dirty_flag()
updated_snapshot = dataset.data

Additional Notes

• This change alters identity behavior so that repeated .data access now returns the same list object until invalidated.
• Snapshot values and timing semantics remain unchanged and returned snapshot remains mutable.
• Added tests to cover the new changes