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

PKE Playground — LLM Context

This document provides context for an LLM working on this codebase. It explains the model, design decisions, and where the project is headed.

What This Is

A point kinetic equation (PKE) model coupled with lumped-parameter thermal-hydraulics, implemented in MATLAB/Octave. The model represents a simplified PWR (pressurized water reactor) core and primary loop.

Why It Exists

This is a workable plant model being developed for hybrid systems reachability analysis. The end goal is to use barrier certificate methods to prove that under bounded variations in steam generator (SG) heat removal, the reactor stays within a defined safe operating region (bounded temperatures, power levels, etc.).

The model needs to be:

• Physically motivated (not just a toy system)
• Clean and state-space oriented (explicit state vector, clear inputs/outputs)
• Structured so that Q_sg(t) is a bounded disturbance input for reachability tools

The Model

State Vector (10 states)

y = [n; C1; C2; C3; C4; C5; C6; T_f; T_c; T_cold]

• n — normalized neutron population (1.0 = nominal)
• C1..C6 — six delayed neutron precursor group concentrations (Keepin U-235 thermal fission data)
• T_f — lumped fuel temperature [C]
• T_c — average core coolant temperature [C]
• T_cold — cold leg / SG outlet coolant temperature [C]

Algebraic Outputs

• T_hot = 2*T_c - T_cold (linear coolant temperature profile through the core)
• T_avg = T_c

Equations

Neutronics:

dn/dt   = (rho - beta) / Lambda * n + sum(lambda_i * C_i)
dC_i/dt = beta_i / Lambda * n - lambda_i * C_i

Thermal-hydraulics (three lumped nodes):

M_f*c_f   * dT_f/dt    = P0*n - hA*(T_f - T_c)                        [fuel]
M_c*c_c   * dT_c/dt    = hA*(T_f - T_c) - 2*W*c_c*(T_c - T_cold)     [core coolant]
M_sg*c_c  * dT_cold/dt = W*c_c*(T_hot - T_cold) - Q_sg(t)             [SG/cold leg]

Reactivity feedback:

rho = rho_ext(t) + alpha_f*(T_f - T_f0) + alpha_c*(T_c - T_c0)

Why Q_sg Is the Input (Not T_cold)

In a real PWR, the steam generator removes heat from the primary loop based on secondary-side demand. The cold leg temperature is a result of that heat removal, not a boundary condition you get to set. Treating Q_sg(t) as the external input and letting T_cold be a dynamic state is physically correct and maps naturally to the reachability problem: "given that SG demand is somewhere in [Q_min, Q_max], what states can the reactor reach?"

Why T_hot = 2*T_c - T_cold

This comes from the linear coolant temperature profile assumption through the core. If coolant enters at T_cold and exits at T_hot, and the average is T_c, then T_c = (T_hot + T_cold) / 2, so T_hot = 2*T_c - T_cold. This avoids needing a separate hot leg state while still tracking both temperatures.

Why ode15s

The PKE system is stiff. The prompt neutron generation time Lambda (~10^-4 s) is orders of magnitude smaller than the thermal time constants (~10-100 s) and precursor decay constants (~0.01-3 s^-1). An explicit solver would need extremely small timesteps; ode15s handles this naturally.

File Structure

Each file has one purpose:

File	Purpose
pke_solver.m	Main driver script — scenario config, solve, print
pke_params.m	All plant parameters and steady-state derivation
pke_th_rhs.m	ODE right-hand side f(t, y) — this is the dynamics
pke_initial_conditions.m	Analytic steady-state initial condition
load_profile.m	SG heat demand time series (swappable)
plot_pke_results.m	4-panel results plotting

For Future Reachability Work

• pke_th_rhs.m is your dx/dt = f(x, w) where w = Q_sg
• Linearize around the steady state from pke_params.m to get A, B matrices
• The safe region will be a polytope or sublevel set on [n, T_f, T_hot, T_cold] (or a subset)
• Q_sg is the bounded disturbance: Q_sg in [Q_min, Q_max] around P0
• Barrier certificate B(x) would certify that trajectories starting in the safe set stay there for all admissible Q_sg(t)