yall/fullset-g1-repro/README.md

0001 # FullSet G1 reproduction
0002
0003 This example reproduces Fredi's SPS H2 `FullSetG_1` calibration chain from raw
0004 TB2026 data using Yall and HTCondor.
0005
0006 It is a larger validation workflow, not the recommended first Yall/LFHCal test.
0007 For a fresh BNL setup, complete the checks in [`../SETUP.md`](../SETUP.md)
0008 first.
0009
0010 ## Inputs
0011
0012 The workflow uses pedestal run `485` and merges muon runs
0013 `484`, `486`, `487`, `488`, `489`, `490`, and `491` as
0014 `Muon_FullSetG_1`.
0015
0016 Set G uses the V1 summing-board mapping, the FullSetG bad-channel map, and the
0017 published FullSetG ToA offsets.
0018
0019 The raw inputs must be readable as:
0020
0021 ```text
0022 $LFHCAL_DATA/Run484.h2g
0023 $LFHCAL_DATA/Run485.h2g
0024 $LFHCAL_DATA/Run486.h2g
0025 $LFHCAL_DATA/Run487.h2g
0026 $LFHCAL_DATA/Run488.h2g
0027 $LFHCAL_DATA/Run489.h2g
0028 $LFHCAL_DATA/Run490.h2g
0029 $LFHCAL_DATA/Run491.h2g
0030 ```
0031
0032 The published reference calibration is:
0033
0034 ```text
0035 calibrations/TB2026/calib_SPS-H2_FullSetG_1.txt
0036 ```
0037
0038 ## Run table and dependencies
0039
0040 The Yallfile declares the eight runs once in a typed
0041 `@table runs type run:` table. One `convert-{type}-{run}` family converts every
0042 row. `merge-muon` binds `type=muon`, restricting both its patterned parent
0043 fan-in and `@input.parts` to runs `484` and `486`–`491`; pedestal run `485`
0044 cannot leak into the merge.
0045
0046 The `{type}-{run}` pedestal family uses `@each type pedestal`. That explicitly
0047 binds only `type`; the compatible `convert-{type}-{run}` parent supplies the
0048 remaining `run=485`, producing `pedestal-485`. `transfer-g1` depends on the
0049 patterned pedestal family, so changing the pedestal row makes the conversion,
0050 pedestal task, and transfer dependency follow it automatically.
0051
0052 This partial-binding syntax requires yall-run PR #33, merged as commit
0053 `1081e9dd39418262588248272618130ce0503b8a`.
0054
0055 ## Run at BNL
0056
0057 Use the normal BNL `tcsh` login/submit session:
0058
0059 ```tcsh
0060 cd "$LFHCAL_REPO/examples/yall/fullset-g1-repro"
0061 source env.tcsh
0062
0063 yall-run validate
0064 yall-run plan
0065
0066 set C = `yall-run create --campaigns-dir "$LFHCAL_WORK/campaigns"`
0067 echo "$C"
0068 yall-run start "$C"
0069 yall-run status "$C"
0070 ```
0071
0072 Repeat `yall-run status "$C"` to inspect progress.
0073
0074 Results are written under:
0075
0076 ```text
0077 $LFHCAL_WORK/fullset-g1-repro/
0078 ```
0079
0080 The final products are:
0081
0082 ```text
0083 $LFHCAL_WORK/fullset-g1-repro/final/calib_Final_Muon_FullSetG_1.root
0084 $LFHCAL_WORK/fullset-g1-repro/final/calib_Final_Muon_FullSetG_1_calib.txt
0085 ```
0086
0087
0088 ## Compare with Fredi and build PDF reports
0089
0090 After the campaign has completed, the report script can be run directly; it
0091 does not need the LFHCal example environment:
0092
0093 ```tcsh
0094 cd "$LFHCAL_REPO/examples/yall/fullset-g1-repro"
0095 python3 compare_and_report.py --work /gpfs01/star/scratch/$USER/lfhcal/fullset-g1-repro
0096 ```
0097
0098 If the standard BNL scratch output exists, `--work` may be omitted and the
0099 script will locate it automatically.  It deliberately refuses stale
0100 example-specific environment state rather than guessing.
0101
0102 The script compares the reproduced calibration tables with
0103 `calibrations/TB2026/calib_SPS-H2_FullSetG_1.txt`, reports channel-by-channel
0104 and refinement-stage differences, and writes CSV/JSON/text results under:
0105
0106 ```text
0107 $LFHCAL_WORK/fullset-g1-repro/report/comparison/
0108 ```
0109
0110 It also uses `pdfunite` to assemble the existing ROOT-generated plot PDFs.
0111 The MIP reports follow the same ordering as Fredi's combined calibration summary:
0112 FWHM, Gaussian width, Landau MPV/width, maximum, fit chi-square, per-layer MIP
0113 fits, trigger maps/SNR/suppression, and per-layer trigger primitives.
0114
0115 Outputs are written under:
0116
0117 ```text
0118 $LFHCAL_WORK/fullset-g1-repro/report/pdf/
0119 ```
0120
0121 including reports for the initial fit and each refinement stage, a
0122 `SummaryMipCalibration_Final_FullSetG_1.pdf` alias for Imp5R, simple pedestal
0123 and transfer plot books, and an all-in-one `CalibrationPlotBook_FullSetG_1.pdf`.