Skip to content

Feat/event driven simulation - #4

Merged
Rionlyu merged 12 commits into
mainfrom
feat/event-driven-simulation
Jul 13, 2026
Merged

Feat/event driven simulation#4
Rionlyu merged 12 commits into
mainfrom
feat/event-driven-simulation

Conversation

@Rionlyu

@Rionlyu Rionlyu commented Jul 13, 2026

Copy link
Copy Markdown
Owner

Summary

Adds deterministic, event-driven workload simulation to TopoQueue through a new simulate command:

topoqueue simulate \
  --cluster examples/cluster.yaml \
  --jobs examples/timed-jobs.yaml \
  --policy all \
  --output text

TopoQueue can now model job arrivals, queue waiting, topology-aware admission, fixed-duration execution, completion, exact resource release, and retries at subsequent scheduling events.

## What changed

- Added a separate strict timed-workload YAML model and loader.
- Implemented a logical-tick event loop with deterministic ordering:
    1. completions;
    2. arrivals;
    3. admissions.

- Added exact, checked resource reclamation using recorded allocations.
- Implemented strict FIFO and backfill behavior over time.
- Added terminal handling for permanently unschedulable jobs.
- Added lifecycle results, event timelines, and queue-delay metrics.
- Added concurrent, isolated comparison of both timed policies.
- Added stable text and JSON simulation output.
- Added make demo-simulate, a deterministic benchmark, documentation, and lifecycle-focused test coverage.

## Example results

 Policy         Completed    Makespan    Total wait    Average wait    Maximum wait
━━━━━━━━━━━━━  ━━━━━━━━━━━  ━━━━━━━━━━  ━━━━━━━━━━━━  ━━━━━━━━━━━━━━  ━━━━━━━━━━━━━━
 Backfill               3          12             7            2.33               7
─────────────  ───────────  ──────────  ────────────  ──────────────  ──────────────
 Strict FIFO            3          14            17            5.67              10

Backfill reduces queue delay and makespan by using otherwise idle capacity while the larger queue-head job waits for the full cluster.

## Compatibility

- Existing schedule and compare behavior remains unchanged.
- Timed workloads use a separate loader, so existing static input validation and JSON shapes remain stable.
- Simulations use logical integer ticks only—no sleeps, wall-clock time, randomness, or background timers.
- This remains an educational scheduling simulator and does not claim Kubernetes, Kueue, or production-scheduler compatibility.

## Validation

- [x] make fmt-check
- [x] make vet
- [x] make test
- [x] make build
- [x] make demo
- [x] make demo-simulate
- [x] make benchmark
- [x] 20 consecutive package test runs
- [x] Byte-identical text and JSON across three independent renders
- [x] Independent branch review completed with no remaining actionable findings

@Rionlyu
Rionlyu merged commit 9f4ead8 into main Jul 13, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant