pimm documentation#

Particle Imaging Models

Foundation-model research for particle-imaging detectors.

Install pimm

Run the quickstart

pimm is research infrastructure for variable-length, three-dimensional point clouds from particle-imaging detectors. It provides model families, datasets, training and evaluation loops, distributed launchers, and portable exports.

Install#

curl -sSL https://raw.githubusercontent.com/DeepLearnPhysics/particle-imaging-models/main/install.sh | bash

The installer creates the locked environment and checks the native operators. See Installation for requirements, containers, manual setup, and hardware-specific settings.

Use a trained model

Load a local export or a published checkpoint, reproduce its preprocessing, and run a forward pass.

Load, run, and fine-tune a model
Fine-tune a backbone

Select a checkpoint, map its weights into a task model, freeze or unfreeze the right parameters, and evaluate the result.

Fine-tune a checkpoint
Train or pretrain

Choose a real recipe, set the data root, make a small smoke run, then scale it without changing the training config.

Train or pretrain
Bring your own data

Implement a dataset that emits pimm’s packed sample contract, validate one batch, and register it for use in a config.

data/custom
Run on a cluster

Describe your Slurm site once, dry-run the generated job, submit it, monitor it, and resume safely.

Run on Slurm
Extend pimm

Trace one batch through registries, transforms, model, trainer, hooks, evaluator, and checkpoint code before adding a component.

Architecture and extension seams

Verify an installation#

This command resolves the launcher and the bundled tiny configuration, then prints the command it would run. It does not read data or start training.

uv run pimm launch \
  --train.config tests/tiny_semseg \
  --resources.nproc-per-node 1 \
  --dry-run

For an actual training run, follow the ten-minute quickstart. Training requires Linux x86-64 and an NVIDIA driver compatible with the locked CUDA 12.6 environment.

The experiment lifecycle#

Data + transforms Packed batch Model + loss Trainer + hooks Checkpoint + metrics Export + inference

The Python config defines what is trained. Launch YAML and launcher flags define where it runs. Every run records the resolved config, source snapshot, command metadata, logs, and checkpoint state together. The experiment anatomy page connects those objects to their exact implementation.

Supported scope#

Need

Included

Sparse backbones

Point Transformer v1/v2/v3, SparseUNet, LitePT, Volt

Representation learning

Panda/Sonata, PoLAr-MAE

Downstream tasks

semantic segmentation, PointGroup, Panda Detector

Scale

local torchrun, DDP, experimental FSDP2 paths, Slurm via Submitit

Portability

structured checkpoints, plain model weights, Hugging Face exports

Important

pimm currently supports 3D sparse point clouds. A model is only scientifically reusable when its coordinate convention, units, feature order, transforms, dataset revision, and checkpoint revision are known. Start with Data conventions and the model chooser; do not infer preprocessing from an architecture name.

Need an exact answer?#