Simulate
Geant4 ingest workflow
Vikshep does not replace Geant4 — it ingests its output. Pass a CSV export from any Geant4 run (or ROOT TTree, or HDF5 Well schema) and Vikshep converts it to a content-addressed grid ready for the scattering transform. No rewriting of your Geant4 macro or detector description is needed.
What ingest does
The ingest pipeline reads the Geant4 output, detects or applies the column schema, rasterizes each event into a shared-memory grid (one grid per event, per layer), computes per-layer and per-event aggregates, and writes a manifest.json with content-addressed output OIDs and provenance. No raw tensors are written to disk; only the aggregates and the OIDs are stored in the manifest.
The manifest is the input to the scattering transform and to all downstream recipes. It is the single source of truth for what data was ingested, when, and from what source.
CLI — Geant4 CSV
The quickest path: a CSV export from Geant4, one command.
vikshep-ingest g4 examples/g4_quickstart/sample.csv --schema komal_v1
Writes manifest.json and provenance.json to the current directory. The manifest lists every output OID and the per-layer aggregate values.
Non-standard column names
If your Geant4 CSV uses different column names, use --schema generic with a --column-map:
vikshep-ingest g4 data/sim_output.csv \ --schema generic \ --column-map "event_id=evtId,layer=layerNo,energy_dep=eDep,hit_x=x,hit_y=y,hit_z=z"
Studio — Ingest screen
In Studio, the Ingest screen accepts drag-drop or a file dialog. The workflow is:
- 01Schema detection — Vikshep detects the column profile or prompts for a manual column map.
- 02Column mapping UI — an editable key-value table for non-komal_v1 files.
- 03Aggregates preview — a table of per-layer statistics computed immediately from the manifest.
- 04Per-layer energy and multiplicity histograms — rendered from manifest aggregates; no raw tensors cross the UI layer.
- 05Pad policy editor — set circular or zero-pad boundary conditions per axis.
- 06Run ingest — submits via the Executor, shows progress, lands on Results.
Supported schemas
| Schema | Format | Columns / fields | Notes |
|---|---|---|---|
| komal_v1 | Geant4 CSV | event_id, layer, hit_x, hit_y, hit_z, energy_dep, particle_id | Default schema for the Edinburgh pilot analysis (ATLAS boosted di-boson). |
| generic | Geant4 CSV | Any — specify column mapping with --column-map | Use --column-map key=col,... to map schema fields to arbitrary column names. |
| well_hdf5 | HDF5 (Well schema) | t0/t1/t2 fields; periodic or wall boundary conditions | Well-scale ingest (over 1 TB) is a hosted-plane feature (Lab/Enterprise). |
| root_uproot | ROOT TTree | ATLAS analysis framework output; via uproot | Requires uproot extra: pip install -e 'backend/ingest[uproot]' |
Provenance output
Every ingest run writes a provenance.json alongside the manifest. The provenance records:
- +schema_version, engine_version, engine_build_hash
- +executor (local or cloud), platform
- +op (e.g. ingest_g4), config_digest (sha256 of sorted config JSON)
- +seed (if set), input_oids (content hashes of input files), output_oids
- +wall_clock_ms, created_at (ISO 8601 UTC)
- +manifest_hash (self-fingerprint of the manifest, excluding this field)
The provenance manifest is the basis of the Determinism Certificate. See Verify for how to issue and verify certificates.
Next: scattering features and recipes
After ingest, pass the manifest to the scattering transform (requires the open core from vikshep-compute) and then to a recipe:
# Calibrate detector response vikshep-recipe calibrate --features manifest.json --target layer1_e_mean # Tag with DisCo decorrelation vikshep-recipe tag --features manifest.json \ --label is_signal --protect mass --lambda 1.0
The scattering extra must be installed (see Install → Path 2) for the scattering transform. The calibrate and tag recipes fall back to per-event aggregates if the scattering core is not present; the report states which path ran.