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>
110 lines
5.7 KiB
Markdown
110 lines
5.7 KiB
Markdown
# CLAUDE.md
|
|
|
|
Guidance for Claude Code (and any AI agent) working in this repository.
|
|
|
|
## Living documentation — update these files
|
|
|
|
**`CLAUDE.md` files are living.** This one and the ones in subdirectories.
|
|
When you learn something new about the system that a future agent would
|
|
benefit from, update the appropriate `CLAUDE.md` before the session ends.
|
|
**Context that exits a session uncaptured is lost forever** — treat this as
|
|
the single most important rule in this repo.
|
|
|
|
**Where to write:**
|
|
- Stable, authoritative knowledge (architecture, conventions, interfaces,
|
|
design decisions) → the relevant `CLAUDE.md`. Root for cross-cutting;
|
|
subdirectory for layer-specific.
|
|
- Session-level findings, in-progress investigations, paths that didn't pan
|
|
out → `claude_memory/YYYY-MM-DD-topic.md`. See `claude_memory/README.md`
|
|
for the pattern.
|
|
|
|
**When to write:**
|
|
- After a non-trivial debugging session (what broke, root cause, how you knew).
|
|
- After an architectural or structural decision (what we chose, what we
|
|
rejected, why).
|
|
- After discovering a non-obvious fact (subtle constraint, undocumented tool
|
|
behavior, counterintuitive data format).
|
|
- Before ending a session where you explored paths that didn't pan out — so
|
|
the next agent doesn't waste effort redoing them.
|
|
|
|
Over time, session notes that stabilize get distilled up into the relevant
|
|
`CLAUDE.md`; the rest get archived or deleted. This is a discipline, not
|
|
automation — do the graduation explicitly when knowledge becomes authoritative.
|
|
|
|
## What this is
|
|
|
|
The preliminary example for the HAHACS thesis — a PWR startup controller
|
|
demonstrating the full pipeline from written operating procedures to verified
|
|
hybrid controller. This repo composes three layers of the same story:
|
|
|
|
| Layer | Location | Role | Thesis mapping |
|
|
|---|---|---|---|
|
|
| Story | `thesis/` (submodule) | The PhD proposal: math, prose, claims | Motivates and defines the methodology |
|
|
| Discrete | `fret-pipeline/` | FRET requirements → LTL → ltlsynt → AIGER circuit → state machine | Implements Thrust 1 + 2 |
|
|
| Continuous | `plant-model/` | 10-state PKE + thermal-hydraulics PWR model (MATLAB/Octave) | Plant for Thrust 3 (reachability / barrier certs) |
|
|
| Verification | `reachability/` | Continuous-mode verification artifacts | Thrust 3 output — currently empty |
|
|
| Hardware | `hardware/` | Ovation HIL artifacts | Integration milestone — currently empty |
|
|
| Deliverables | `presentations/` | Conference papers and talks (submodules) | Dissemination |
|
|
|
|
Running example: the `PWR_HYBRID_3` controller. The discrete automaton it
|
|
synthesizes is literally the state machine drawn in `thesis/3-research-approach/approach.tex`
|
|
Figure 1 (Cold Shutdown → Heatup → Power Operation, with SCRAM).
|
|
|
|
## How changes flow
|
|
|
|
1. **Requirement change.** Edit the FRET export (`fret-pipeline/pwr_hybrid_3.json`)
|
|
→ run `fret-pipeline/scripts/fret_to_synth.py` → re-synthesize via
|
|
`synthesize.sh` → re-trace via `trace_aiger.py`. New `.svg` / `.dot` /
|
|
`.png` land in `fret-pipeline/diagrams/`. Copy the figure you want to cite
|
|
into `docs/figures/` so the thesis can pick it up.
|
|
2. **Plant change.** Edit `plant-model/pke_params.m` or dynamics in
|
|
`pke_th_rhs.m` → re-run `main.m` to verify behavior. Steady-state values
|
|
feed the `T_avg`, `P_crit` thresholds in the FRET requirements — if you
|
|
change them here, check the requirement predicates match.
|
|
3. **Verification work.** Continuous-mode verification (reachability, barrier
|
|
certificates) reads the guards from `fret-pipeline/specs/synthesis_config_v3.json`
|
|
and the dynamics from `plant-model/pke_th_rhs.m`. Results go in `reachability/`.
|
|
4. **Thesis edit.** `cd thesis && <edit> && git commit && git push origin main`,
|
|
then from the umbrella root: `git add thesis && git commit` to bump the
|
|
submodule pointer.
|
|
|
|
## Where to look for what
|
|
|
|
- Reactor physics, steady-state, ODE dynamics → `plant-model/`
|
|
- Controller synthesis, requirements, state machines → `fret-pipeline/`
|
|
- Research narrative, math, claims, citations → `thesis/`
|
|
- Shared figures (for the thesis or talks) → `docs/figures/`
|
|
- How the layers compose → `docs/architecture.md`
|
|
|
|
## Submodule rituals
|
|
|
|
- Fresh clone: `git clone <url> && git submodule update --init --recursive`
|
|
(or `git clone --recurse-submodules <url>`). Without this, `thesis/` and
|
|
`presentations/2026DICE/` are empty directories.
|
|
- Editing the thesis: `cd thesis && git checkout main` first — submodules
|
|
default to detached HEAD. Then edit, commit, push inside the submodule,
|
|
then `cd ..` and commit the new submodule pointer in the umbrella.
|
|
- Pulling upstream thesis changes: `cd thesis && git pull origin main`, then
|
|
commit the new pointer in the umbrella.
|
|
|
|
## Conventions
|
|
|
|
- FRET variables: `control_<group> = q_<value>` for modes; everything else is
|
|
an environment input. See `fret-pipeline/README.md` for the full naming rule.
|
|
- Plant model units: internal SI (W, kg, °C); printed/plotted in °F.
|
|
- Continuous state vector: `y = [n; C1..C6; T_f; T_c; T_cold]`. Guards in
|
|
FRET should reference the algebraic outputs (`T_hot`, `T_avg`) or direct
|
|
states, not derived quantities.
|
|
- `Q_sg(t)` is the bounded disturbance — never treat `T_cold` as an input.
|
|
|
|
## What's deliberately missing (so you don't go looking)
|
|
|
|
- LTL-to-Stateflow translator — there's a known pain point in the thesis
|
|
workflow where AIGER circuits still need to become Stateflow. Not yet
|
|
automated. Current path: generate AIGER → eyeball the state machine
|
|
diagram → hand-translate to Stateflow. Roadmapped.
|
|
- Hardware bring-up (Ovation DCS) — scheduled for the integration thrust.
|
|
`hardware/` is a placeholder.
|
|
- Continuous-mode verification — `reachability/` is empty. Choice of tool
|
|
(CORA / Flow* / SpaceEx / JuliaReach) still pending.
|