avoidance-cascade-python

Python implementation of avoidance cascade detection for ternary agents.

Agents hold one of three states: +1 (engaged), 0 (neutral), −1 (avoiding). The library detects when avoidance begins to cascade through a population, models how it spreads, identifies tipping points, and simulates interventions.

Installation

pip install avoidance-cascade

For development:

git clone https://github.com/SuperInstance/avoidance-cascade-python.git
cd avoidance-cascade-python
pip install -e ".[dev]"

Quick Start

Detect a cascade

from avoidance_cascade import CascadeDetector

det = CascadeDetector(window_size=10, threshold=0.5)

# Each call is one time-step; pass a list of agent states
det.observe([1, 0, -1, -1, -1, 0, -1, 1, -1, -1])  # 6/10 avoiding → alert!

print(det.avoidance_ratio)  # 0.6
print(len(det.alerts))      # 1

Model contagion spread

from avoidance_cascade import SpreadModel

model = SpreadModel(population_size=200, contagion_rate=0.35, contact_degree=5, seed=42)
model.seed_avoiders([0, 1, 2])

result = model.simulate(steps=50)
print(f"Peak avoidance: {result.peak_avoidance_ratio:.2%} at step {result.peak_avoidance_step}")
print(f"Estimated R0:   {result.r0_estimate:.3f}")

Detect tipping points

from avoidance_cascade import TippingPointDetector

tp = TippingPointDetector(method="combined", threshold=0.5)
events = tp.analyze([0.05, 0.10, 0.20, 0.45, 0.55, 0.80])

for e in events:
    print(f"Step {e.step}: {e.method} — {e.metric_before:.2f} → {e.metric_after:.2f}")

Simulate interventions

from avoidance_cascade import SpreadModel, InterventionSimulator, Strategy

model = SpreadModel(population_size=100, contagion_rate=0.4, contact_degree=4, seed=42)
model.seed_avoiders([0, 1])

sim = InterventionSimulator(model, seed=42)

# Compare all strategies
results = sim.compare_all(apply_at_step=10, steps=50)
for r in results:
    print(f"{r.strategy.value:15s}  reduction={r.reduction:+.2%}  final={r.final_avoidance_ratio:.2%}")

API Reference

CascadeDetector

Methods: observe(population), run(history), reset()

Properties: avoidance_ratio, engaged_ratio, neutral_ratio, alerts, step

SpreadModel

Methods: seed_avoiders(indices), seed_engaged(indices), step(), simulate(steps), reset()

TippingPointDetector

Methods: observe(ratio), analyze(ratios), reset()

InterventionSimulator

Methods: baseline(steps), simulate_intervention(strategy, ...), compare_all(...)

Running Tests

PYTHONPATH=src pytest tests/ -v

License

MIT © SuperInstance