# Scientific-workflow teaching adapter

From the workshop workspace, with the Python 3.12 environment activated:

```bash
python -m pip install -r workshop-support/science/requirements-science.txt
python workshop-support/science/prepare_science.py SnakeMake.main work-science
cd work-science/program
snakemake --cores 2 --scheduler greedy --dry-run
snakemake --cores 2 --scheduler greedy
snakemake --cores 2 --scheduler greedy
snakemake --cores 2 --scheduler greedy --summary
cd ../..
python workshop-support/science/check_outputs.py work-science
```

The helper creates a new directory and refuses to overwrite an existing one.
It copies the original learner programs, raw HDF5 data and supplied solution
INIs. All their bytes remain unchanged. The raw dataset is not redistributed
in this support package; it comes from the separately cloned teaching repository.

The single Snakefile replaces nested workflows and success markers with actual
file dependencies. Run it from `work-science/program`. Each fit writes four
momentum files. The supplied 18 INIs contain 17 unique model/range combinations:
`input_0.ini` and `input_6.ini` both specify `1exp`, tmin 10, tmax 22. The adapter
schedules this output once. It does not invent the missing `1exp`, tmin 8,
tmax 22 configuration. The full initial DAG has 20 jobs including `all`:
17 correlator fits, one combination, one dispersion fit, and the final target.

Expected results are 68 files in `data/energy_fits`, four files in
`data/dispersion_data`, `program/energies/energies_chosen.pdf` and
`program/dispersion/dispersion_pion.pdf`. Rule logs are in `program/logs`.
`check_outputs.py` checks expected filenames, replica counts, finite numeric
values and PDF signatures. A PDF signature is not a visual-layout check.

`run_dispersion_mathtext.py` changes text rendering immediately before the
original script saves its figure, so an external LaTeX installation is not
required. Labels use Matplotlib's built-in mathtext. This does not change fitted
parameters, replica transformations, covariance, fit selection, numeric plot
arrays or the original scripts. Headless plotting and one thread for each of
the common numerical-library thread pools are set in the Snakefile.

The workflow preserves known source-analysis concerns: the code uses inverse
xi in its dispersion relation while the slides display xi; the plot-band
helper hardcodes L=16 while the supplied spectrum list uses L=32; covariance,
fit-selection and resampling conventions require separate scientific review.
The original correlator script does not save minimizer validity flags. Successful
execution and finite artifacts therefore establish an orchestration example,
not validated scientific inference. Do not alter numerical conventions during
the workflow exercises.

In the recorded run the selection chose the `d011` two-exponential fit with
tmin 10 and tmax 24: all 400 fitted energies were negative, with mean about
-0.20133. This is incompatible with the positive square-root branch used by
the dispersion model. The checker reports selected means and flags this issue;
its successful structural checks must not be read as a scientific pass.
