# TrainSim — train simulation for ATO

Python **simulation** of a train on a circular route. Provides the plant model that **[ATO](https://git.italiatts.online/rwsholdem/ato)** controls.

| | |
|---|---|
| **Forgejo** | https://git.italiatts.online/rwsholdem/trainsim |
| **Language** | Python (FastAPI) |
| **Role** | Physics, REST API, live route map |

## What it does

1. Simulates 1-D motion on a **loop track** (configurable length).
2. Exposes a **lean HTTP API** (see `spec/interface.md` — same contract as ATO).
3. Serves a **route map** at `/` — nodes, edges, moving train dot.
4. Optional door commands are accepted and logged as signals (no real doors).

## Repository layout

| Path | Purpose |
|------|---------|
| `trainsim/` | FastAPI app, physics engine, config loader |
| `config/sim.default.json` | Physics gains, tick rate, max speed |
| `config/track.default.json` | Node positions + edge lengths (loop) |
| `spec/` | Interface contract + JSON examples (mirrors ATO repo) |
| `static/map.html` | Browser map UI |
| `tests/` | pytest (physics + API) |

## Interface (summary)

See [`spec/interface.md`](spec/interface.md).

| Method | Path | Body |
|--------|------|------|
| GET | `/train/state` | — |
| POST | `/train/actuate` | `{ traction_pct, brake_pct }` |
| POST | `/sim/start` | — |
| POST | `/sim/stop` | — |
| POST | `/train/doors` | `{ "command": "open" \| "close" }` (signal only) |

## Build & test

```bash
pip install -r requirements.txt
pytest -q
docker build -t trainsim .
```

## Run locally

```bash
uvicorn trainsim.app:create_app --factory --host 0.0.0.0 --port 8080
```

Open http://localhost:8080/ for the map.

## Run with ATO

See ATO repo — `./run-e2e.sh` in CodeView `profiles/ato-lab` builds both images in nested DinD and runs a 15 s cruise demo.

---

*Detailed simulation notes — to be expanded in a later README revision.*