physicskit 0.1.0__py3-none-any.whl

physicskit/particle/kinematics.py

@@ -0,0 +1,271 @@
+r"""Relativistic four-vector kinematics.
+
+Works throughout in **natural units with** :math:`c=1`: energy, momentum,
+and mass all share the same energy-like unit (GeV for particle physics,
+MeV for nuclear physics -- the caller's choice, so long as it is used
+consistently), the same convention :mod:`physicskit.relativity` uses for
+its own geometrized units (:math:`G=c=1`).
+
+- :class:`FourVector` -- an energy-momentum four-vector :math:`p^\mu =
+  (E, p_x, p_y, p_z)`, with its invariant mass, speed, and Lorentz factor
+  as derived properties.
+- :func:`boost` -- a Lorentz boost along a Cartesian axis.
+- :func:`boost_generic` -- a Lorentz boost along an arbitrary 3-velocity.
+- :func:`invariant_mass` -- the invariant mass of a system of particles.
+- :func:`rapidity` -- the additive (under boosts) rapidity variable.
+- :func:`boost_to_com` -- the velocity of a system's center-of-momentum frame.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ["FourVector", "boost", "boost_generic", "invariant_mass", "rapidity", "boost_to_com"]
+
+
+class FourVector:
+    r"""An energy-momentum four-vector :math:`p^\mu=(E,p_x,p_y,p_z)`.
+
+    Parameters
+    ----------
+    E : float
+        Energy.
+    px, py, pz : float
+        Momentum components.
+
+    Examples
+    --------
+    >>> p = FourVector(2.0, 0.0, 0.0, 1.0)
+    >>> round(p.mass, 6)
+    1.732051
+    """
+
+    def __init__(self, E, px, py, pz):
+        self.E = float(E)
+        self.px = float(px)
+        self.py = float(py)
+        self.pz = float(pz)
+
+    @property
+    def p_vec(self):
+        """``ndarray`` of shape (3,): the momentum 3-vector."""
+        return np.array([self.px, self.py, self.pz])
+
+    @property
+    def p_mag(self):
+        r"""Momentum magnitude, :math:`|\vec p|`."""
+        return float(np.linalg.norm(self.p_vec))
+
+    @property
+    def mass(self):
+        r"""Invariant mass, :math:`m=\sqrt{E^2-|\vec p|^2}`.
+
+        The radicand is clipped at 0 before the square root, so a
+        four-vector that is numerically spacelike only by floating-point
+        noise (e.g. the sum of several on-shell four-vectors) returns
+        ``0.0`` rather than raising on a tiny negative argument.
+        """
+        radicand = self.E**2 - self.p_mag**2
+        return float(np.sqrt(max(radicand, 0.0)))
+
+    @property
+    def beta(self):
+        r"""Speed, :math:`\beta=|\vec p|/E`."""
+        return self.p_mag / self.E
+
+    @property
+    def gamma(self):
+        r"""Lorentz factor, :math:`\gamma=E/m`.
+
+        Raises
+        ------
+        ZeroDivisionError
+            If the four-vector is massless (no rest frame).
+        """
+        m = self.mass
+        if m == 0.0:
+            raise ZeroDivisionError("A massless four-vector has no rest frame / undefined gamma.")
+        return self.E / m
+
+    def __add__(self, other):
+        return FourVector(self.E + other.E, self.px + other.px, self.py + other.py, self.pz + other.pz)
+
+    def __sub__(self, other):
+        return FourVector(self.E - other.E, self.px - other.px, self.py - other.py, self.pz - other.pz)
+
+    def __repr__(self):
+        return f"FourVector(E={self.E:.4g}, px={self.px:.4g}, py={self.py:.4g}, pz={self.pz:.4g})"
+
+
+def boost(four_vector, beta, axis="z"):
+    r"""Lorentz-boost a :class:`FourVector` along a Cartesian axis.
+
+    Parameters
+    ----------
+    four_vector : FourVector
+        The four-vector to boost.
+    beta : float
+        Boost velocity, :math:`-1 < \beta < 1`, in units of :math:`c=1`.
+    axis : {"x", "y", "z"}, default="z"
+        Cartesian axis of the boost.
+
+    Returns
+    -------
+    FourVector
+        The boosted four-vector.
+
+    Examples
+    --------
+    >>> p = FourVector(1.0, 0.0, 0.0, 0.0)  # a particle at rest, mass 1
+    >>> pb = boost(p, 0.6, axis="z")
+    >>> round(pb.E, 6), round(pb.pz, 6)
+    (1.25, 0.75)
+    """
+    if not (-1.0 < beta < 1.0):
+        raise ValueError(f"beta={beta} must satisfy -1 < beta < 1.")
+    gamma = 1.0 / np.sqrt(1.0 - beta**2)
+    E, px, py, pz = four_vector.E, four_vector.px, four_vector.py, four_vector.pz
+    if axis == "x":
+        return FourVector(gamma * (E + beta * px), gamma * (px + beta * E), py, pz)
+    elif axis == "y":
+        return FourVector(gamma * (E + beta * py), px, gamma * (py + beta * E), pz)
+    elif axis == "z":
+        return FourVector(gamma * (E + beta * pz), px, py, gamma * (pz + beta * E))
+    raise ValueError(f"axis must be 'x', 'y', or 'z', got {axis!r}.")
+
+
+def boost_generic(four_vector, beta_vec):
+    r"""Lorentz-boost a :class:`FourVector` along an arbitrary 3-velocity.
+
+    Generalizes :func:`boost` to a boost direction that need not lie
+    along a Cartesian axis -- the transformation used, e.g., to take a
+    daughter four-momentum computed in a parent's rest frame back to the
+    lab frame when the parent's own flight direction is not one of the
+    axes (as happens at every vertex of a branching cascade; see
+    :mod:`physicskit.particle.collider`).
+
+    .. math::
+
+        E' = \gamma(E + \vec\beta\cdot\vec p), \qquad
+        \vec p' = \vec p + \left[\frac{\gamma-1}{\beta^2}(\vec\beta\cdot\vec p)
+        + \gamma E\right]\vec\beta
+
+    which reduces to :func:`boost` when :math:`\vec\beta` is aligned with
+    a single axis.
+
+    Parameters
+    ----------
+    four_vector : FourVector
+        The four-vector to boost.
+    beta_vec : array_like of shape (3,)
+        Boost velocity, :math:`|\vec\beta| < 1`, in units of :math:`c=1`.
+
+    Returns
+    -------
+    FourVector
+        The boosted four-vector.
+
+    Examples
+    --------
+    >>> p = FourVector(1.0, 0.0, 0.0, 0.0)  # a particle at rest, mass 1
+    >>> pb = boost_generic(p, [0.0, 0.0, 0.6])
+    >>> round(pb.E, 6), round(pb.pz, 6)
+    (1.25, 0.75)
+    """
+    beta_vec = np.asarray(beta_vec, dtype=float)
+    beta2 = float(beta_vec @ beta_vec)
+    if beta2 >= 1.0:
+        raise ValueError(f"|beta_vec|={np.sqrt(beta2)} must be < 1.")
+    if beta2 == 0.0:
+        return FourVector(four_vector.E, four_vector.px, four_vector.py, four_vector.pz)
+    gamma = 1.0 / np.sqrt(1.0 - beta2)
+    E, p_vec = four_vector.E, four_vector.p_vec
+    p_dot_beta = float(p_vec @ beta_vec)
+    p_new = p_vec + ((gamma - 1.0) * p_dot_beta / beta2 + gamma * E) * beta_vec
+    E_new = gamma * (E + p_dot_beta)
+    return FourVector(float(E_new), *[float(c) for c in p_new])
+
+
+def invariant_mass(four_vectors):
+    """The invariant mass of a system of four-vectors.
+
+    Parameters
+    ----------
+    four_vectors : iterable of FourVector
+        The particles making up the system.
+
+    Returns
+    -------
+    float
+        The mass of the sum of the four-vectors -- e.g. the reconstructed
+        mass of a resonance from its decay products.
+
+    Examples
+    --------
+    >>> p1 = FourVector(1.0, 0.0, 0.0, 0.6)
+    >>> p2 = FourVector(1.0, 0.0, 0.0, -0.6)
+    >>> round(invariant_mass([p1, p2]), 6)
+    2.0
+    """
+    total = None
+    for p in four_vectors:
+        total = p if total is None else total + p
+    return total.mass
+
+
+def rapidity(four_vector, axis="z"):
+    r"""Rapidity along a Cartesian axis, :math:`y=\tfrac12\ln\!\big[(E+p_i)/(E-p_i)\big]`.
+
+    Rapidity is additive under boosts along the same axis: boosting a
+    particle by velocity :math:`\beta` shifts its rapidity by exactly
+    :math:`\operatorname{artanh}\beta`.
+
+    Parameters
+    ----------
+    four_vector : FourVector
+        The particle.
+    axis : {"x", "y", "z"}, default="z"
+        Cartesian axis.
+
+    Returns
+    -------
+    float
+
+    Examples
+    --------
+    >>> p = FourVector(2.0, 0.0, 0.0, 1.0)
+    >>> round(rapidity(p), 6)
+    0.549306
+    """
+    E = four_vector.E
+    p_i = {"x": four_vector.px, "y": four_vector.py, "z": four_vector.pz}[axis]
+    return float(0.5 * np.log((E + p_i) / (E - p_i)))
+
+
+def boost_to_com(four_vectors):
+    """The 3-velocity of the center-of-momentum frame of a system.
+
+    Parameters
+    ----------
+    four_vectors : iterable of FourVector
+        The particles making up the system.
+
+    Returns
+    -------
+    ndarray of shape (3,)
+        The velocity (units of :math:`c=1`) of the system's total
+        momentum relative to the current frame, :math:`\\vec\\beta_{\\rm
+        com} = \\vec p_{\\rm tot}/E_{\\rm tot}`.
+
+    Examples
+    --------
+    >>> p1 = FourVector(2.0, 0.0, 0.0, 1.0)
+    >>> p2 = FourVector(1.0, 0.0, 0.0, 0.0)
+    >>> beta_com = boost_to_com([p1, p2])
+    >>> [round(float(b), 6) for b in beta_com]
+    [0.0, 0.0, 0.333333]
+    """
+    total = None
+    for p in four_vectors:
+        total = p if total is None else total + p
+    return total.p_vec / total.E

physicskit/particle/neutrinos.py

@@ -0,0 +1,84 @@
+r"""Two-flavor vacuum neutrino oscillations.
+
+- :func:`oscillation_probability` -- the standard two-flavor
+  :math:`\nu_e\to\nu_\mu` vacuum oscillation probability.
+- :func:`survival_probability` -- its complement, :math:`\nu_e\to\nu_e`.
+
+**Simplification**: a full treatment has three flavors, a PMNS matrix
+with three mixing angles and a CP-violating phase, and matter (MSW)
+effects for neutrinos propagating through the Earth or the Sun. The
+two-flavor vacuum-oscillation formula used here is the standard
+leading-order approximation whenever a single mass-squared splitting
+dominates (as :math:`\Delta m^2_{21}` or :math:`\Delta m^2_{31}}` each
+individually do in different regimes), and is the textbook starting
+point for any oscillation demonstration (see the Particle Data Group's
+"Neutrino Mixing" review).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ["oscillation_probability", "survival_probability"]
+
+
+def oscillation_probability(L, E, theta, delta_m2):
+    r"""Two-flavor vacuum oscillation probability :math:`P(\nu_e\to\nu_\mu)`.
+
+    .. math::
+
+        P(\nu_e\to\nu_\mu) = \sin^2(2\theta)\,
+        \sin^2\!\left(1.267\,\frac{\Delta m^2 L}{E}\right)
+
+    the standard PDG form in practical units: :math:`L` in km, :math:`E`
+    in GeV, :math:`\Delta m^2` in :math:`{\rm eV}^2` (the numerical
+    constant 1.267 absorbs :math:`\hbar,c` and the unit conversion; see
+    the Particle Data Group's "Neutrino Mixing" review).
+
+    Parameters
+    ----------
+    L : array_like
+        Baseline (distance traveled), in km.
+    E : array_like
+        Neutrino energy, in GeV.
+    theta : float
+        Mixing angle, in radians.
+    delta_m2 : float
+        Mass-squared splitting, in :math:`{\rm eV}^2`.
+
+    Returns
+    -------
+    ndarray or float
+
+    Examples
+    --------
+    >>> round(float(oscillation_probability(0.0, 1.0, 0.5, 2.5e-3)), 10)
+    0.0
+    >>> theta = np.pi / 4  # maximal mixing
+    >>> L_E = np.pi / 2 / (1.267 * 2.5e-3)  # argument = pi/2 -> sin^2 = 1
+    >>> round(float(oscillation_probability(L_E, 1.0, theta, 2.5e-3)), 6)
+    1.0
+    """
+    L = np.asarray(L, dtype=float)
+    E = np.asarray(E, dtype=float)
+    return np.sin(2.0 * theta) ** 2 * np.sin(1.267 * delta_m2 * L / E) ** 2
+
+
+def survival_probability(L, E, theta, delta_m2):
+    r"""Two-flavor vacuum survival probability, :math:`P(\nu_e\to\nu_e)=1-P(\nu_e\to\nu_\mu)`.
+
+    Parameters
+    ----------
+    L, E, theta, delta_m2
+        See :func:`oscillation_probability`.
+
+    Returns
+    -------
+    ndarray or float
+
+    Examples
+    --------
+    >>> round(float(survival_probability(0.0, 1.0, 0.5, 2.5e-3)), 10)
+    1.0
+    """
+    return 1.0 - oscillation_probability(L, E, theta, delta_m2)

physicskit/particle/nuclear.py

@@ -0,0 +1,100 @@
+r"""Nuclear binding energy and reaction Q-values.
+
+Masses and energies here are in **MeV**, the universal convention for the
+semi-empirical mass formula's fitted coefficients.
+
+- :func:`semf_binding_energy`, :func:`binding_energy_per_nucleon` -- the
+  Weizsacker (liquid-drop) semi-empirical mass formula.
+- :func:`q_value` -- the energy released (or absorbed) in a nuclear reaction.
+"""
+
+from __future__ import annotations
+
+__all__ = ["semf_binding_energy", "binding_energy_per_nucleon", "q_value"]
+
+_A_V = 15.75
+_A_S = 17.8
+_A_C = 0.711
+_A_A = 23.7
+_A_P = 11.18
+
+
+def semf_binding_energy(Z, A):
+    r"""Semi-empirical (Weizsacker) total nuclear binding energy, in MeV.
+
+    .. math::
+
+        B(Z,A) = a_V A - a_S A^{2/3} - a_C\frac{Z(Z-1)}{A^{1/3}}
+        - a_A\frac{(A-2Z)^2}{A} + \delta(A,Z)
+
+    with the standard coefficients :math:`a_V=15.75`, :math:`a_S=17.8`,
+    :math:`a_C=0.711`, :math:`a_A=23.7` MeV, and the pairing term
+    :math:`\delta=+a_PA^{-1/2}` for even-even nuclei,
+    :math:`\delta=-a_PA^{-1/2}` for odd-odd nuclei, and :math:`\delta=0`
+    for odd-:math:`A` nuclei, with :math:`a_P\approx11.18` MeV.
+
+    Parameters
+    ----------
+    Z : int
+        Atomic (proton) number.
+    A : int
+        Mass number.
+
+    Returns
+    -------
+    float
+        Total binding energy, in MeV.
+
+    Examples
+    --------
+    >>> B = semf_binding_energy(26, 56)  # Iron-56
+    >>> 8.0 < B / 56 < 9.0
+    True
+    """
+    N = A - Z
+    if Z % 2 == 0 and N % 2 == 0:
+        delta = _A_P / A**0.5
+    elif Z % 2 == 1 and N % 2 == 1:
+        delta = -_A_P / A**0.5
+    else:
+        delta = 0.0
+    return _A_V * A - _A_S * A ** (2 / 3) - _A_C * Z * (Z - 1) / A ** (1 / 3) - _A_A * (A - 2 * Z) ** 2 / A + delta
+
+
+def binding_energy_per_nucleon(Z, A):
+    """Binding energy per nucleon, ``semf_binding_energy(Z, A) / A``, in MeV.
+
+    Examples
+    --------
+    >>> bpn = binding_energy_per_nucleon(26, 56)
+    >>> 8.0 < bpn < 9.0
+    True
+    """
+    return semf_binding_energy(Z, A) / A
+
+
+def q_value(reactant_masses, product_masses):
+    r"""Reaction Q-value, :math:`Q=\sum m_{\rm reactants}-\sum m_{\rm products}`.
+
+    A positive ``Q`` means the reaction is exothermic (releases energy);
+    a negative ``Q`` means it is endothermic and requires that much
+    additional kinetic energy to proceed. Masses (or mass-energies) may be
+    in any consistent unit.
+
+    Parameters
+    ----------
+    reactant_masses : iterable of float
+        Masses of the reactants.
+    product_masses : iterable of float
+        Masses of the products.
+
+    Returns
+    -------
+    float
+
+    Examples
+    --------
+    >>> round(q_value([2.014102, 3.016049], [4.002602, 1.008665]), 6)  # D + T -> He4 + n
+    0.018884
+    """
+    return sum(reactant_masses) - sum(product_masses)

physicskit/particle/scattering.py

@@ -0,0 +1,159 @@
+r"""Cross-sections and Mandelstam kinematics.
+
+Uses the same natural-unit convention (:math:`\hbar=c=1`) as
+:mod:`physicskit.particle.kinematics`.
+
+- :func:`mandelstam_s`, :func:`mandelstam_t`, :func:`mandelstam_u` -- the
+  three relativistic invariants of a 2-to-2 scattering process.
+- :func:`rutherford_dsigma_domega`, :func:`impact_parameter` -- classical
+  Rutherford scattering off a Coulomb potential.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ["ALPHA_FS", "mandelstam_s", "mandelstam_t", "mandelstam_u", "rutherford_dsigma_domega", "impact_parameter"]
+
+ALPHA_FS = 1 / 137.035999084
+"""The fine-structure constant, :math:`\\alpha\\approx1/137.036`."""
+
+
+def _dot_squared(p1, p2, sign):
+    dE = p1.E + sign * p2.E
+    dpx = p1.px + sign * p2.px
+    dpy = p1.py + sign * p2.py
+    dpz = p1.pz + sign * p2.pz
+    return dE**2 - (dpx**2 + dpy**2 + dpz**2)
+
+
+def mandelstam_s(p1, p2):
+    r"""Mandelstam :math:`s=(p_1+p_2)^2`, the total invariant mass squared.
+
+    Parameters
+    ----------
+    p1, p2 : physicskit.particle.kinematics.FourVector
+        The two incoming (or, by the same formula, any two summed) particles.
+
+    Returns
+    -------
+    float
+
+    Examples
+    --------
+    >>> from physicskit.particle.kinematics import FourVector
+    >>> p1 = FourVector(1.0, 0.0, 0.0, 0.6)
+    >>> p2 = FourVector(1.0, 0.0, 0.0, -0.6)
+    >>> round(mandelstam_s(p1, p2), 6)
+    4.0
+    """
+    return float(_dot_squared(p1, p2, +1))
+
+
+def mandelstam_t(p1, p3):
+    r"""Mandelstam :math:`t=(p_1-p_3)^2`, the momentum-transfer invariant.
+
+    Parameters
+    ----------
+    p1 : physicskit.particle.kinematics.FourVector
+        An incoming particle.
+    p3 : physicskit.particle.kinematics.FourVector
+        The outgoing particle it is compared to.
+
+    Returns
+    -------
+    float
+    """
+    return float(_dot_squared(p1, p3, -1))
+
+
+def mandelstam_u(p1, p4):
+    r"""Mandelstam :math:`u=(p_1-p_4)^2`, the other momentum-transfer invariant.
+
+    Parameters
+    ----------
+    p1 : physicskit.particle.kinematics.FourVector
+        An incoming particle.
+    p4 : physicskit.particle.kinematics.FourVector
+        The other outgoing particle.
+
+    Returns
+    -------
+    float
+
+    Notes
+    -----
+    For a 2-to-2 process :math:`1+2\to3+4`, :math:`s+t+u=\sum_i m_i^2`.
+    """
+    return float(_dot_squared(p1, p4, -1))
+
+
+def rutherford_dsigma_domega(theta, Z1, Z2, E_kin, alpha=ALPHA_FS):
+    r"""Rutherford differential cross section, in natural units.
+
+    .. math::
+
+        \frac{d\sigma}{d\Omega} = \left(\frac{Z_1Z_2\alpha}{4E_{\rm kin}}\right)^2
+        \frac{1}{\sin^4(\theta/2)}
+
+    Parameters
+    ----------
+    theta : array_like
+        Scattering angle (radians). ``theta=0`` gives ``inf`` -- the
+        genuine, integrable-but-divergent small-angle Rutherford behavior.
+    Z1, Z2 : float
+        Projectile and target charge numbers.
+    E_kin : float
+        Projectile kinetic energy.
+    alpha : float, default=ALPHA_FS
+        Coupling constant (the fine-structure constant, by default).
+
+    Returns
+    -------
+    ndarray or float
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> theta = np.array([np.pi / 4, np.pi / 2])
+    >>> vals = rutherford_dsigma_domega(theta, Z1=1, Z2=79, E_kin=5.0)
+    >>> ratio = (vals[0] * np.sin(theta[0] / 2) ** 4) / (vals[1] * np.sin(theta[1] / 2) ** 4)
+    >>> round(float(ratio), 6)
+    1.0
+    """
+    theta = np.asarray(theta, dtype=float)
+    prefactor = (Z1 * Z2 * alpha / (4.0 * E_kin)) ** 2
+    with np.errstate(divide="ignore"):
+        result = prefactor / np.sin(theta / 2.0) ** 4
+    return result
+
+
+def impact_parameter(theta, Z1, Z2, E_kin, alpha=ALPHA_FS):
+    r"""Classical Rutherford impact parameter producing scattering angle ``theta``.
+
+    .. math::
+
+        b(\theta) = \frac{Z_1Z_2\alpha}{2E_{\rm kin}}\cot(\theta/2)
+
+    Parameters
+    ----------
+    theta : array_like
+        Scattering angle (radians).
+    Z1, Z2 : float
+        Projectile and target charge numbers.
+    E_kin : float
+        Projectile kinetic energy.
+    alpha : float, default=ALPHA_FS
+        Coupling constant.
+
+    Returns
+    -------
+    ndarray or float
+
+    Examples
+    --------
+    >>> round(float(impact_parameter(np.pi, Z1=1, Z2=79, E_kin=5.0)), 6)
+    0.0
+    """
+    theta = np.asarray(theta, dtype=float)
+    return (Z1 * Z2 * alpha / (2.0 * E_kin)) / np.tan(theta / 2.0)

physicskit/particle/tests/conftest.py

@@ -0,0 +1,7 @@
+"""Test-session setup: force Matplotlib's non-interactive Agg backend
+before anything imports pyplot, so the suite (and CI, which has no
+display) can exercise the plotting/animation code headlessly."""
+
+import matplotlib
+
+matplotlib.use("Agg")