PWR-HYBRID-3/plant-model/CLAUDE.md

CLAUDE.md

Guidance for Claude Code (and any AI agent) working in this subdirectory.

See also: the parent repo's CLAUDE.md (living-documentation rule — update this file when new knowledge is created) and claude_memory/ for session notes that haven't yet earned a place here.

What this is

A 10-state point kinetic equation (PKE) model of a PWR coupled with lumped-parameter thermal-hydraulics, plus mode-specific continuous controllers. Implements the plant and the tactical layer of the HAHACS methodology — see ../thesis/3-research-approach/approach.tex sections on transitory, stabilizing, and expulsory modes.

The model is being developed for hybrid-systems reachability analysis. The end goal is barrier-certificate and reachability methods (in ../reachability/) to prove each continuous mode satisfies its obligations under bounded Q_sg(t) variations.

Naming convention (thesis-aligned)

Continuous state and control-theory notation matches the thesis:

Symbol	Meaning
t	time [s]
x	continuous state vector, [n; C1..C6; T_f; T_c; T_cold]
plant	parameter struct from pke_params() (was p — renamed to avoid collision with p_i predicates)
u	control input: external rod reactivity [dk/k]
Q_sg	bounded disturbance: SG heat removal [W], as a function handle Q_sg(t)
ref	reference/setpoint struct (e.g. ref.T_avg)

T_avg = T_c (algebraic alias); T_hot = 2*T_c - T_cold (linear coolant profile assumption).

Running

From inside MATLAB:

main     % runs the default closed-loop scenario

From a terminal (figures appear as their own windows):

matlab -nodesktop -nosplash -r "main"     # drops at >> prompt; `exit` to quit
matlab -r "main" &                        # full IDE, backgrounded
matlab -batch "main"                      # headless sanity check (no figures shown)

main.m configures the scenario (plant, Q_sg, ref, tspan), picks a controller, and calls pke_solver. Tested on MATLAB R2025b; works on any MATLAB with ode15s (R2020b or newer).

Architecture

plant-model/
  pke_params.m               plant parameters and derived steady state
  pke_initial_conditions.m   analytic equilibrium x0 from plant
  pke_th_rhs.m               dynamics:  dx/dt = f(t, x, plant, Q_sg, u)
  pke_solver.m               closed-loop driver; takes a controller fn handle
  plot_pke_results.m         4-panel results plot
  load_profile.m             canned Q_sg demand shapes
  main.m                     entry point — scenario config + run
  controllers/
    ctrl_null.m              u = 0 (baseline, no feedback)
    ctrl_operation.m         stabilizing: P on T_avg
    (future: ctrl_heatup, ctrl_scram, ctrl_shutdown)

Controller contract:

u = ctrl_<mode>(t, x, plant, ref)

Pure function. Returns scalar u (external rod reactivity in dk/k). All four signature args are required even if unused — lets the solver swap controllers by function handle without caring which one it is.

Solver contract:

[t, X, U] = pke_solver(plant, Q_sg, ctrl_fn, ref, tspan)

Builds the closed-loop RHS internally, calls ode15s, then reconstructs the control trajectory U by re-evaluating ctrl_fn at each returned time step. For event-driven or hysteretic controllers, this reconstruction may miss interior solver evaluations — revisit if / when that matters.

Key design decisions

• Q_sg is the disturbance, never an actuator. Cold leg temperature is a dynamic state resulting from SG heat removal — the reachability formulation needs Q_sg ∈ [Q_min, Q_max] as a bounded disturbance, not a control input.
• u is explicit. pke_th_rhs takes u directly instead of reading p.rho_ext(t) from the params struct. This decouples plant from controller and matches the thesis's f(x, u) formulation.
• Controller gains live in the controller file. Rough-out phase — we'll lift to a config struct once we're tuning more than one mode. The gain in ctrl_operation (Kp = 1e-4 /K) is chosen to roughly double the effective moderator coefficient, not for precision tracking.
• ode15s is required because the system is stiff: Lambda (~10⁻⁴ s) vs thermal time constants (~10–100 s).

Conventions

• One function per file, each file has a single responsibility.
• Internal model uses SI (W, kg, °C); all printed/plotted temperatures in °F.
• Reference setpoints in SI (so ref.T_avg is in °C).
• Controllers are pure functions — no persistent state. If a mode ever needs integral action, augment x rather than hiding state in globals.

For reachability work (next chapter)

• pke_th_rhs(t, x, plant, Q_sg, u) is the ẋ = f(x, u) with Q_sg as the disturbance w. For a given mode, substitute u = ctrl_<mode>(t, x, plant, ref) to get the closed-loop ẋ = f_cl(x, w).
• Linearize around x0 from pke_initial_conditions(plant) for A, B, B_w matrices when a linear reach set is enough.
• Safe regions come from the FRET spec's guards (see ../fret-pipeline/specs/synthesis_config_v3.json) — these define X_entry, X_exit, X_safe per the thesis approach.
• Do NOT try to verify the whole hybrid system at once. Pick one mode, compute its reach set, discharge the per-mode obligation. The compositionality argument in the thesis is what makes this tractable.