mohamedelashri/hep-tools

Use when working with jagged or variable-length arrays in Python HEP analysis: building event records with ak.zip, filtering nested arrays, computing combinatorics (cartesian products or combinations), flattening ragged arrays, using argmin/argmax with keepdims, broadcasting per-event weights to per-object, or debugging OptionType/None-padding issues in Awkward 2.x workflows.

Use when building a HEP statistical analysis with cabinetry: writing a cabinetry config file, building histogram templates from ROOT NTuples, constructing a pyhf workspace, running a profile likelihood fit, visualising pre/post-fit data-MC comparisons, producing pull plots and NP rankings, or computing CLs exclusion limits or discovery significance via cabinetry's high-level API.

Use when building a Python command-line interface with Typer: adding arguments and options to a script, creating subcommands, wiring an entry point into pyproject.toml, validating CLI inputs with callbacks, or adding a CLI layer to an existing analysis script or HEP workflow.

Use when setting up code quality tooling for a HEP Python project: configuring pre-commit hooks, adding ruff for linting and auto-formatting, setting up mypy for static type checking, or debugging linter failures in CI or a pre-commit run.

Use when building a columnar HEP analysis with coffea: loading ROOT data as NanoEvents, choosing a schema, writing a ProcessorABC processor, accumulating histograms or cutflows, and scaling execution from local iteration to Dask.

Use when writing Python bindings for C++ HEP code with nanobind or pybind11: exposing a C++ class or function to Python, binding STL containers (vector, map), handling numpy/awkward array interop, choosing between nanobind and pybind11, or setting up a CMake build that produces a Python extension module.

Use when working with particle decay chains in Python: parsing EvtGen or DecFiles .dec decay descriptors with DecFileParser, building DecayChain and DecayMode objects programmatically, visualizing decay trees with DecayChainViewer, computing visible branching fractions, or converting AmpGen amplitude models to GooFit format. Also use when looking up LHCb or Belle II bundled decay tables, handling charge-conjugate decays, or filtering decay chains by minimum effective branching fraction.

Use when running jet clustering in Python with the Scikit-HEP fastjet package (or migrating from the deprecated pyjet): calling anti-kt or Cambridge/Aachen algorithms on particle four-vectors, accessing jet constituents, computing jet substructure variables (N-subjettiness, soft drop), clustering jets from generator-level events read with pyhepmc or pylhe, or processing many events over awkward arrays with the array-oriented (columnar) interface to avoid slow Python loops.

Use when accessing ROOT files on EOS, WLCG storage, or another XRootD endpoint from Python through fsspec: opening root:// URIs with uproot, listing remote directories, handling authentication, or diagnosing XRootD path and timeout failures.

Use when writing unit-safe HEP code in Python: converting between MeV and GeV, expressing cross-sections or luminosities with explicit units, computing ctau or decay lengths from particle lifetimes, checking that cut thresholds or histogram ranges carry correct units, or bridging hepunits values with Pint quantities.

Use when creating, filling, slicing, or plotting histograms with the scikit-hep hist library: defining axes (Regular, Variable, StrCategory), filling with weighted data, using UHI indexing (loc, rebin, sum), applying an mplhep experiment style, producing ratio panels for data/MC comparisons, or projecting multi-dimensional histograms.

Use when you need to minimize a scalar cost function in Python using MINUIT2 via iminuit (e.g., unbinned likelihood fits or least-squares fits), and you need HESSE/MINOS-style uncertainties or custom cost functions.

Use when selecting or debugging standalone CERN LCG software from CVMFS: choosing an LCG view and platform, sourcing its environment, checking package versions, or avoiding conflicts between LCG views and experiment releases.

Use when plotting HEP histograms with matplotlib and mplhep: applying a stable experiment style such as LHCb2, adding LHCb labels, drawing 1D or 2D histograms, and constructing data/model comparisons or ratio panels.

Use when looking up particle properties (mass, charge, width, PDG ID, lifetime, spin, parity) from the PDG tables in Python: converting between particle names and PDG IDs, filtering decay modes, checking if a particle is stable, querying quantum numbers (J, P, C, G, I), working with MC generator output where particle codes need to be identified or converted (Geant3, Pythia, Corsika7, EvtGen), or using particle/PDGID literals in analysis code.

Use when reading or writing HepMC3 event records in Python: opening HepMC2, HepMC3, LHEF, or HEPEVT files from a Monte Carlo generator, iterating over events, accessing truth particles and vertices, filtering by status code or PDG ID, traversing decay trees via particle parents/children, using the NumPy API for fast vectorized processing, visualizing events in Jupyter notebooks, or writing modified events back to a HepMC file.

Use when you need HistFactory statistical modeling, profile-likelihood fits, CLs limits, or workspace manipulation in Python.

Use when reading, writing, or validating binned and/or unbinned statistical models in the HS3 (HEP Statistics Serialization Standard) JSON format: loading an HS3 workspace, validating schema compliance, building and evaluating a model (logpdf), serialising a workspace for publication, or working with the standardized JSON format for HEP statistical models.

Use when reading or writing Les Houches Event (LHE) files in Python: reading parton-level events from MadGraph, Powheg, Sherpa, Pythia, or Whizard generators, iterating over initial- and final-state parton four-vectors, accessing event weights and scale/PDF reweighting blocks, counting events efficiently, writing modified LHE files back to disk, visualising event topologies with graphviz, or converting events to awkward arrays for vectorized analysis. Also use when the user mentions LHEFile, LHEEvent, LHEParticle, or parsing .lhe / .lhe.gz files.

Use when a pytest suite is slow and needs speeding up: profiling slow tests, reducing collection time, parallelizing with pytest-xdist or pytest-split, selecting a subset of tests to run, blocking inadvertent network or large-file disk access in HEP tests, or optimizing CI test run time.

Use when creating a new Python package, adding pyproject.toml to an existing project, choosing a build backend, setting up src layout, configuring VCS-based versioning, or managing a development environment with pixi or uv for a HEP Python project.

Use when writing or configuring tests for a HEP Python project with pytest: setting up pyproject.toml test configuration, writing fixtures and parametrized tests, handling numerical tolerances for physics quantities, setting up code coverage, or choosing between unit and integration tests.

Use when performing statistical unfolding for a HEP measurement: measurement: building a response matrix from MC, applying Bayesian iterative unfolding (RooUnfoldBayes), SVD unfolding (RooUnfoldSvd), bin-by-bin correction factors, or any other RooUnfold algorithm; handling detector-level fakes or backgrounds (response.Fake, SetBkg); propagating statistical and systematic uncertainties through the unfolding; comparing unfolding methods for stability; or performing closure tests.

Use when delivering analysis-ready columns from remote HEP datasets with ServiceX: defining FileList, XRootD, Rucio, or CERN Open Data inputs, choosing an uproot query, limiting branches and events, and diagnosing delivery or authorization failures.

Use when generating a self-contained Python script with PEP 723 inline dependency metadata: writing the script block header, making a script runnable with uv run --script, combining with a Typer CLI for argument handling, or creating a one-off analysis tool that should not live inside a package and must declare its own dependencies inline.

Use when reading or writing ROOT files in Python without a ROOT installation, or when encountering issues opening TTrees, RNTuples, or histograms.

Use when computing 4-vector quantities in Python: invariant mass, deltaR, transverse momentum, boost, or any Lorentz vector arithmetic over collections of particles. Also use when registering scikit-hep vector behaviors on awkward-array records so that ak.zip objects gain Momentum4D methods, or when constructing vector objects from (pt, phi, eta, mass) or (px, py, pz, energy) field conventions.

Use when planning or debugging an XCache proxy for repeated XRootD reads: choosing cache boundaries, routing root:// requests through the proxy, validating cache hits and bypass behavior, or handling credentials and storage limits safely.