Introduces raw/<kind>/<gen>/<detector>/shard-NNN.root and
processed/<kind>/<gen>/<schema>/<detector>/shard-NNN.parquet as the dataset
convention, plus scripts to operate on it: migrate_geant_steps.py for the
one-time move into this layout, bump_dataset_version.py to cut new
gen/schema versions with a logged reason, steps_to_parquet_parallel.py to
convert ROOT shards to parquet in parallel and place them correctly, and
create_root_files.py to generate new ROOT shards via a minicalosim
executable. The loader gains .manifest file support so pools/ (train/dev/
holdout shard lists) can be passed straight to `giant train`.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replaces the independent log_delta_e/log_edep targets with 2 additive-log-ratio
coordinates over the deposit/secondary/post-energy simplex (fractions of pre_E
summing to 1), so edep + e_sec + post_E == pre_E holds by construction after
decoding (softmax) rather than being learned approximately. Requires e_sec
(secondary energy) as a new conditioning input and a steps_to_parquet.py pass
to derive it from child track first-step energies.
One-off script (like export_validation_plots.py / export_event_observables.py)
that writes a 3x3 marginals grid, post_dir/travel_dir norm histograms, and
vector-PDF copies of the KL-bars/photon-edep/event-level plots directly into
the thesis-presentations repo's images/ folder.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Move ipykernel into the analysis extra instead of a separate
dependency group, since it's needed wherever analysis plotting runs.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
One-off script mirroring export_validation_plots.py, used to export the
new event-level and pdg-contribution-share plots into the knowledge-base
attachments folder.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
pdg_contribution_table_pl sums real/generated total deposited energy and
total step_length per pdg species over the whole file (pure lazy polars
group_by, no post_pos reconstruction needed for these scalars). Adds
plot_pdg_energy_share/plot_pdg_length_share, each rendering two pies
(real vs generated) so the per-species breakdown can be compared directly,
plus a matching notebook section.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
sum(step_length) per event_id, alongside the existing total deposited
energy, since path length and energy deposit aren't interchangeable once
tracks scatter. Adds plot_total_length and a matching notebook cell.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds section headers and explanatory comments throughout the existing
tiers, plus new cells running compute_event_observables_pl and the four
event-level shower plots. Notebook outputs reflect the user's own re-run.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Aggregates giant predict --coord local output per event_id into total
deposited energy, longitudinal/transverse shower profiles, and shower-max
depth, reconstructed into world-frame physical units (mm, MeV). Streams the
file in two polars passes rather than building a SampleCollection, since
per-event sums would be corrupted by row subsampling on these large files.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds plot_kl_bars/plot_kl_bars_pl (numpy/polars variants) for ranking which
target dimension or pdg/material stratum drives KL regressions, with the
same kl*n group capping as plot_marginals. Switches existing histogram
plots to step-type/log-scale. Adds sample_frac to load_predicted_local for
subsampling large predict parquets.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Inference batches were capped at the source parquet's row-group size
(e.g. 122,880 rows) because the old loop only sliced within a single
chunk read from disk. --batch-size (including auto) had no effect once
it exceeded that, leaving most estimated GPU memory unused. Accumulate
rows across row groups and files into a buffer and slice exactly
batch-size pieces off it, so inference always uses the requested batch
size regardless of how the file happens to be chunked.
Checkpoints have a fixed PDG embedding vocab sized at train time, so a
code unseen during training has no embedding index. Drop those rows
and report a per-code skip count instead of raising a KeyError.
Inference has no backward graph or optimizer state, so it has a much
lower per-sample memory footprint than training. estimate_batch_size
now takes a training flag selecting between two calibration points;
predict uses the inference one (hidden_dim=1024, n_blocks=8,
batch_size=65536 measured at ~2037 MiB).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Estimates batch size from free GPU memory using the checkpoint's
hidden_dim/n_blocks, same as the train command.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Calibrated against a measured reference point (hidden_dim=512,
n_blocks=6, batch_size=131072 -> ~8 GiB VRAM), assuming activation
memory scales linearly with batch_size * hidden_dim * n_blocks.
CUDA-only for now since it relies on torch.cuda.mem_get_info.
The Typer-based giant/cli.py train command now has full feature
parity (dropout, warmup-epochs, validate-steps, shorthand flags),
making the standalone argparse script redundant.
Replaces CosineAnnealingLR with a LambdaLR that linearly ramps the LR
from lr/warmup_epochs to lr over the first warmup_epochs steps, then
applies cosine decay for the remainder. Default warmup_epochs=5;
overridable via --warmup-epochs CLI flag.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
validate_marginals and collect_samples could already vary flow ODE
steps for inference (giant predict --steps), but training-time
marginal validation and DDIM evaluation were stuck at hardcoded
defaults. Add a validate_steps config/CLI option and forward steps to
sample_ddim consistently.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Output space is 9D (post_dir + travel_dir), not 6D; documents the
giant CLI, analysis/validate modules, ROOT-to-parquet conversion
script, cpu/cuda install extras, and the ruff/ty dev tooling.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
ruff removed unused imports across analysis.py and several test files.
ty caught a wrong dict[int, int] annotation on StreamingStepsDataset's
mat_map (materials are strings) and a real bug in steps_to_parquet.py
where --compression none passed None to polars' write_parquet, which
only accepts the literal "uncompressed". Also narrows a few
Optional-typed attributes (ddpm_schedule, Normalizer.mean/std) with
asserts and aligns __getitem__'s parameter name with torch's Dataset
base class.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Pins torch to 2.3.x via mutually-exclusive cpu/cuda uv extras (newer
torch requires newer NVIDIA drivers), and adds upper bounds to the
other dependencies based on current PyPI releases.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
load_predicted_local now reads predict parquet via a lazy polars scan with
column projection pushed into the reader, instead of materializing the
whole file as a pandas DataFrame. Also adds marginal_table_pl and
constraint_report_pl, polars-native duplicates that read straight from a
predict parquet path/LazyFrame and stay lazy per (group, dim) pair, so
peak memory is one column slice rather than the whole SampleCollection.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Provides stratified marginal comparisons, joint-structure checks (correlation
matrices, physically-coupled pairwise plots, direction alignment), and
physical-constraint validation (unit-norm directions, non-negative raw
targets) for a trained model's generated samples, building on the aggregate
marginal/KL check already in giant.validate.
Supports two entry points: live sampling against a checkpoint + val data
(load_model_bundle/collect_samples), or loading a precomputed
`giant predict --coord local` parquet directly (load_predicted_local) without
needing the checkpoint at all. Predict output is now tagged with parquet
schema metadata so the loader can verify a file's format and reject
coord=global or untagged files with a clear error instead of guessing from
column names.
Also extends the config git-hash mismatch warning (added for --config
loading) to checkpoint loading: both `giant predict` and
analysis.load_model_bundle now look for a config.toml next to the checkpoint
and warn (without failing) if it was generated from a different git commit.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Wire a dropout hyperparameter (default 0.1) through the config, model,
training pipeline, and CLI. Persisted in saved model_config so checkpoints
reconstruct the architecture correctly.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
A Ctrl-C or job-scheduler kill signal during training used to crash with a
raw KeyboardInterrupt mid-batch, abandoning whatever checkpoint state was
in flight. Now a signal sets a flag instead: the loop discards an
in-progress epoch's partial work (since lr_sched hasn't stepped and there's
no validation pass yet for it), but lets an epoch that's already past its
training loop finish normally — checkpoint, metrics row, and all — before
stopping. A second signal force-kills immediately for an unresponsive run.
Verified against a backgrounded run: SIGINT mid-training stopped cleanly
with a consistent last.pt/metrics.csv, and --resume picked up exactly at
the next epoch.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
validate_marginals now estimates a per-dimension KL(real || generated) via
a shared histogram, alongside the existing mean/std comparison, so
distribution-shape drift shows up even when the first two moments match.
Wire it into giant/train.py: every validate_every epochs (default 10, 0
disables), the training loop runs validate_marginals against val_loader and
prints the table. validate_every flows through DEFAULT_CONFIG/config.toml
and is exposed as --validate-every on both giant train and scripts/train.py.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
cli.py and scripts/train.py duplicated ~140 lines of training setup and had
drifted (scripts/train.py forgot to save model_config, breaking predict on
those checkpoints). Extract shared logic into giant/constants.py (X_DIM,
target names), giant/config.py (device/git/TOML/seeding helpers, run
metadata), and giant/pipeline.py (the actual training-job orchestration),
so both entry points become thin CLI wrappers around the same code path.
Also adds --seed/--resume support (checkpoints now carry optimizer/scheduler
state, epoch, and best_val_loss), a richer [meta] section in the saved
config.toml (git hash, seed, versions, timestamp, invocation, dataset
stats), and a metrics.csv (train/val loss, lr, epoch time) written every
epoch and append-safe across resumes.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Outputs the model's 9D prediction (denormalised only — still local
frame, log-scaled scalars) alongside the matching ground-truth target
for the same input rows, so they're directly comparable in the space
the loss is actually computed in. Also fixes mat_map keys being cast
with int() instead of str() when loading a checkpoint in predict.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
step_length already encodes |post_pos - pre_pos| by definition, so a raw
post_pos target would duplicate that magnitude and could drift inconsistent
with step_length during sampling. Instead add travel_dir, a unit vector
(local frame) giving only the direction of pre_pos->post_pos; post_pos is
reconstructed at inference as pre_pos + step_length * travel_dir, keeping
the two self-consistent. Target grows from 6D to 9D.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The dataset yielded one row at a time, forcing DataLoader's default
collate to Python-loop over every row to assemble each batch. That
loop scales with batch size and was pinning a CPU core at 100% while
the GPU sat idle. Now the dataset yields whole batches via vectorized
numpy slicing, used with DataLoader(batch_size=None).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
material is a string literal (e.g. "G4_PbWO4"), not an integer. Store as
object array and key mat_map on str throughout loader and transforms.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- iter_cond_chunks: column-projected row-group streaming; post-step
variables are never read from disk during inference
- build_cond_features: assembles conditioning arrays without any target
or post-step fields
- inv_local_frame_rotation: Rodrigues R^T (negative angle) to rotate
predicted post_dir back from local frame to world frame
- giant predict: loads checkpoint, streams input, runs flow matching
sampler, inverse-normalises and inverse-rotates outputs, writes
predictions incrementally as parquet via PyArrow ParquetWriter
- train now saves model_config in checkpoint so predict can reconstruct
the architecture without extra CLI flags
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Streaming pipeline: row-group-level parquet reading (PyArrow) so
large files never fully land in RAM; Welford online algorithm for
normalizer fitting; StreamingStepsDataset with shuffle buffer and
multi-worker file striping; event-ID scan and vocab scan via cheap
single-column reads
- giant/cli.py: typer-based CLI with `giant train` subcommand, mirroring
scripts/train.py; --shuffle-buffer flag for RAM control
- pyproject.toml: add typer>=0.12 dependency and giant entry point
- train.py: replace len(loader.dataset) with local counters (compatible
with IterableDataset which has no __len__)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
lars