Interval Collision Optimizer

Minimize near-collisions between periodic events using simulated annealing.

This repo provides:

• A clean, reusable core library (src/interval_optimizer/core.py)
• A live Streamlit app for interactive visualization (apps/streamlit_app.py)
• Tests and examples to help you get started

---

What it does

Given a set of intervals (in seconds), the optimizer nudges them slightly so that events scheduled every T seconds collide (occur near the same time) as little as possible, according to a user-defined threshold.

---

Quickstart

1) Create a virtual environment (recommended)

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

2) Install dependencies

pip install -r requirements.txt

3) Run the Streamlit app

streamlit run apps/streamlit_app.py

Then open the URL shown in your terminal.

---

CLI Demo (minimal)

python examples/minimal.py

---

Library Usage

from interval_optimizer.core import optimize_intervals, total_near_collisions

intervals = [100, 628, 2500, 504000, 204000]
total, per_pair = total_near_collisions(intervals, threshold=3.0)

result = optimize_intervals(
    initial_intervals=intervals,
    threshold=3.0,
    iterations=5000,
    seed=7
)
print(result["best_intervals"], result["best_total_collisions"])

---