Batch AV scenario validation on Ray, built on Argoverse 2 Motion Forecasting.

Real AV2 trajectories and map archives flow through a distributed sim → metrics pipeline with Job UI, HTML viz, and a one-click demo — from zero-install browser preview to live Ray jobs on fetched mini subsets.

Real Argoverse 2 trajectories and map geometry — scrub the timeline in your browser (zero install):

open examples/demo_viz/av2_0003904f-371d-4544-8712-5f4eff74ef91.html   # PASS collision + lane keeping

Scenario	Metrics	Preview
0003904f-…	PASS collision + lane_keeping	Open HTML locally
0000b0f9-…	FAIL lane_keeping only
0000b6ab-…	FAIL collision + lane_keeping

More viewers: examples/demo_viz/README.md.

After bash scripts/run_av2_demo.sh or raysim submit --source av2 ...:

	Overview — local Ray cluster during an AV2 job
	Actors — sim-<job_id>-* SimActor pool
	Ray Core — distributed sim stage in the batch pipeline

Tier 0 — zero install: open the HTML above (known PASS on collision + lane keeping).

Tier 1 — full AV2 pipeline: one script installs deps, fetches one scenario, submits a Ray job, and prints next steps:

bash scripts/run_av2_demo.sh
bash scripts/run_av2_demo.sh --html-only   # tier 0 only
bash scripts/run_av2_demo.sh --help

Tier 2 — synthetic (CI-friendly):

pip install -e ".[dev]"
python examples/run_local.py              # generate → submit → print status
raysim submit --scenarios ./data/scenarios --fake-gpus 4 --fail-rate 0.1

Requirements: Python 3.10+, pip, venv recommended. Source of truth: pyproject.toml.

cd raysim
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"       # synthetic + tests
pip install -e ".[dev,av2]"   # + Argoverse 2 adapter
pip install -e ".[dev,av2,ui]" # + Job UI

System tools (not pip): s5cmd or aws CLI for AV2 mini download (scripts/fetch_av2_mini.sh).

• Ray batch pipeline — SimActor pool with fake-GPU scheduling, streaming ray.wait, collision + lane-keeping validators
• Job UI — FastAPI app to submit, monitor, and view results
• AV2 adapter — Argoverse 2 Motion Forecasting ingest + mini fetch script
• HTML viz — bird's-eye scrubber (pre-baked demos + on-demand from Job UI)
• CLI — raysim submit, status, results

Throughput benchmarks: docs/reliability.md.

• docs/architecture.md — Ray-enhanced pipeline design
• docs/reliability.md — scheduler, retries, benchmarks

raysim/
├── raysim/                 # Python package
│   ├── models.py           # Scenario + job/sim/metric schemas
│   ├── runtime.py          # Ray init with fake_gpu
│   ├── sim/                # SimActor pool
│   ├── metrics/            # CPU metrics runner
│   ├── validators/         # Collision + lane-keeping
│   ├── job.py              # Driver (ray.wait streaming)
│   ├── storage.py          # LocalStore
│   ├── meta/               # SQLite job meta
│   ├── adapters/           # ScenarioAdapter + AV2 stub/fixture
│   └── cli.py              # raysim submit / status / results
├── scripts/
│   ├── generate_scenarios.py
│   ├── fetch_av2_mini.sh   # AV2 Motion Forecasting mini subset
│   └── run_av2_demo.sh     # One-click AV2 install → fetch → submit
├── benchmarks/
│   └── run_benchmark.py    # Sequential vs Ray fake_gpus sweep
├── examples/
│   ├── run_local.py        # One-shot local demo
│   └── demo_viz/           # Pre-baked HTML (primary: av2_*.html from real AV2)
├── tests/
└── docs/
    ├── architecture.md
    ├── reliability.md
    ├── roadmap.md
    └── phase-implementation.md

MIT