Reactor-Sim/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

All source code lives under src/reactor_sim. Submodules map to plant systems: fuel.py and neutronics.py govern fission power, thermal.py and coolant.py cover heat transfer and pumps, turbine.py drives the steam cycle, and consumer.py represents external electrical loads. High-level coordination happens in reactor.py and simulation.py. The convenience runner run_simulation.py executes the default scenario; add notebooks or scenario scripts under experiments/ (create as needed). Keep assets such as plots or exported telemetry inside artifacts/.

Build, Test, and Development Commands

• python -m reactor_sim.simulation — run the default 10-minute transient and print JSON snapshots.
• python run_simulation.py — same as above, handy for IDE launch configs.
• python -m pip install -e .[dev] — install editable package with optional tooling when dev dependencies are defined.

Operations & Control Hooks

Manual commands live in reactor_sim.commands.ReactorCommand. Pass a command_provider callable to ReactorSimulation to adjust rods, pumps, turbine, coolant demand, or the attached ElectricalConsumer. Use ReactorCommand.scram_all() for full shutdown, ReactorCommand(consumer_online=True, consumer_demand=600) to hook the grid, or toggle pumps (primary_pump_on=False) to simulate faults. Control helpers in control.py expose set_rods, increment_rods, and scram, and you can switch set_manual_mode(True) to pause the automatic rod controller. For hands-on runs, launch the curses dashboard (FISSION_DASHBOARD=1 FISSION_REALTIME=1 python run_simulation.py) and use the on-screen shortcuts (q quit/save, space SCRAM, p/o pumps, t turbine, +/- rods in 0.05 steps, [/ ] consumer demand, s/d setpoint, a toggles auto/manual rods). Recommended startup: enable manual rods (a), withdraw to ~0.3 before ramping the turbine/consumer, then re-enable auto control when you want closed-loop operation. The plant now boots cold (ambient core temperature, idle pumps); scripts must sequence startup: enable pumps, gradually withdraw rods, connect the consumer after turbine spin-up, and use ControlSystem.set_power_setpoint to chase desired output. Set FISSION_REALTIME=1 to run continuously with real-time pacing; optionally set FISSION_SIM_DURATION=infinite for indefinite runs and send SIGINT/Ctrl+C to stop. Use FISSION_SIM_DURATION=600 (default) for bounded offline batches.

Coding Style & Naming Conventions

Use Python 3.10+ with type hints and dataclasses. Stick to PEP 8 plus 4-space indentation. Module names remain lowercase with underscores mirroring plant subsystems (control.py, turbine.py). Exported classes use PascalCase (ReactorSimulation), internal helpers stay snake_case. Keep docstrings concise and prefer explicit units inside attribute names to avoid ambiguity.

Testing Guidelines

Pytest is the preferred framework. Place tests under tests/ mirroring the reactor_sim tree (e.g., tests/test_neutronics.py). Name fixtures after the system (e.g., primary_loop). Each PR should add regression tests for new physical models, persistence helpers, and failure paths (core power within ±5% plus expected component integrity behavior). Run python -m pytest locally before opening a pull request.

Commit & Pull Request Guidelines

Write commits in imperative mood (Add turbine moisture separator model). Squash small WIP commits before review. Pull requests must describe the scenario, attach log excerpts (snapshots.json diff) or plots for novel behavior, and link to any tracking issues. Include validation notes: commands run, expected trends (e.g., outlet temperature increase), and outstanding risks.

Safety & Configuration

Sim parameters live in constructors; never hard-code environment-specific paths. When adding new physics, guard unstable calculations with clamps and highlight operating limits in comments. Sensitive experiments (e.g., beyond design basis) should default to disabled flags so scripted studies remain safe by default.

Reliability & Persistence

Component wear is tracked via failures.py; stress from overheating, pump starvation, or turbine imbalance will degrade integrity and eventually disable the affected subsystem with automatic SCRAM for core damage. Persist plant snapshots with ControlSystem.save_state()/load_state() (used by Reactor.save_state/load_state) so long-running studies can resume; FISSION_LOAD_STATE/FISSION_SAVE_STATE env vars wire this into the CLI.