ψ Vikshep
DocsTalk to founders

Quickstart

Geant4 to physics answer in four commands

From a Geant4 CSV export to calibrated features and a mass-decorrelated tagger — no GPU, no account, no build step.

Prerequisites: Python 3.10+, Git. Install time (first run): ~20 s. Pipeline time on sample data: ~22 s.

Clone and install

git clone https://github.com/samvardhan03/Vikshep.git
cd Vikshep
pip install -e backend/ingest

vikshep-ingest is not yet on PyPI. Install from the repo clone only.

Step 1Ingest a Geant4 CSV

The G4 Direct Interface reads a Geant4 ntuple CSV, rasterizes each event into a 2-D (phi, theta) grid, computes 32 aggregate scalars per event, and writes a manifest. No engine binary required.

vikshep-ingest g4 examples/g4_quickstart/sample.csv --schema komal_v1

Expected output

Geant4 Direct Interface — profile: komal_v1
  CSV            : examples/g4_quickstart/sample.csv
  Events parsed  : 10
  Hits total     : 45
  Malformed rows : 0
  Grid channels  : 1  (energy)
  Aggregate scalars: 32 per event
  Grid OIDs      : 10 (28-char SHA3-256)
  Manifest written: examples/g4_quickstart/manifest.json

The komal_v1 schema expects per-hit rows: event_id, layer (1|2|3), phi (rad), theta (rad), momentum (GeV/c)[, energy (GeV)]. For other ntuple layouts use --schema generic --column-map {...}.

Step 2 (optional)Inspect the manifest

The manifest is the control-plane payload — OIDs and scalars, no raw tensors. Inspect it before running recipes.

cat examples/g4_quickstart/manifest.json | python3 -c "
import json, sys
m = json.load(sys.stdin)
print('Events:', m['n_events'])
print('Aggregates per event:', len(m['aggregate_names']))
print('Grid OIDs (first 3):', m['grid_oids'][:3])
"

Expected output

Events: 10
Aggregates per event: 32
Grid OIDs (first 3): ['...28 hex chars...', '...', '...']

Step 3Calibrate detector response

Fit a regression from aggregate features to a target scalar (e.g. energy deposited in a layer). Outputs a calibration report with R² and residual std.

vikshep-recipe calibrate \
  --features examples/g4_quickstart/manifest.json \
  --target layer1_e_mean

Expected output

  Report written: examples/g4_quickstart/calibrate_report.json
  target   : layer1_e_mean
  R^2      : 1.0000
  residual std: 0.0001
  n_events : 10

Step 4Tag with DisCo mass-decorrelation

Train a classifier and enforce zero distance correlation between its score and a protected variable (e.g. mass). The --lambda flag controls the decorrelation penalty strength. Higher = stricter decorrelation.

vikshep-recipe tag \
  --features examples/g4_quickstart/manifest.json \
  --label    layer1_n_hits \
  --protect  layer2_phi_mean \
  --lambda   1.0

Expected output

Report written: examples/g4_quickstart/tag_report.json
  lambda   : 1.0
  AUC      : 1.0000
  dCorr^2  : 0.0000  (lower = better decorrelation)
  n_events : 10

dCorr² = 0.0000 means the tagger score and the protected variable are statistically independent at this sample size — mass sculpting is suppressed.

What each command produces

CommandInputOutput
vikshep-ingest g4Geant4 CSVmanifest.json — OIDs + 32 scalars/event
vikshep-recipe calibratemanifest.jsoncalibrate_report.json — R² + residual std
vikshep-recipe tagmanifest.jsontag_report.json — AUC + dCorr²

Time to first value

Measured on Apple M-series (macOS 22.6, Python 3.11, no GPU), fresh install, sample.csv (10 events):

  • pip install -e backend/ingest~20 s (first install; cached ≈ 3 s)
  • vikshep-ingest g4~7 s
  • vikshep-recipe calibrate< 1 s
  • vikshep-recipe tag~15 s (sklearn fit)
  • End-to-end from git clone to tag_report.json< 45 s

Next steps