cebf8c167a
Folds three previously-separate pieces into one preliminary-example repo for the HAHACS thesis: - thesis/ (submodule) → gitea Thesis.git — the PhD proposal - fret-pipeline/ — FRET requirements to AIGER controller (was ~/Documents/fret_processing/; prior single-commit history abandoned per user decision) - plant-model/ — 10-state PKE + lumped T/H PWR model (was ~/Documents/PKE_Playground/; never version-controlled before) - presentations/2026DICE/ (submodule) → gitea 2026DICE.git - reachability/, hardware/ — empty placeholders for Thrust 3 and HIL - docs/architecture.md — how the discrete and continuous layers compose - claude_memory/ — session notes and scratch knowledge pattern Plant model refactored to thesis naming (x, plant, u, ref); pke_th_rhs now takes u as an explicit arg instead of reading rho_ext from the params struct. First two controllers built to the contract u = ctrl_<mode>(t, x, plant, ref): ctrl_null (baseline) and ctrl_operation (stabilizing, proportional on T_avg). Validated under a 100% -> 80% Q_sg step: ctrl_operation reduces steady-state T_avg drift ~47% vs. the unforced plant. Root CLAUDE.md emphasizes that CLAUDE.md files are living documents and that any knowledge not captured before a session ends is lost forever; claude_memory/ holds the session-level notes that haven't stabilized enough to graduate into a CLAUDE.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
89 lines
4.1 KiB
Markdown
89 lines
4.1 KiB
Markdown
# 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)`
|