# README — Prostate IMRT Plan Reproduction

## Goal
Reproduce a fixed-field 7-beam coplanar 6 MV prostate IMRT plan from the
provided DICOM-RT bundle. This is a research replanning benchmark, NOT
treatment authorization.

## Six phases
1. Structure QA — load the RTSTRUCT in 3D Slicer (optional authoring tool)
   or directly in Python. Three defects are planted. Fix them per
   repair_recipes.md. Hint: the "PTV_placeholder" ROI is actually a CTV.
2. Import into matRad — use the shipped pln_template.mat and
   machine/benchmark_6MV.mat.
3. Optimize — fluence optimization (IPOPT) + Engel sequencing. DAO is
   optional. Expect weight tuning to satisfy institutional_constraints.md.
4. Dose calc — matRad pencil-beam (SVDPB) at 3 mm.
5. Export — DICOM RTPLAN, RTDOSE, RTSTRUCT with consistent FrameOfReference
   UID across CT/RTSTRUCT/RTDOSE/RTPLAN.
6. Independent QA — recompute DVH in Python via pydicom + pymedphys;
   render axial/sagittal/coronal isodose PNGs; produce report.md +
   plan_metrics.json + beam_summary.csv.

## Required outputs in submission/
- RTPLAN.dcm, RTDOSE.dcm, RTSTRUCT_corrected.dcm
- replay_state.mat (numeric-only matRad state — save w, dij.physicalDose{1},
  dij.doseGrid.dimensions, and pln.numOfFractions as -v7 .mat)
- dvh_metrics.csv, plan_metrics.json, beam_summary.csv
- figures/{axial,sagittal,coronal}.png (>=800x800)
- report.md, decisions.md (<=500 words)

## Environment (pinned)
- GNU Octave 6.4.0 (conda-forge) — matRad ships a pre-built IPOPT MEX that
  works natively with this version. No compile needed.
- matRad public GitHub commit c014dc82d620bace0836eb8cc420fe33c19cdb87
- Python 3.10 with pydicom 3.0.1, pymedphys 0.41.0, numba 0.65.0

## Expected effort
2-4 senior medical physicist days.

## What's in the box (agent_input.zip)
- dicom/CT/*.dcm — 90 anonymized axial CT slices (synthesized, no PHI)
- dicom/RTSTRUCT.dcm — corrupted RTSTRUCT with 3 planted defects
- prescription.json, beam_geometry.json
- institutional_constraints.md, repair_recipes.md
- machine/benchmark_6MV.mat — frozen benchmark 6 MV beam model (+SHA256)
- beam_model_notes.md — provenance and usage notes for the benchmark beam model
- pln_template.mat — compact MAT file storing only the fixed non-objective planning knobs
- submission_template/ — blank output stubs for report, metrics, and decisions files
- manifest.json — SHA256 for every shipped file
- README_AGENT.md

## Bundle note
`agent_input.zip` is intentionally small when compressed because the CT is a
low-resolution synthesized phantom (183x183 matrix, 90 slices) and the MAT
files compress aggressively. The uncompressed archive contains 104 files and
about 9.3 MB of data.
