ANASEN_analysis/CLAUDE.md

ANASEN Analysis — working notes for Claude

Agent behavior

• Architecture & Remotes:
  • upstream points to the canonical public repo (read-only reference).
  • origin points to your private sandbox repo (read/write scratchpad).
  • NEVER attempt to push to upstream. All upstream synchronization is strictly one-way (git fetch upstream -> merge).
• Upstream Sync Routine:
  • Before applying requested features or edits, sync with upstream if requested.
  • Never pull into a dirty working tree. Use: git stash -> git fetch upstream -> git merge upstream/devel_vignesh -> git stash pop.
  • If a merge conflict occurs in analysis macros (TrackRecon.C, MakeVertex.C, kinematics scripts, or calibration tables), STOP immediately. Do not attempt to guess physics logic; flag the exact conflict lines and await instruction.
• Commits & Pushes to origin:
  • Commit only when a coherent, discrete change is finished or when explicitly asked. Write concise, conventional commit messages.
  • Push only to origin (git push origin <branch>). Push after completing a requested unit of work so the sandbox stays backed up.
• ALWAYS output a brief, step-by-step plan before modifying files or running commands.
• Targeted edits only. Never regenerate a whole file to make a local change.
• Never read MakeVertex.C
• Never read TrackRecon.C end to end (~4,250 lines; ~63k tokens each, and it stays in the prefix for the rest of the session). Grep for the symbol, then Read with offset/limit around the hit. If a question genuinely needs the whole file, say so first. Do not explore the codebase open-endedly.
• Do not spawn subagents for work that can be done inline — each starts cold and re-derives context already loaded. Worth it only for wide parallel searches where the conclusion is all that's needed.
• You cannot verify your own work here. No test suite, no CI, no data in the repo; validation is visual, via ROOT TBrowser, on a machine that has the data. Say explicitly when a change is unverified — never report a physics change as working because it compiled. The dangerous bugs are silent: a flipped sign in a kinematics term, an inverted spline direction, a wrong argument order, an off-by-one in a wire mask. None of them throw. The run completes, the plot renders, and the spectrum is wrong.
• Review once per coherent change, not per edit. Scale depth to blast radius: scratch macros, shell, and docs are shallow; TrackRecon.C, MakeVertex.C, Armory/, or any calibration fit is deep and should tolerate uncertain findings — silent failure is what's being hunted. Run /security-review only for file I/O or shell interpolation in the run_*.sh drivers; it is not a physics tool.

Build & execution

• ROOT macros (.C) compile via ACLiC inside ROOT. Do not link into binaries.
• Standalone binaries (EventBuilder, Mapper): cd Armory && make
• Pre-compile for parallel runs: root -q -l -b -e '.L TrackRecon.C++O'
• Batch runs: ./run_17F.sh, ./run_27Al.sh, ./run_tr.sh
• run_tr.sh gates its stages with if [[ 1 -eq 0 ]] / if [[ 1 -eq 1 ]]. Flip the literal to enable a block.
• Data is NOT in the repo. Mapped ROOT files live at ../ANASEN_analysis/data/${DATASET}_Data/${PREFIX}${run}_mapped.root.

Runtime configuration

All config is getenv-driven; the run scripts export it. Defaults are in TrackRecon.C::Begin().

Physics / results-affecting: DATASET reactiondata CO2percent pressure_in_torr CATHODE_GAIN PC_ENERGY_CALIBRATION source_vertex CUTLIST DITHER_SIGMA RNG_SEED BEAM_AXIS_X BEAM_AXIS_Y timecut_low timecut_high DISABLE_BAD_ANODE_WIRES A1C1_LOWBAND_RFACTOR A1C1_CFRAC_SPLIT A1C1_ANODEE_COFF A1C1_ANODEE_REF A1C1_MISSING_FMAX A1C1_Z_SCALE_QQQ A1C1_Z_SCALE_SX3 A1C1_Z_OFF_QQQ A1C1_Z_OFF_SX3

Plumbing: OUT_DIR RUN_NUMBER FLUSH_BARRIER MAX_RSS_MB MEMCHECK_STRIDE

DEDX_SCALE is read by eloss_calculations/Eloss.py, NOT by TrackRecon.C. It multiplies catima.dedx when the lookup tables are generated. Changing it invalidates every .dat table — re-run Eloss.py (the run scripts do this automatically before processing). Tables are keyed eloss_calculations/<species>_lookup_<E>MeV_<P>torr_<CO2>pc.dat (e.g. alpha_lookup_50MeV_250torr_3pc.dat).

Footguns

• HistPlotter keys oMap by histogram NAME only. The folder argument does not namespace. Two Fill calls with the same name in different folders merge silently — no warning, no error, wrong plot. Always make names unique unless required.
• Si–PC coincidence sits at negative dt. The real band is roughly -450 < t_si - t_pc < -200, not near zero. Do not "correct" a timing gate toward zero.
• RNG: one shared anasenRandom (TRandom3, seed 4357, RNG_SEED to override) — do not introduce fresh TRandom3(0) instances; it breaks reproducibility.
• Pass By Reference in Event Loops: Always iterate via const auto& over cluster/hit vectors to prevent expensive struct copies in multi-million event runs.

Invariants to check on any physics change

Units (MeV vs keV, cm vs mm); sign conventions on z and beam direction; eloss spline domain and extrapolation; energy conservation in the kinematics; dead-wire / neighbour masking; RNG seeding. When reviewing, include the .dat and run_*.sh parameter deltas — the most consequential recent changes have been constants, not code.

Docs

README.md has the pipeline documentation and full file references.