Skip to content

AGENTS.md

Latest commit

 

History

History
73 lines (50 loc) · 4.77 KB

AGENTS.md

File metadata and controls

73 lines (50 loc) · 4.77 KB
Raw

CLAUDE.md

This file provides guidance to agents when working with code in this repository.

Overview

particle is a pure-Python Scikit-HEP package providing a pythonic interface to the Particle Data Group (PDG) particle data tables and the standard MC particle identification (PDG ID) numbering scheme. The two central public classes are PDGID (queries on an integer ID) and Particle (full object-oriented particle record with search/lookup). The package ships its own data tables and reads them lazily at runtime.

Commands

This is a uv-managed environment; prefer uv run for Python invocations.

uv run pytest                          # run the full test suite
uv run pytest tests/pdgid/             # run one test directory
uv run pytest tests/particle/test_particle.py::test_name   # run a single test
uv run pytest --benchmark-enable       # benchmarks are disabled by default (see addopts)
prek -a --quiet                        # lint / format (ruff, mypy, codespell, etc.)
uv run nox                             # default sessions: lint, pylint, tests
uv run nox -s pylint                   # pylint only
uv run nox -s build                    # build sdist + wheel, twine check
uv run nox -s zipapp                   # build the self-contained particle.pyz

Notes:

  • pytest config sets filterwarnings = ["error"] and xfail_strict = true — warnings and unexpected xpasses fail the suite.
  • Lint enforces from __future__ import annotations at the top of every module (ruff isort required-imports).
  • mypy runs in strict mode over src and tests.

CLI

The package is runnable as a module:

python -m particle search D0      # look up particles by name or PID
python -m particle pdgid 323      # print PDGID property table for an ID

Architecture

src/particle/ is organized into subpackages, each pairing an ID/domain class with optional literals and data:

  • pdgid/ — PDGID (an int subclass) plus functions.py, a large library of free-standing predicates (is_meson, has_bottom, charge, J, etc.) that operate on any SupportsInt. PDGID methods delegate to these functions; the functions are the source of truth and are also re-exported for composable use. literals.py holds named ID aliases (e.g. pi_plus).
  • particle/ — the Particle class (particle.py, ~1300 lines, built with attrs), plus enums.py (Charge, Parity, SpinType, Inv, Status), kinematics.py (width_to_lifetime etc.), utilities.py, regex.py, and convert.py (data-table generation, see below).
  • converters/ — BiMap/DirectionalMaps (bimap.py) plus per-generator converters (pythia.py, geant.py, corsika.py, evtgen.py) backed by CSV files.
  • pythia/, geant/, corsika/, lhcb/ — generator-specific ID classes (PythiaID, Geant3ID, Corsika7ID) and name mappings.
  • data/ — bundled data files plus a loader. Import particle.data and use particle.data.basepath / "particle2026.csv" (uses importlib.resources, so it works even from a zipapp). Do not hardcode filesystem paths to data.

Particle data loading

Particle keeps lazily-populated class-level caches: _table (sorted list), _hash_table (PDGID → Particle), and _table_names. The table is not read at import — load_table() is triggered on first access (e.g. from_pdgid, findall, all). load_table(filename, append=True) lets users extend or replace the built-in table; by default it loads particle2026.csv then nuclei2026.csv. from_pdgid / from_name / findall are the main lookup entry points.

Data files and regeneration

src/particle/data/README.rst documents every data file. The pipeline: the 2008 fixed-width files (mass_width_2008.fwf, mass_width_2008_ext.fwf) + LaTeX names + the year's .txt PDG download are combined by particle/convert.py into the per-year particleYYYY.csv that Particle reads. Regenerate with:

python -m particle.particle.convert regenerate <year> <version>   # rebuild built-in CSVs

The pdgid.literals and particle.literals modules are generated by cog from the CSV table — edit the common_particles source (shared_literals.py) and regenerate, don't hand-edit the generated lists:

uv run nox -s generate_aliases    # runs cog over the two literals.py files

Conventions

  • Every source file begins with the BSD-3 copyright header and from __future__ import annotations.
  • Supported Python is 3.10+; strict dependencies are attrs and hepunits only (pandas/tabulate are dev/test extras, imported lazily where used).
  • Follow the Scikit-HEP developer guide.
  • Releases are cut by tagging v#.#.# on GitHub after updating docs/CHANGELOG.md; the version is derived from git via hatch-vcs.