diff --git a/docs/usage/particle.ipynb b/docs/usage/particle.ipynb index fd10e3d7..3c33be59 100644 --- a/docs/usage/particle.ipynb +++ b/docs/usage/particle.ipynb @@ -284,7 +284,7 @@ "source": [ "````{margin}\n", "> [!NOTE]\n", - "> By convention, {mod}`qrules` uses $\\mathrm{GeV}/c^2$ as energy unit.\n", + "> By convention, {mod}`qrules` uses $\\mathrm{GeV}/c^2$ as energy unit (see {class}`.Particle`). The [`hepunits`](https://pypi.org/project/hepunits) package makes unit conversions explicit.\n", "````" ] }, @@ -294,14 +294,15 @@ "metadata": {}, "outputs": [], "source": [ + "from hepunits import GeV, MeV\n", + "\n", "energies_mev = {4180, 4220, 4420, 4600}\n", "template_particle = particle_db[\"J/psi(1S)\"]\n", "for energy_mev in energies_mev:\n", - " energy_gev = energy_mev / 1e3\n", " new_particle = create_particle(\n", " template_particle,\n", " name=f\"EpEm ({energy_mev} MeV)\",\n", - " mass=energy_gev,\n", + " mass=energy_mev * MeV / GeV,\n", " )\n", " particle_db.add(new_particle)\n", "len(particle_db)" diff --git a/pyproject.toml b/pyproject.toml index dcdee701..22a04fb9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -38,6 +38,7 @@ dependencies = [ "PyYAML", "attrs>=20.1.0", # on_setattr and https://www.attrs.org/en/stable/api.html#attrs.define "frozendict", + "hepunits>=2.4.7", "jsonschema", "particle", "python-constraint2", diff --git a/src/qrules/particle/__init__.py b/src/qrules/particle/__init__.py index c1d9ed79..a8330d10 100644 --- a/src/qrules/particle/__init__.py +++ b/src/qrules/particle/__init__.py @@ -120,7 +120,7 @@ def _to_spin(value: Spin | tuple[Fraction, Fraction] | tuple[float, float], /) - @total_ordering @frozen(kw_only=True, order=False, repr=True) class Particle: - """Immutable container of data defining a physical particle. + r"""Immutable container of data defining a physical particle. A `Particle` is defined by the minimum set of the quantum numbers that every possible instances of that particle have in common (the "static" quantum numbers of @@ -132,6 +132,15 @@ class Particle: labels that are not taken into account when checking if two `Particle` instances are equal. + The `~Particle.mass` and `~Particle.width` are expressed in :math:`\mathrm{GeV}` + (with :math:`c=1`). To convert values from another unit, use the `hepunits + `_ package, in which :math:`\mathrm{MeV}=1`: + + >>> from hepunits import GeV, MeV + >>> phi = Particle(name="phi(1020)", pid=333, spin=1, mass=1019.461 * MeV / GeV) + >>> phi.mass + 1.019461 + .. note:: As opposed to classes such as `.EdgeQuantumNumbers` and `.NodeQuantumNumbers`, diff --git a/src/qrules/particle/_adapter/scikit_hep.py b/src/qrules/particle/_adapter/scikit_hep.py index 26b044e2..7779d231 100644 --- a/src/qrules/particle/_adapter/scikit_hep.py +++ b/src/qrules/particle/_adapter/scikit_hep.py @@ -7,6 +7,7 @@ from math import copysign from typing import TYPE_CHECKING +from hepunits import GeV from particle import Particle as PdgDatabase from qrules.particle import Particle, ParticleCollection, Spin @@ -53,7 +54,7 @@ def __convert_pdg_instance(pdg_particle: PdgDatabase) -> Particle: def convert_mass_width(value: float | None) -> float: if value is None: return 0.0 - return float(value) / 1e3 # https://github.com/ComPWA/qrules/issues/14 + return float(value) / GeV def convert_spin(value: Fraction | float | None) -> float: if value is None: diff --git a/uv.lock b/uv.lock index 14f5551f..898a26f0 100644 --- a/uv.lock +++ b/uv.lock @@ -2326,6 +2326,7 @@ source = { editable = "." } dependencies = [ { name = "attrs" }, { name = "frozendict" }, + { name = "hepunits" }, { name = "jsonschema" }, { name = "particle" }, { name = "python-constraint2" }, @@ -2447,6 +2448,7 @@ requires-dist = [ { name = "attrs", specifier = ">=20.1.0" }, { name = "frozendict" }, { name = "graphviz", marker = "extra == 'viz'" }, + { name = "hepunits", specifier = ">=2.4.7" }, { name = "jsonschema" }, { name = "particle" }, { name = "pdg", marker = "extra == 'pdg'" },