physicskit 0.1.0__py3-none-any.whl

physicskit/particle/decays.py

@@ -0,0 +1,357 @@
+r"""Two-body decay kinematics and radioactive decay chains.
+
+Uses the same natural-unit convention (:math:`c=1`) as
+:mod:`physicskit.particle.kinematics`.
+
+- :func:`two_body_decay_momentum`, :func:`two_body_decay` -- the
+  kinematics of a parent particle decaying to two daughters.
+- :func:`decay_constant`, :func:`half_life`, :func:`radioactive_decay_number`,
+  :func:`activity` -- the exponential radioactive decay law.
+- :func:`bateman_decay_chain` -- the Bateman equations for a linear chain
+  of successive radioactive decays.
+- :func:`michel_spectrum`, :func:`sample_michel_electron_energies`,
+  :func:`muon_decay_event` -- the three-body :math:`\mu^-\to e^-\bar\nu_\mu\nu_e`
+  weak decay and its (unpolarized, massless-electron) Michel energy spectrum.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from physicskit.particle.kinematics import FourVector, boost_generic
+
+__all__ = [
+    "two_body_decay_momentum",
+    "two_body_decay",
+    "decay_constant",
+    "half_life",
+    "radioactive_decay_number",
+    "activity",
+    "bateman_decay_chain",
+    "michel_spectrum",
+    "sample_michel_electron_energies",
+    "muon_decay_event",
+]
+
+
+def two_body_decay_momentum(M, m1, m2):
+    r"""Daughter momentum magnitude in a two-body decay, in the parent's rest frame.
+
+    .. math::
+
+        p^* = \frac{\sqrt{\lambda(M^2,m_1^2,m_2^2)}}{2M}, \qquad
+        \lambda(a,b,c) = a^2+b^2+c^2-2ab-2bc-2ca
+
+    Parameters
+    ----------
+    M : float
+        Parent mass.
+    m1, m2 : float
+        Daughter masses.
+
+    Returns
+    -------
+    float
+
+    Raises
+    ------
+    ValueError
+        If ``M < m1 + m2`` (energetically forbidden decay).
+
+    Examples
+    --------
+    >>> round(two_body_decay_momentum(1.0, 0.4, 0.4), 6)
+    0.3
+    """
+    if M < m1 + m2:
+        raise ValueError(f"M={M} must be >= m1+m2={m1 + m2} for the decay to be allowed.")
+    a, b, c = M**2, m1**2, m2**2
+    lam = a**2 + b**2 + c**2 - 2 * a * b - 2 * b * c - 2 * c * a
+    return float(np.sqrt(max(lam, 0.0)) / (2.0 * M))
+
+
+def two_body_decay(M, m1, m2, cos_theta, phi):
+    """The two daughters' four-momenta in the parent's rest frame.
+
+    Parameters
+    ----------
+    M : float
+        Parent mass.
+    m1, m2 : float
+        Daughter masses.
+    cos_theta : float
+        Cosine of daughter 1's polar angle from the z-axis.
+    phi : float
+        Daughter 1's azimuthal angle.
+
+    Returns
+    -------
+    p1, p2 : FourVector
+        The two daughters, back-to-back in the parent's rest frame.
+
+    Examples
+    --------
+    >>> p1, p2 = two_body_decay(1.0, 0.4, 0.4, cos_theta=1.0, phi=0.0)
+    >>> round(p1.E, 6), round(p1.pz, 6)
+    (0.5, 0.3)
+    """
+    p_star = two_body_decay_momentum(M, m1, m2)
+    sin_theta = np.sqrt(max(1.0 - cos_theta**2, 0.0))
+    px = p_star * sin_theta * np.cos(phi)
+    py = p_star * sin_theta * np.sin(phi)
+    pz = p_star * cos_theta
+    E1 = np.sqrt(p_star**2 + m1**2)
+    E2 = np.sqrt(p_star**2 + m2**2)
+    p1 = FourVector(float(E1), float(px), float(py), float(pz))
+    p2 = FourVector(float(E2), float(-px), float(-py), float(-pz))
+    return p1, p2
+
+
+def decay_constant(half_life_):
+    r"""Decay constant from half-life, :math:`\lambda=\ln2/t_{1/2}`.
+
+    Examples
+    --------
+    >>> round(decay_constant(np.log(2)), 6)
+    1.0
+    """
+    return float(np.log(2.0) / half_life_)
+
+
+def half_life(decay_constant_):
+    r"""Half-life from decay constant, :math:`t_{1/2}=\ln2/\lambda`.
+
+    Examples
+    --------
+    >>> round(half_life(1.0), 6)
+    0.693147
+    """
+    return float(np.log(2.0) / decay_constant_)
+
+
+def radioactive_decay_number(N0, decay_constant_, t):
+    r"""Surviving population, :math:`N(t)=N_0e^{-\lambda t}`.
+
+    Parameters
+    ----------
+    N0 : float
+        Initial population.
+    decay_constant_ : float
+        Decay constant :math:`\lambda`.
+    t : array_like
+        Time(s), same units as :math:`1/\lambda`.
+
+    Returns
+    -------
+    ndarray or float
+
+    Examples
+    --------
+    >>> round(float(radioactive_decay_number(100.0, 1.0, 0.693147)), 4)
+    50.0
+    """
+    return N0 * np.exp(-decay_constant_ * np.asarray(t))
+
+
+def activity(N, decay_constant_):
+    r"""Decay rate (activity), :math:`A=\lambda N`.
+
+    Examples
+    --------
+    >>> activity(100.0, 0.01)
+    1.0
+    """
+    return decay_constant_ * N
+
+
+def bateman_decay_chain(N0, decay_constants, t):
+    r"""Population of every species in a linear radioactive decay chain.
+
+    Solves the Bateman equations for a chain :math:`1\to2\to\cdots\to n`
+    with decay constants ``decay_constants`` (species 1 starts with
+    population ``N0``, all daughters start at zero):
+
+    .. math::
+
+        N_k(t) = N_0\Big(\prod_{i=1}^{k-1}\lambda_i\Big)
+        \sum_{i=1}^{k}\frac{e^{-\lambda_i t}}
+        {\prod_{j=1,j\neq i}^{k}(\lambda_j-\lambda_i)}
+
+    with :math:`N_1(t)=N_0e^{-\lambda_1 t}`. A zero decay constant for the
+    final species represents a stable end product.
+
+    Parameters
+    ----------
+    N0 : float
+        Initial population of species 1.
+    decay_constants : sequence of float
+        Decay constant of each of the ``n`` species in the chain. Must be
+        pairwise distinct among the species actually populated (the
+        closed-form sum divides by ``lambda_j - lambda_i``).
+    t : array_like
+        Times at which to evaluate the populations.
+
+    Returns
+    -------
+    ndarray of shape (n, len(t))
+        Population of each species over time.
+
+    Examples
+    --------
+    >>> t = np.array([0.0, 1.0])
+    >>> N = bateman_decay_chain(100.0, [1.0, 2.0], t)
+    >>> N.shape
+    (2, 2)
+    >>> round(float(N[0, 0]), 6)
+    100.0
+    """
+    t = np.asarray(t, dtype=float)
+    lam = np.asarray(decay_constants, dtype=float)
+    n = len(lam)
+    N = np.zeros((n, len(t)))
+    for k in range(n):  # k is 0-indexed species k+1
+        prefactor = N0 * np.prod(lam[:k]) if k > 0 else N0
+        total = np.zeros_like(t)
+        for i in range(k + 1):
+            denom = 1.0
+            for j in range(k + 1):
+                if j != i:
+                    denom *= lam[j] - lam[i]
+            total += np.exp(-lam[i] * t) / denom
+        N[k] = prefactor * total
+    return N
+
+
+def michel_spectrum(x):
+    r"""The (unpolarized, massless-electron) Michel spectrum shape for muon decay.
+
+    .. math::
+
+        \frac{d\Gamma}{dx} = 2x^2(3-2x), \qquad x=\frac{2E_e}{m_\mu}\in[0,1]
+
+    the standard leading-order result for :math:`\mu^-\to e^-\bar\nu_\mu\nu_e`
+    from the V-A four-fermion weak interaction (Michel 1950; see e.g.
+    Commins & Bucksbaum, *Weak Interactions of Leptons and Quarks*, Ch. 4,
+    or the muon-decay chapter of any standard particle physics text),
+    in the limit :math:`m_e/m_\mu\to0` and for an unpolarized muon (no
+    Michel parameter :math:`\rho,\eta,\xi,\delta` dependence -- those
+    parametrize corrections from polarization and a nonzero electron
+    mass/anomalous couplings, all set to their V-A/Standard-Model,
+    unpolarized values here). Normalized so that :math:`\int_0^1
+    (d\Gamma/dx)\,dx = 1`.
+
+    Parameters
+    ----------
+    x : array_like
+        Scaled electron energy, :math:`x=2E_e/m_\mu\in[0,1]`.
+
+    Returns
+    -------
+    ndarray or float
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> x = np.linspace(0, 1, 100001)
+    >>> round(float(np.trapezoid(michel_spectrum(x), x)), 4)
+    1.0
+    """
+    x = np.asarray(x, dtype=float)
+    return 2.0 * x**2 * (3.0 - 2.0 * x)
+
+
+def sample_michel_electron_energies(n, rng=None):
+    r"""Sample ``n`` scaled electron energies :math:`x=2E_e/m_\mu` from the Michel spectrum.
+
+    Rejection sampling against the shape's bound: :math:`x^2(3-2x)\le1`
+    on :math:`[0,1]` (attained at :math:`x=1`), so a uniform proposal on
+    :math:`[0,1]\times[0,1]` accepted below the (unnormalized) curve
+    :math:`x^2(3-2x)` reproduces :func:`michel_spectrum`.
+
+    Parameters
+    ----------
+    n : int
+        Number of samples.
+    rng : numpy.random.Generator, optional
+        Random number generator; a fresh default one is used if omitted.
+
+    Returns
+    -------
+    ndarray of shape (n,)
+
+    Examples
+    --------
+    >>> rng = np.random.default_rng(0)
+    >>> xs = sample_michel_electron_energies(20000, rng=rng)
+    >>> bool(0.68 < xs.mean() < 0.72)  # theoretical mean <x> = 7/10
+    True
+    """
+    rng = np.random.default_rng() if rng is None else rng
+    samples = np.empty(n)
+    filled = 0
+    while filled < n:
+        batch = max(2 * (n - filled), 16)
+        x_cand = rng.uniform(0.0, 1.0, size=batch)
+        y_cand = rng.uniform(0.0, 1.0, size=batch)
+        accepted = x_cand[y_cand <= x_cand**2 * (3.0 - 2.0 * x_cand)]
+        take = accepted[: n - filled]
+        samples[filled : filled + len(take)] = take
+        filled += len(take)
+    return samples
+
+
+def muon_decay_event(m_mu, rng=None):
+    r"""Sample one :math:`\mu^-\to e^-+\bar\nu_\mu+\nu_e` decay in the muon rest frame.
+
+    Toy-but-exact three-body kinematics built from two chained exact
+    two-body decays (reusing :func:`two_body_decay`, so energy-momentum
+    is conserved to machine precision at both vertices):
+
+    1. The electron's energy is drawn from the Michel spectrum (massless
+       electron approximation) via :func:`sample_michel_electron_energies`,
+       fixing the invariant mass of the recoiling neutrino pair through
+       :math:`m_{\nu\nu}^2=m_\mu^2-2m_\mu E_e` (exact for :math:`m_e=0`).
+       :func:`two_body_decay` then gives the electron and the
+       neutrino-pair "system" four-momenta, back to back in the muon
+       rest frame, with an isotropically sampled decay angle (the
+       standard unpolarized-muon assumption).
+    2. The neutrino-pair system is split into its two (massless)
+       neutrinos isotropically in *its own* rest frame via a second call
+       to :func:`two_body_decay`, then boosted back to the muon rest
+       frame with :func:`~physicskit.particle.kinematics.boost_generic`.
+
+    Both neutrino masses are set to zero -- an excellent approximation
+    given their sub-eV masses compared to :math:`m_\mu\sim100` MeV.
+
+    Parameters
+    ----------
+    m_mu : float
+        Muon mass (in whatever energy unit the caller uses consistently).
+    rng : numpy.random.Generator, optional
+        Random number generator; a fresh default one is used if omitted.
+
+    Returns
+    -------
+    p_e, p_numu_bar, p_nue : FourVector
+        The three decay products, in the muon rest frame.
+
+    Examples
+    --------
+    >>> from physicskit.particle.kinematics import invariant_mass
+    >>> rng = np.random.default_rng(1)
+    >>> p_e, p_numu_bar, p_nue = muon_decay_event(105.658, rng=rng)
+    >>> round(invariant_mass([p_e, p_numu_bar, p_nue]), 6)
+    105.658
+    """
+    rng = np.random.default_rng() if rng is None else rng
+    x = float(sample_michel_electron_energies(1, rng=rng)[0])
+    E_e = 0.5 * x * m_mu
+    m_nunu = float(np.sqrt(max(m_mu**2 - 2.0 * m_mu * E_e, 0.0)))
+    cos1, phi1 = rng.uniform(-1.0, 1.0), rng.uniform(0.0, 2.0 * np.pi)
+    p_e, p_nunu = two_body_decay(m_mu, 0.0, m_nunu, cos1, phi1)
+    cos2, phi2 = rng.uniform(-1.0, 1.0), rng.uniform(0.0, 2.0 * np.pi)
+    p_numu_bar_rest, p_nue_rest = two_body_decay(m_nunu, 0.0, 0.0, cos2, phi2)
+    beta_vec = p_nunu.p_vec / p_nunu.E
+    p_numu_bar = boost_generic(p_numu_bar_rest, beta_vec)
+    p_nue = boost_generic(p_nue_rest, beta_vec)
+    return p_e, p_numu_bar, p_nue

physicskit/particle/electroweak.py

@@ -0,0 +1,300 @@
+r"""Toy models of three electroweak/QED phenomena: spontaneous symmetry
+breaking, leading-order QED annihilation, and neutral-meson CP violation.
+
+Uses the same natural-unit convention (:math:`\hbar=c=1`) as
+:mod:`physicskit.particle.kinematics`.
+
+- :func:`higgs_potential`, :func:`higgs_vev`, :func:`higgs_field_rollover`
+  -- classical spontaneous symmetry breaking of a real scalar field in a
+  :math:`\phi^4` double-well potential (the same mechanism underlying
+  the Higgs field's nonzero vacuum expectation value), reduced to a
+  single spatial point (0+1 dimensional) for simplicity.
+- :func:`qed_dsigma_domega_mumu`, :func:`qed_total_cross_section_mumu` --
+  the leading-order (tree-level, single-photon-exchange) QED
+  differential and total cross sections for :math:`e^+e^-\to\mu^+\mu^-`.
+- :func:`meson_decay_rates_cp_eigenstate`, :func:`cp_asymmetry` -- a
+  Wigner-Weisskopf two-state-mixing toy model of neutral-meson
+  (:math:`K^0`-:math:`\bar K^0`-style) CP violation in the decay-rate
+  asymmetry to a common CP eigenstate final state.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.integrate import solve_ivp
+
+from physicskit.particle.scattering import ALPHA_FS
+
+__all__ = [
+    "higgs_potential",
+    "higgs_vev",
+    "higgs_field_rollover",
+    "qed_dsigma_domega_mumu",
+    "qed_total_cross_section_mumu",
+    "meson_decay_rates_cp_eigenstate",
+    "cp_asymmetry",
+]
+
+
+def higgs_potential(phi, a, b):
+    r"""The classical :math:`\phi^4` double-well potential, :math:`V(\phi)=-a\phi^2+b\phi^4`.
+
+    For :math:`a,b>0` this has an unstable extremum at :math:`\phi=0`
+    (the symmetric, "false vacuum" point) and two degenerate true minima
+    at :math:`\phi=\pm v`, :math:`v=\sqrt{a/(2b)}` -- the field must
+    "choose" one of them, spontaneously breaking the :math:`\phi\to-\phi`
+    symmetry. This is the same quartic potential that gives the Higgs
+    field its nonzero vacuum expectation value.
+
+    Parameters
+    ----------
+    phi : array_like
+        Field value.
+    a, b : float
+        Potential parameters, :math:`a,b>0`.
+
+    Returns
+    -------
+    ndarray or float
+
+    Examples
+    --------
+    >>> float(higgs_potential(0.0, a=1.0, b=1.0))
+    0.0
+    """
+    phi = np.asarray(phi, dtype=float)
+    return -a * phi**2 + b * phi**4
+
+
+def higgs_vev(a, b):
+    r"""The true-vacuum field value, :math:`v=\sqrt{a/(2b)}`, minimizing :func:`higgs_potential`.
+
+    Examples
+    --------
+    >>> round(higgs_vev(a=2.0, b=1.0), 6)
+    1.0
+    """
+    return float(np.sqrt(a / (2.0 * b)))
+
+
+def higgs_field_rollover(phi0, phidot0, a, b, t_eval, damping=0.0):
+    r"""Classically evolve a homogeneous scalar field rolling in :func:`higgs_potential`.
+
+    Integrates the (0+1 dimensional -- no spatial gradient/kink
+    structure, a single point standing in for a spatially uniform field
+    configuration) classical field equation
+
+    .. math::
+
+        \ddot\phi = -\frac{dV}{d\phi} - \gamma\dot\phi
+        = 2a\phi - 4b\phi^3 - \gamma\dot\phi
+
+    Started near the unstable symmetric point :math:`\phi\approx0` with
+    a tiny perturbation, the field is repelled from it and rolls down
+    into one of the two true vacua :math:`\phi=\pm v`
+    (:func:`higgs_vev`) -- whichever side the initial perturbation
+    pushes it toward, a toy realization of spontaneous symmetry
+    breaking. A small damping :math:`\gamma>0` (representing energy
+    radiated into other field modes, not modeled explicitly) lets the
+    field settle into the chosen vacuum instead of oscillating in it
+    forever.
+
+    Parameters
+    ----------
+    phi0, phidot0 : float
+        Initial field value and velocity.
+    a, b : float
+        Potential parameters, see :func:`higgs_potential`.
+    t_eval : array_like
+        Times at which to report the solution.
+    damping : float, default=0.0
+        Damping coefficient :math:`\gamma\ge0`.
+
+    Returns
+    -------
+    phi, phidot : ndarray
+        Field value and velocity at each time in ``t_eval``.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> t = np.linspace(0, 60, 600)
+    >>> phi, phidot = higgs_field_rollover(1e-3, 0.0, a=1.0, b=1.0, t_eval=t, damping=0.08)
+    >>> v = higgs_vev(1.0, 1.0)
+    >>> bool(abs(abs(phi[-1]) - v) < 0.05)
+    True
+    """
+    t_eval = np.asarray(t_eval, dtype=float)
+
+    def rhs(t, y):
+        phi, phidot = y
+        return [phidot, 2.0 * a * phi - 4.0 * b * phi**3 - damping * phidot]
+
+    sol = solve_ivp(rhs, (t_eval[0], t_eval[-1]), [phi0, phidot0], t_eval=t_eval, rtol=1e-9, atol=1e-12)
+    return sol.y[0], sol.y[1]
+
+
+def qed_dsigma_domega_mumu(cos_theta, sqrt_s, alpha=ALPHA_FS):
+    r"""Leading-order QED differential cross section for :math:`e^+e^-\to\mu^+\mu^-`.
+
+    .. math::
+
+        \frac{d\sigma}{d\Omega} = \frac{\alpha^2}{4s}\left(1+\cos^2\theta\right)
+
+    the standard tree-level, single-photon-exchange, unpolarized result
+    in the ultrarelativistic (massless-fermion) limit -- e.g. Peskin &
+    Schroeder, *An Introduction to Quantum Field Theory*, eq. (5.15); or
+    Halzen & Martin, *Quarks and Leptons*, eq. (6.23). :math:`\theta` is
+    the muon's polar angle relative to the beam in the center-of-mass
+    frame, and :math:`s=(\sqrt s)^2` is the Mandelstam invariant (see
+    :func:`physicskit.particle.scattering.mandelstam_s`).
+
+    **Simplification**: electron and muon masses are neglected (valid
+    for :math:`\sqrt s\gg2m_\mu\approx0.2` GeV); higher-order QED
+    corrections and any :math:`Z`-boson contribution (relevant near and
+    above the :math:`Z` pole, :math:`\sqrt s\sim91` GeV) are not included.
+
+    Parameters
+    ----------
+    cos_theta : array_like
+        Cosine of the muon's center-of-mass polar angle.
+    sqrt_s : float
+        Center-of-mass energy.
+    alpha : float, default=ALPHA_FS
+        Fine-structure constant.
+
+    Returns
+    -------
+    ndarray or float
+
+    Examples
+    --------
+    >>> round(float(qed_dsigma_domega_mumu(0.0, sqrt_s=10.0) / qed_dsigma_domega_mumu(1.0, sqrt_s=10.0)), 6)
+    0.5
+    """
+    cos_theta = np.asarray(cos_theta, dtype=float)
+    s = sqrt_s**2
+    return (alpha**2 / (4.0 * s)) * (1.0 + cos_theta**2)
+
+
+def qed_total_cross_section_mumu(sqrt_s, alpha=ALPHA_FS):
+    r"""Total leading-order QED cross section for :math:`e^+e^-\to\mu^+\mu^-`.
+
+    .. math::
+
+        \sigma = \frac{4\pi\alpha^2}{3s}
+
+    obtained by integrating :func:`qed_dsigma_domega_mumu` over the full
+    solid angle; the same simplifications apply (massless fermions, no
+    :math:`Z` contribution).
+
+    Parameters
+    ----------
+    sqrt_s : float
+        Center-of-mass energy.
+    alpha : float, default=ALPHA_FS
+        Fine-structure constant.
+
+    Returns
+    -------
+    float
+
+    Examples
+    --------
+    >>> round(qed_total_cross_section_mumu(10.0), 10) == round(4 * np.pi * ALPHA_FS**2 / (3 * 100.0), 10)
+    True
+    """
+    s = sqrt_s**2
+    return 4.0 * np.pi * alpha**2 / (3.0 * s)
+
+
+def meson_decay_rates_cp_eigenstate(t, delta_m, gamma_s, gamma_l, epsilon):
+    r"""Time-dependent :math:`P^0,\bar P^0\to f_{CP}` decay rates, Wigner-Weisskopf toy model.
+
+    A neutral meson :math:`P^0` (modeled on the :math:`K^0`-:math:`\bar
+    K^0` system) mixes through the effective non-Hermitian Hamiltonian
+    :math:`H=M-i\Gamma/2`; its mass eigenstates are the short/long-lived
+    combinations :math:`P_{S,L}\approx P^0\pm\bar P^0` (up to the small
+    CP-violating admixture parametrized by the complex parameter
+    :math:`\varepsilon`, :math:`|\varepsilon|\ll1`). Decaying to a common
+    CP eigenstate final state :math:`f` (e.g. :math:`\pi^+\pi^-`), the
+    two flavor-tagged rates interfere as
+
+    .. math::
+
+        \Gamma(P^0(t)\to f) &= e^{-\Gamma_S t} + |\varepsilon|^2e^{-\Gamma_L t}
+        + 2|\varepsilon|e^{-\Gamma t}\cos(\Delta m\,t-\phi_\varepsilon) \\
+        \Gamma(\bar P^0(t)\to f) &= e^{-\Gamma_S t} + |\varepsilon|^2e^{-\Gamma_L t}
+        - 2|\varepsilon|e^{-\Gamma t}\cos(\Delta m\,t-\phi_\varepsilon)
+
+    with :math:`\Gamma=(\Gamma_S+\Gamma_L)/2`; this is the standard
+    interference pattern used to measure :math:`\Delta m` and the
+    :math:`K_S` lifetime from :math:`K^0/\bar K^0\to\pi\pi` decay-rate
+    oscillations (see the Particle Data Group's "CP violation in
+    :math:`K_L` decays" review, or Griffiths, *Introduction to Elementary
+    Particles*, Ch. 8).
+
+    Parameters
+    ----------
+    t : array_like
+        Proper time since production (tagged as a pure :math:`P^0` or
+        :math:`\bar P^0` flavor eigenstate at :math:`t=0`).
+    delta_m : float
+        Mass splitting between the two mass eigenstates, :math:`\Delta m=m_L-m_S`.
+    gamma_s, gamma_l : float
+        Decay widths of the short- and long-lived mass eigenstates.
+    epsilon : complex
+        CP-violation parameter, :math:`|\varepsilon|\ll1`.
+
+    Returns
+    -------
+    gamma_meson, gamma_mesonbar : ndarray
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> t = np.linspace(0, 5, 6)
+    >>> g, gbar = meson_decay_rates_cp_eigenstate(t, delta_m=1.0, gamma_s=5.0, gamma_l=0.5, epsilon=0.0)
+    >>> np.allclose(g, gbar)
+    True
+    """
+    t = np.asarray(t, dtype=float)
+    eps = complex(epsilon)
+    eps_abs, phi_eps = abs(eps), np.angle(eps)
+    gamma = 0.5 * (gamma_s + gamma_l)
+    common = np.exp(-gamma_s * t) + eps_abs**2 * np.exp(-gamma_l * t)
+    osc = 2.0 * eps_abs * np.exp(-gamma * t) * np.cos(delta_m * t - phi_eps)
+    return common + osc, common - osc
+
+
+def cp_asymmetry(t, delta_m, gamma_s, gamma_l, epsilon):
+    r"""Decay-rate CP asymmetry :math:`A(t)`, from :func:`meson_decay_rates_cp_eigenstate`.
+
+    .. math::
+
+        A(t) = \frac{\Gamma(\bar P^0(t)\to f) - \Gamma(P^0(t)\to f)}
+        {\Gamma(\bar P^0(t)\to f) + \Gamma(P^0(t)\to f)}
+
+    which oscillates at frequency :math:`\Delta m` inside a decaying
+    envelope, vanishing identically for :math:`\varepsilon=0` (no CP
+    violation).
+
+    Parameters
+    ----------
+    t, delta_m, gamma_s, gamma_l, epsilon
+        See :func:`meson_decay_rates_cp_eigenstate`.
+
+    Returns
+    -------
+    ndarray or float
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> t = np.linspace(0, 5, 6)
+    >>> A = cp_asymmetry(t, delta_m=1.0, gamma_s=5.0, gamma_l=0.5, epsilon=0.0)
+    >>> np.allclose(A, 0.0)
+    True
+    """
+    gamma_meson, gamma_mesonbar = meson_decay_rates_cp_eigenstate(t, delta_m, gamma_s, gamma_l, epsilon)
+    return (gamma_mesonbar - gamma_meson) / (gamma_mesonbar + gamma_meson)