# 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)`