SimLab — Command-Line PWR Simulator

A retro 1970s-mainframe-style Pressurized Water Reactor simulator, controlled entirely from the command line.

What Is This?

SimLab is a Python-based nuclear reactor simulator that models the essential physics of a PWR (Pressurized Water Reactor). You operate the reactor from a terminal interface styled after 1970s mainframe consoles — uppercase text, live ASCII bar gauges, and keyboard controls.

The physics are simplified but grounded: point kinetics for neutronics, lumped-parameter thermal-hydraulics, and a "magic xenon" system that compresses real-world timescales so you can experience xenon poisoning transients in minutes instead of hours.

Features

Reactor Physics

• Neutronics — Point kinetics with 6 delayed neutron precursor groups, reactivity feedback, and external neutron source
• Reactivity — Summed from rod worth, Doppler feedback, moderator temperature feedback, xenon, samarium, and boron contributions
• Xenon Poisoning — I-135/Xe-135 decay chain with adjustable magic time scaler (up to 360x compression)
• Samarium Poisoning — Pm-149/Sm-149 chain modeling the stable Sm-149 absorber (removal by neutron capture only)
• Thermal-Hydraulics — 3-node lumped model: fuel temperature, hot leg, and cold leg with average coolant tracking
• Steam Generator — Primary-to-secondary heat transfer with operator-controlled throttle valve
• Decay Heat — 3-group ANS-standard model with short, medium, and long-lived fission product contributions
• Control Rods — Two independent groups with sin²-shaped differential worth curves, 228 discrete steps each, and gravity-drop SCRAM
• Boron Control — Continuous borate/dilute operations affecting reactivity (toggleable)
• Pressurizer — Pressure and level dynamics with heater and spray controls, coupled to average coolant temperature (toggleable)

Instruments and Monitoring

• Neutron Detectors — Three overlapping ranges: source range (CPS), intermediate range (decades), and power range (% rated)
• Alarm System — 11 threshold alarms with hysteresis deadbands, WARNING/ALARM severity levels, and operator acknowledgement (toggleable)

Automation

• Go Critical — Adaptive rod withdrawal state machine with burst sizing and criticality detection
• Power Ascension — Automated ramp to 50% power with proportional control and stability monitoring
• Load Follow — Rod Group 2 and throttle tracking to 75% power with control deadband to prevent hunting
• Mutual Exclusion — Only one automation script active at a time; manual rod keys abort active automation

Training Scenarios

• Startup to Power — Take the reactor from cold shutdown to 50% power and hold stable
• Xenon Transient — Manage a power reduction from 100% to 50% while xenon dynamics shift reactivity
• Emergency Shutdown — SCRAM the reactor and cool down below 200°C before fuel limits are reached

Save and Load

• Quick Save — F5 saves full reactor state to a timestamped JSON file
• Resume — Load a saved state from the command line and continue in sandbox mode
• Migration — v1 save files automatically upgraded with v2 defaults

Display

• 8-region terminal layout: header, power gauge, temperatures, rod positions, plant systems, alarm panel, event log, and key legend
• Log-scale power gauge spanning source range through 120% rated power
• Scrolling timestamped event log with action throttling
• Retro mainframe aesthetic — minimum 80x32 terminal

Controls

Key	Action
W / S	Raise / Lower Rod Group 1
E / D	Raise / Lower Rod Group 2
R / F	Open / Close Steam Throttle
A / Z	Borate / Dilute (boron control)
X	Stop boron change
H	Toggle pressurizer heaters
J	Toggle pressurizer spray
K	Acknowledge alarms
T	Cycle time warp (1x → 10x → 100x)
G	Toggle go-critical automation
P	Toggle power ascension to 50%
L	Toggle load follow to 75%
SPACE	SCRAM
F5	Save reactor state
Q	Quit

Usage

python -m simlab                  # Sandbox mode (all features)
python -m simlab --scenario 1     # Startup to Power scenario
python -m simlab --scenario 2     # Xenon Transient scenario
python -m simlab --scenario 3     # Emergency Shutdown scenario
python -m simlab --load FILE      # Resume from saved state
python -m simlab --v1             # v1 physics only (no boron/samarium/pressurizer/alarms)
python -m simlab --test           # Run physics test harness

Feature flags: --no-boron, --no-samarium, --no-pressurizer, --no-alarms

Requirements

• Python 3.10+
• Terminal emulator with ANSI/curses support (80x32 minimum)
• windows-curses on Windows (provides the standard curses module)

Architecture

src/simlab/
  __main__.py          # Module entry: python -m simlab
  main.py              # CLI parsing and entry point
  constants.py         # Nuclear constants (Keepin 6-group, xenon, decay heat, etc.)
  config.py            # SimConfig feature toggle dataclass (v1/v2 modes)
  persistence.py       # Save/load reactor state to JSON

  models/              # Data layer
    parameters.py      #   ReactorParams dataclass (50+ fields)
    reactor_state.py   #   ReactorState (17-element ODE state vector)

  physics/             # Pure-function physics modules
    neutronics.py      #   Point kinetics (dn/dt, delayed neutron precursors)
    reactivity.py      #   Reactivity summation (rods + feedback + poisons)
    control_rods.py    #   Rod worth curves, SCRAM logic
    thermal.py         #   3-node thermal-hydraulics (fuel, hot leg, cold leg)
    steam_generator.py #   Primary-to-secondary heat transfer
    xenon.py           #   I-135 / Xe-135 dynamics with magic time scaler
    samarium.py        #   Pm-149 / Sm-149 fission product dynamics
    pressurizer.py     #   Pressurizer pressure and level
    decay_heat.py      #   3-group ANS-standard decay heat
    instruments.py     #   Neutron detector range readings

  engine/              # ODE solver and simulation loop
    integrator.py      #   RK4 single-step solver
    simulation.py      #   Coupled ODE system, Simulator class

  terminal/            # Curses terminal interface
    app.py             #   Main loop (~10 FPS), mode dispatch
    display.py         #   Screen layout manager (8 regions)
    gauges.py          #   ASCII bar gauge drawing
    input_handler.py   #   Keyboard mapping and command dispatch
    event_log.py       #   Circular buffer event log

  monitoring/          # Alarm and annunciator system
    alarms.py          #   Hysteresis-based alarm evaluation

  automation/          # Automated operating procedures
    manager.py         #   AutomationManager with mutual exclusion
    go_critical.py     #   Go-critical state machine
    power_ascension.py #   Power ascension ramp
    load_follow.py     #   Load-following tracker

  scenarios/           # Training missions and scoring
    base.py            #   ScenarioDefinition base class
    scoring.py         #   ScenarioScorer, ScoreReport
    startup_to_power.py
    xenon_transient.py
    emergency_shutdown.py

For detailed architecture documentation, see docs/developer/01-architecture.md.