Skip to content

Commit 06013d5

Browse files
committed
docs: add mkdocs skeleton + entry pages + the two footgun pages
mkdocs-material config (build via pip install -e '.[docs]' && mkdocs serve). Pages: index (overview + two execution paths), install (editable + GPU + extras), quickstart (runnable ~30-line example mirroring the quickstart notebook), and the two highest-value 'tribal knowledge' pages migrated from CLAUDE.md: - physics/units.md — the ENC (wire) vs ADC (pixel) convention + threshold-units table - concepts/coordinates.md — the volume-local frame, the canonical-frame rationale, and the frame-mismatch bug class (incl. the pixel-origin bug + ND-LAr trigger) nav links validated; mkdocstrings/jupyter plugins stubbed for a later pass.
1 parent f88f3fa commit 06013d5

6 files changed

Lines changed: 301 additions & 0 deletions

File tree

‎docs/concepts/coordinates.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Coordinates & frames
2+
3+
JAXTPC transforms every deposit into a **volume-local frame** before any physics
4+
runs. Understanding this is essential for extending the simulator (new
5+
detectors, new readout references) — and a frame mismatch here is a real bug
6+
class (see the box at the bottom).
7+
8+
## The local-frame transform
9+
10+
The loader (`tools/loader.py`) maps each deposit from global detector
11+
coordinates to its volume's local frame:
12+
13+
- **Drift axis (x):** `x_local = drift_direction * (x_anode_cm - x_global)`, so
14+
`x_local ≥ 0` and electrons always drift toward `x_local = 0` (the anode),
15+
regardless of which way the volume physically drifts.
16+
- **Transverse axes (y, z):** **centered**, `y_local = y_global - y_center`,
17+
`z_local = z_global - z_center`, where `(y_center, z_center)` is the volume
18+
center `((min+max)/2)` stored as `yz_center_cm`.
19+
20+
## Why: one canonical frame for all volumes
21+
22+
Because the per-volume `drift_direction`, `x_anode`, and `yz_center` are consumed
23+
*once* in the loader, every volume reduces to the **same** local frame — anode at
24+
`x_local = 0`, drift toward `−x`, transverse centered at 0. The JIT physics body
25+
can then use **fixed constants** instead of indexing per-volume geometry inside
26+
the `lax.scan`/`vmap` over volumes. This is what makes a single compiled body
27+
handle any number of volumes.
28+
29+
The inverse transform (local → global) is applied per-volume when writing output
30+
(`production/save.py`), using that volume's own `drift_direction`, `x_anode`, and
31+
`yz_center` — never volume 0's, never a global assumption.
32+
33+
## The invariant for references
34+
35+
Any quantity you compare against a local position must itself be in the **local**
36+
frame. Two examples in the codebase:
37+
38+
- **Wire indexing** (`tools/geometry.py`) builds the wire index reference from
39+
`corners_centered = [±half_y, ±half_z]` — centered, i.e. the local frame. ✔
40+
- **Pixel grid origin** (`tools/config.py`) is stored as
41+
`range_min − center = −half_extent` — also local. ✔
42+
43+
!!! danger "Frame-mismatch bug class"
44+
If a reference is stored in the **global** frame but compared against
45+
**local** positions, results are correct only when the volume is centered at
46+
0 (where the two frames coincide). For an off-center volume, deposits map to
47+
the wrong cell or out-of-bounds → silent signal loss. This exact bug existed
48+
in the pixel grid origin (global `range_min` vs local-centered positions) and
49+
was fixed by storing the origin in the local frame. DUNE ND-LAr (off-center
50+
pixel modules) is the config that would have triggered it.
51+
52+
## Geometry-uniformity assumption
53+
54+
The JIT body captures `cfg.volumes[0]` and applies its geometry (pitch, origin,
55+
wire spacing/angles, max drift, etc.) to **all** volumes. This is correct only if
56+
all volumes share the same local-frame geometry. Every shipped config satisfies
57+
this (uniform within each detector), but it is currently **unvalidated** — adding
58+
an init-time uniformity check is a recommended guard (see the production-
59+
readiness notes). When adding a detector, keep all volumes geometrically uniform,
60+
or the volume-0 assumption will silently apply.

‎docs/index.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# JAXTPC
2+
3+
GPU-accelerated, **differentiable** liquid-argon Time Projection Chamber (TPC)
4+
detector simulation in JAX. It models the full detector response chain — charge
5+
recombination, electron drift with lifetime attenuation, diffusion-convolved
6+
wire/pixel response, electronics shaping, noise, and ADC digitization — for
7+
arbitrary multi-volume geometries (SBND, MicroBooNE, ICARUS, DUNE FD1, DUNE
8+
ND-LAr) with both wire and pixel readout.
9+
10+
## Two execution paths
11+
12+
- **Production** — `DetectorSimulator.process_event(...)`: batched, JIT-compiled,
13+
bounded-memory; the path for generating datasets.
14+
- **Differentiable** — `forward(...)` / `forward_segments(...)`: memory-efficient
15+
reverse-mode gradients through every physics parameter (velocity, lifetime,
16+
diffusion, recombination), for optimization and reconstruction.
17+
18+
## Start here
19+
20+
- **[Install](install.md)** — `pip install -e .`
21+
- **[Quickstart](quickstart.md)** — run a simulation in ~30 lines
22+
- **[Notebooks](https://github.com/DeepLearnPhysics/JAXTPC/tree/main/notebooks)** —
23+
themed, runnable examples (getting started, physics, readout, gradients, reco,
24+
calibration, production)
25+
26+
## Read these before you get surprised
27+
28+
Two conventions account for most confusion:
29+
30+
- **[Units (ENC vs ADC)](physics/units.md)** — wire hits are in electrons (ENC),
31+
pixel hits are in ADC; thresholds mean different things per readout.
32+
- **[Coordinates & frames](concepts/coordinates.md)** — positions are
33+
volume-local/centered; this is load-bearing for the whole pipeline.
34+
35+
## Project status
36+
37+
See the **[documentation roadmap](PLAN.md)** for what's written, what's planned,
38+
and how the docs and notebooks are organized.

‎docs/install.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Installation
2+
3+
JAXTPC is installable as `jaxtpc`. The supported mode today is an **editable
4+
install** from a clone (the `src/jaxtpc/` namespace migration is
5+
[deferred](PLAN.md), so a non-editable wheel isn't fully supported yet).
6+
7+
```bash
8+
git clone https://github.com/DeepLearnPhysics/JAXTPC.git
9+
cd JAXTPC
10+
pip install -e .
11+
```
12+
13+
This installs the runtime dependencies (JAX, NumPy, SciPy, Matplotlib, h5py,
14+
hdf5plugin, PyYAML, Pillow) and registers the CLIs (`jaxtpc-batch`,
15+
`jaxtpc-setup-production`, `jaxtpc-make-labl`, `jaxtpc-viewer`,
16+
`jaxtpc-export-gif`).
17+
18+
## GPU (JAX with CUDA)
19+
20+
By default JAX installs CPU-only. For GPU, install the CUDA build:
21+
22+
```bash
23+
pip install -e ".[gpu]" # jax[cuda12]
24+
# or follow https://docs.jax.dev/en/latest/installation.html for your CUDA setup
25+
```
26+
27+
## Optional extras
28+
29+
```bash
30+
pip install -e ".[dev]" # pytest, nbstripout
31+
pip install -e ".[docs]" # mkdocs-material, mkdocstrings, mkdocs-jupyter
32+
```
33+
34+
## Notebook output stripping (once per clone)
35+
36+
Notebook outputs are kept out of git via an `nbstripout` filter. After cloning:
37+
38+
```bash
39+
pip install nbstripout
40+
nbstripout --install --attributes .gitattributes
41+
```
42+
43+
## Verify
44+
45+
```bash
46+
python -c "import tools, jax; print('JAXTPC OK', jax.devices())"
47+
JAX_PLATFORM_NAME=cpu pytest -m "not slow" -q # ~2 min, CPU
48+
```
49+
50+
!!! note "Use `python3` on systems where `python` is Python 2"
51+
All commands assume `python` is Python ≥ 3.10.

‎docs/physics/units.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Units convention: ENC vs ADC
2+
3+
The wire and pixel paths use **different unit conventions at the hits stage**.
4+
This is intentional, and it is the single most common source of confusion.
5+
6+
| Readout | Kernel | Hits stage | Sensor signal | Pipeline |
7+
|---|---|---|---|---|
8+
| **Wire** | dimensionless e⁻-impulse fraction | **ENC** (electrons) | **ADC** (12-bit, post-digitize) | response (ENC) → electronics → noise → digitize → ADC |
9+
| **Pixel** | ADC per drift-electron (gain baked in) | **ADC** | **ADC** (no separate digitize) | response → done (signal and hits from one pass) |
10+
11+
**Why they differ:** the wire path applies the field response *before*
12+
electronics, so its kernel is a dimensionless field-impulse fraction and the
13+
intermediate hits are in electrons (ENC). The pixel path bakes the chip's
14+
ADC/electron gain into the kernel and skips the digitize step entirely, so its
15+
hits and sensor signal are already in ADC.
16+
17+
## Thresholds mean different things per readout
18+
19+
The same threshold field carries different units depending on readout. This is
20+
the part that bites:
21+
22+
| Threshold | Wire | Pixel | Where applied |
23+
|---|---|---|---|
24+
| `inter_thresh` | ENC | ADC | in-JIT box compaction / merge pruning (`track_hits.py`) |
25+
| `corr_threshold` / `hits_threshold` | ENC | ADC | host, CSR encode (`production/save.py`) |
26+
| `threshold_adc` | ADC | ADC | host, `to_sparse` (sensor only, `tools/output.py`) |
27+
28+
So when you set a threshold, ask **which readout** and **which stage** — an
29+
`inter_thresh` of `1.0` means 1 electron for wire but 1 ADC count for pixel.
30+
31+
## Wire kernel NPZ caveat
32+
33+
`tools/responses/{U,V,Y}_plane_kernel.npz` carry `units = 'ADC_per_electron'`
34+
metadata plus an `adc_per_electron ≈ 0.005` field. **In this pipeline the kernel
35+
values are treated as a dimensionless field-impulse contribution**
36+
(`intensity (electrons) × kernel → ENC`). The `adc_per_electron` /
37+
`electrons_per_adc` metadata is *not* consumed in the JIT path — it's
38+
informational, reflecting the kernel's first-principles calibration source. The
39+
"ADC" produced by `_digitize_signal` is just the quantization step (round +
40+
pedestal + clip) applied to values the electronics chain has already shaped to
41+
ADC scale.
42+
43+
## Practical guidance
44+
45+
- Reading wire hits? They're **electrons**. Reading pixel hits? They're **ADC**.
46+
- Converting electrons ↔ ADC for wire sensor output uses `cfg.electrons_per_adc`.
47+
- When in doubt, print the magnitudes: wire ENC values are in the hundreds–
48+
thousands of electrons; pixel ADC values are small integers/counts.

‎docs/quickstart.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Quickstart
2+
3+
The smallest end-to-end example: build a wire detector, generate a synthetic
4+
event, run the simulation, and plot the readout. No external data needed.
5+
6+
For the runnable version, see
7+
[`notebooks/getting_started/00_quickstart.ipynb`](https://github.com/DeepLearnPhysics/JAXTPC/blob/main/notebooks/getting_started/00_quickstart.ipynb).
8+
9+
```python
10+
import jax, numpy as np, matplotlib.pyplot as plt
11+
from tools.simulation import DetectorSimulator
12+
from tools.geometry import generate_detector
13+
from tools.loader import build_deposit_data
14+
from tools.output import to_sparse
15+
from tools.visualization import visualize_wire_signals
16+
17+
# 1. Build a dual-TPC wire detector
18+
detector = generate_detector("config/cubic_wireplane_config.yaml")
19+
sim = DetectorSimulator(detector, include_track_hits=True, include_digitize=True,
20+
total_pad=50_000, response_chunk_size=10_000)
21+
cfg = sim.config
22+
23+
# 2. Generate a synthetic event (a few straight MIP-like tracks)
24+
def make_synthetic_event(seed=0, n_tracks=6, step_cm=0.4):
25+
rng = np.random.RandomState(seed)
26+
P, DE, DX, TID = [], [], [], []
27+
for t in range(n_tracks):
28+
start = rng.uniform(-180, 180, 3); d = rng.normal(size=3); d /= np.linalg.norm(d)
29+
n = int(rng.uniform(80, 250) / step_cm); s = np.arange(n) * step_cm
30+
pts = np.clip(start[None, :] + s[:, None] * d[None, :], -215.9, 215.9)
31+
P.append(pts); DE.append(np.full(n, rng.uniform(1.8, 2.6) * step_cm, np.float32))
32+
DX.append(np.full(n, step_cm, np.float32)); TID.append(np.full(n, t, np.int32))
33+
return (np.concatenate(P) * 10).astype(np.float32), np.concatenate(DE), np.concatenate(DX), np.concatenate(TID)
34+
35+
pos_mm, de, dx, track_ids = make_synthetic_event()
36+
deposits = build_deposit_data(pos_mm, de, dx, cfg, track_ids=track_ids)
37+
38+
# 3. Run
39+
sim.warm_up()
40+
signals, track_hits_raw, deposits = sim.process_event(deposits, key=jax.random.PRNGKey(42))
41+
42+
# 4. Sparse output + plot
43+
sparse = to_sparse(signals, cfg, threshold_adc=1200 / cfg.electrons_per_adc)
44+
visualize_wire_signals(sparse, cfg, threshold_enc=1200, gamma=0.2, sparse=True)
45+
plt.show()
46+
```
47+
48+
To simulate **real data**, replace step 2 with:
49+
50+
```python
51+
from tools.loader import load_event
52+
deposits = load_event("events.h5", cfg, event_idx=0)
53+
```
54+
55+
## Next steps
56+
57+
- [`notebooks/getting_started/wire_simulation.ipynb`](https://github.com/DeepLearnPhysics/JAXTPC/blob/main/notebooks/getting_started/wire_simulation.ipynb) — full walkthrough with truth/track labels
58+
- [`notebooks/readout/pixel_simulation.ipynb`](https://github.com/DeepLearnPhysics/JAXTPC/blob/main/notebooks/readout/pixel_simulation.ipynb) — pixel readout
59+
- [Units (ENC vs ADC)](physics/units.md) and [Coordinates](concepts/coordinates.md) — the two conventions to know

‎mkdocs.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
site_name: JAXTPC
2+
site_description: GPU-accelerated, differentiable liquid-argon TPC detector simulation in JAX
3+
repo_url: https://github.com/DeepLearnPhysics/JAXTPC
4+
repo_name: DeepLearnPhysics/JAXTPC
5+
docs_dir: docs
6+
7+
theme:
8+
name: material
9+
features:
10+
- navigation.sections
11+
- navigation.top
12+
- navigation.instant
13+
- content.code.copy
14+
- search.suggest
15+
palette:
16+
- scheme: default
17+
primary: indigo
18+
toggle: { icon: material/weather-night, name: Dark mode }
19+
- scheme: slate
20+
primary: indigo
21+
toggle: { icon: material/weather-sunny, name: Light mode }
22+
23+
# Build with the docs extra: pip install -e ".[docs]" && mkdocs serve
24+
plugins:
25+
- search
26+
# - mkdocstrings: # auto API reference from docstrings (enable once docs/reference/api/* added)
27+
# handlers: { python: { paths: ["."] } }
28+
# - mkdocs-jupyter: # render notebooks/ as pages
29+
30+
markdown_extensions:
31+
- admonition
32+
- tables
33+
- toc: { permalink: true }
34+
- pymdownx.highlight
35+
- pymdownx.superfences
36+
37+
nav:
38+
- Home: index.md
39+
- Install: install.md
40+
- Quickstart: quickstart.md
41+
- Concepts:
42+
- Coordinates & frames: concepts/coordinates.md
43+
- Physics:
44+
- Units (ENC vs ADC): physics/units.md
45+
- Roadmap: PLAN.md

0 commit comments

Comments
 (0)