physicskit 0.1.0__py3-none-any.whl

physicskit/particle/visualizers/static.py

@@ -0,0 +1,101 @@
+"""Static plotting helpers: decay chain populations and differential cross sections.
+
+Matplotlib is used throughout. Every function returns its figure object
+rather than calling ``show()``, so it composes cleanly into larger
+figures or headless pipelines.
+"""
+
+from __future__ import annotations
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+__all__ = ["plot_decay_chain", "plot_differential_cross_section"]
+
+
+def plot_decay_chain(t, populations, labels=None, ax=None):
+    """Plot each species' population over time in a radioactive decay chain.
+
+    Parameters
+    ----------
+    t : ndarray of shape (n_t,)
+        Times.
+    populations : ndarray of shape (n_species, n_t)
+        Population of each species over time, e.g. from
+        :func:`physicskit.particle.decays.bateman_decay_chain`.
+    labels : sequence of str, optional
+        Label for each species; defaults to ``"species 1"``, ``"species 2"``, ...
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure is created if omitted.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from physicskit.particle.decays import bateman_decay_chain
+    >>> t = np.linspace(0, 10, 50)
+    >>> N = bateman_decay_chain(1000.0, [0.5, 0.2], t)
+    >>> fig, ax = plot_decay_chain(t, N, labels=["Parent", "Daughter"])
+    >>> isinstance(fig, plt.Figure)
+    True
+    """
+    populations = np.asarray(populations)
+    if labels is None:
+        labels = [f"species {i + 1}" for i in range(populations.shape[0])]
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.figure
+    for row, label in zip(populations, labels, strict=True):
+        ax.plot(t, row, label=label)
+    ax.set_xlabel("t")
+    ax.set_ylabel("population")
+    ax.legend()
+    return fig, ax
+
+
+def plot_differential_cross_section(theta, dsigma_domega, ax=None, log_scale=True):
+    """Plot a differential cross section :math:`d\\sigma/d\\Omega` vs. scattering angle.
+
+    Parameters
+    ----------
+    theta : ndarray of shape (n,)
+        Scattering angles (radians).
+    dsigma_domega : ndarray of shape (n,)
+        Differential cross section values, e.g. from
+        :func:`physicskit.particle.scattering.rutherford_dsigma_domega`.
+    ax : matplotlib.axes.Axes, optional
+        Axes to draw into; a new figure is created if omitted.
+    log_scale : bool, default=True
+        Plot the cross section on a log y-axis, appropriate for the
+        Rutherford formula's steep small-angle divergence.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+    ax : matplotlib.axes.Axes
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from physicskit.particle.scattering import rutherford_dsigma_domega
+    >>> theta = np.linspace(0.1, np.pi - 0.1, 50)
+    >>> vals = rutherford_dsigma_domega(theta, Z1=2, Z2=79, E_kin=5.0)
+    >>> fig, ax = plot_differential_cross_section(theta, vals)
+    >>> isinstance(fig, plt.Figure)
+    True
+    """
+    if ax is None:
+        fig, ax = plt.subplots()
+    else:
+        fig = ax.figure
+    ax.plot(theta, dsigma_domega)
+    if log_scale:
+        ax.set_yscale("log")
+    ax.set_xlabel(r"$\theta$")
+    ax.set_ylabel(r"$d\sigma/d\Omega$")
+    return fig, ax

physicskit/plasma/__init__.py

@@ -0,0 +1,176 @@
+"""Computational plasma physics: single-particle motion, MHD, waves, and kinetic theory.
+
+Typical usage::
+
+    import physicskit as pk
+    import numpy as np
+
+    # Cyclotron gyration of a proton in a 1 T field:
+    r_hist, v_hist = pk.plasma.boris_integrate(
+        np.zeros(3), np.array([1e5, 0.0, 0.0]),
+        pk.plasma.QE, pk.plasma.MP,
+        np.zeros(3), np.array([0.0, 0.0, 1.0]),
+        dt=1e-10, steps=1000,
+    )
+"""
+
+from .acceleration import simulate_wakefield_acceleration, wakefield_e_field
+from .instabilities import (
+    reconnection_field_from_flux,
+    reconnection_harris_ic,
+    reconnection_inflow_velocity,
+    simulate_reconnection,
+    simulate_weibel_filamentation,
+    weibel_fastest_growing_mode,
+    weibel_growth_rate,
+)
+from .kinetic import (
+    deposit_number_density,
+    interpolate_field,
+    landau_damping_ic,
+    landau_damping_rate,
+    langmuir_wave_ic,
+    maxwellian_velocities,
+    pic_simulate,
+    pic_step,
+    solve_poisson_1d,
+    two_stream_ic,
+)
+from .mhd import (
+    MU0,
+    alfven_speed,
+    grad_shafranov_rhs_solovev,
+    lundquist_number,
+    magnetosonic_speeds,
+    petschek_rate,
+    resistive_diffusion_time,
+    safety_factor_large_aspect_ratio,
+    solovev_particular_solution,
+    solve_grad_shafranov,
+    sound_speed,
+    sweet_parker_layer_width,
+    sweet_parker_rate,
+)
+from .single_particle import (
+    ME,
+    MP,
+    QE,
+    boris_integrate,
+    boris_push,
+    curvature_drift,
+    cyclotron_frequency,
+    exb_drift,
+    grad_b_drift,
+    larmor_radius,
+    magnetic_mirror_bounce,
+    magnetic_moment,
+    mirror_force,
+)
+from .turbulence import drift_wave_noise_ic, hasegawa_mima_rhs, simulate_hasegawa_mima
+from .visualizers import (
+    animate_alfven_wave,
+    animate_drift_wave_turbulence,
+    animate_ion_acoustic_soliton,
+    animate_langmuir_wave,
+    animate_reconnection,
+    animate_two_stream_phase_space,
+    animate_wakefield_acceleration,
+    animate_weibel_filamentation,
+    plot_cma_diagram,
+    plot_drift_trajectory,
+    plot_field_energy_history,
+    plot_flux_surfaces,
+    plot_particle_orbit_3d,
+    plot_phase_space,
+    plot_phase_space_interactive,
+    plot_q_profile,
+)
+from .waves import (
+    alfven_wave_pulse_ic,
+    cma_coordinates,
+    cold_plasma_dispersion,
+    ion_acoustic_soliton_evolve,
+    ion_acoustic_soliton_profile,
+    plasma_frequency,
+    rl_parameters,
+    simulate_alfven_wave,
+    stix_parameters,
+    whistler_dispersion,
+)
+
+__all__ = [
+    "QE",
+    "ME",
+    "MP",
+    "MU0",
+    "cyclotron_frequency",
+    "larmor_radius",
+    "magnetic_moment",
+    "boris_push",
+    "boris_integrate",
+    "exb_drift",
+    "grad_b_drift",
+    "curvature_drift",
+    "mirror_force",
+    "magnetic_mirror_bounce",
+    "alfven_speed",
+    "sound_speed",
+    "magnetosonic_speeds",
+    "solovev_particular_solution",
+    "grad_shafranov_rhs_solovev",
+    "solve_grad_shafranov",
+    "safety_factor_large_aspect_ratio",
+    "lundquist_number",
+    "resistive_diffusion_time",
+    "sweet_parker_rate",
+    "sweet_parker_layer_width",
+    "petschek_rate",
+    "plasma_frequency",
+    "stix_parameters",
+    "rl_parameters",
+    "cold_plasma_dispersion",
+    "whistler_dispersion",
+    "cma_coordinates",
+    "maxwellian_velocities",
+    "landau_damping_ic",
+    "langmuir_wave_ic",
+    "two_stream_ic",
+    "deposit_number_density",
+    "interpolate_field",
+    "solve_poisson_1d",
+    "pic_step",
+    "pic_simulate",
+    "landau_damping_rate",
+    "reconnection_harris_ic",
+    "reconnection_inflow_velocity",
+    "reconnection_field_from_flux",
+    "simulate_reconnection",
+    "weibel_growth_rate",
+    "weibel_fastest_growing_mode",
+    "simulate_weibel_filamentation",
+    "ion_acoustic_soliton_profile",
+    "ion_acoustic_soliton_evolve",
+    "alfven_wave_pulse_ic",
+    "simulate_alfven_wave",
+    "drift_wave_noise_ic",
+    "hasegawa_mima_rhs",
+    "simulate_hasegawa_mima",
+    "wakefield_e_field",
+    "simulate_wakefield_acceleration",
+    "plot_particle_orbit_3d",
+    "plot_drift_trajectory",
+    "plot_flux_surfaces",
+    "plot_q_profile",
+    "plot_phase_space",
+    "plot_field_energy_history",
+    "plot_cma_diagram",
+    "plot_phase_space_interactive",
+    "animate_reconnection",
+    "animate_weibel_filamentation",
+    "animate_two_stream_phase_space",
+    "animate_langmuir_wave",
+    "animate_ion_acoustic_soliton",
+    "animate_drift_wave_turbulence",
+    "animate_alfven_wave",
+    "animate_wakefield_acceleration",
+]

physicskit/plasma/acceleration.py

@@ -0,0 +1,152 @@
+"""Plasma-wakefield-style particle acceleration: a test charge surfing a prescribed traveling wave.
+
+A full plasma-wakefield-accelerator simulation would derive the
+accelerating field self-consistently from a driver beam or laser pulse
+depositing momentum into the plasma via PIC (as :mod:`physicskit.plasma.kinetic`
+does for electrostatic waves, just relativistically and in the wake of a
+driver). That is a large undertaking; the standard pedagogical
+simplification -- used throughout introductory wakefield-acceleration
+treatments -- is instead to *prescribe* the wakefield as a traveling
+longitudinal electric-field wave :math:`E_z(x,t)=E_0\\cos[k(x-v_{ph}t)]`
+(a rigid wake moving at the driver's phase velocity :math:`v_{ph}`, not fed
+back on by the accelerated particle) and inject a single test charge into
+it with :func:`physicskit.plasma.single_particle.boris_push` (setting
+:math:`\\mathbf{B}=0`, since this toy model has no transverse focusing
+field). A particle riding near the wave's phase velocity feels a
+sign-definite accelerating field for as long as it stays within one
+quarter-wavelength of the field's zero-crossing (the "accelerating bucket"),
+gaining energy at the expense of the (externally prescribed, infinite-energy-
+reservoir) wave, exactly the qualitative picture of plasma wakefield
+acceleration without any of its self-consistent field generation.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from physicskit.plasma.single_particle import boris_push
+
+__all__ = [
+    "wakefield_e_field",
+    "simulate_wakefield_acceleration",
+]
+
+
+def wakefield_e_field(x: np.ndarray, t: float, E0: float, k: float, v_phase: float) -> np.ndarray:
+    """Prescribed traveling-wave longitudinal wakefield :math:`E_z(x,t) = E_0\\cos[k(x - v_{ph}t)]`.
+
+    A rigid sinusoidal accelerating structure moving at the fixed phase
+    velocity `v_phase`, standing in for the self-consistent plasma
+    wakefield a real driver beam or laser wake would generate (see the
+    module docstring for the simplification this represents).
+
+    Parameters
+    ----------
+    x : ndarray or float
+        Position(s) at which to evaluate the field.
+    t : float
+        Time.
+    E0 : float
+        Peak field amplitude.
+    k : float
+        Wakefield wavenumber.
+    v_phase : float
+        Phase velocity of the traveling wave.
+
+    Returns
+    -------
+    ndarray or float
+        :math:`E_z(x, t)`, same shape as `x`.
+
+    See Also
+    --------
+    simulate_wakefield_acceleration : Injects a test particle into this field.
+
+    Examples
+    --------
+    >>> round(float(wakefield_e_field(0.0, t=0.0, E0=1.0, k=1.0, v_phase=1.0)), 6)
+    1.0
+    """
+    return E0 * np.cos(k * (x - v_phase * t))
+
+
+def simulate_wakefield_acceleration(x0: float, v0: float, q: float, m: float, E0: float, k: float, v_phase: float, dt: float, steps: int) -> dict:
+    """Integrate a test charge's 1D motion in the prescribed traveling wakefield, with the Boris pusher.
+
+    Calls :func:`physicskit.plasma.single_particle.boris_push` once per
+    step with :math:`\\mathbf{B}=0` and :math:`\\mathbf{E}=(E_z(x,t),0,0)`
+    re-evaluated at the particle's *current* position and time each
+    step -- unlike :func:`physicskit.plasma.single_particle.boris_integrate`,
+    which assumes a field uniform in space and time, this wakefield varies
+    in both, so the field must be recomputed every step rather than
+    baked into a single Numba-compiled loop. The pusher itself remains
+    exactly energy-conserving in a pure magnetic field and exact-leapfrog
+    in a pure electric field; it is otherwise an ordinary (non-relativistic)
+    classical integrator, so results should be read qualitatively once
+    the particle's speed approaches a meaningful fraction of `v_phase`
+    (real wakefield acceleration is an intrinsically relativistic problem).
+
+    Parameters
+    ----------
+    x0 : float
+        Initial position along the wave.
+    v0 : float
+        Initial longitudinal velocity.
+    q : float
+        Particle charge.
+    m : float
+        Particle mass.
+    E0 : float
+        Peak wakefield amplitude, from :func:`wakefield_e_field`.
+    k : float
+        Wakefield wavenumber.
+    v_phase : float
+        Wakefield phase velocity.
+    dt : float
+        Time step.
+    steps : int
+        Number of steps to advance.
+
+    Returns
+    -------
+    dict
+        ``{"t": ndarray shape (steps+1,), "x": position history, "v":
+        longitudinal velocity history, "kinetic_energy": :math:`\\tfrac12 m v^2`
+        history}``.
+
+    See Also
+    --------
+    wakefield_e_field : The prescribed field this particle rides.
+
+    Examples
+    --------
+    A particle launched exactly at the wave's phase velocity, sitting on
+    the accelerating part of the field, gains kinetic energy:
+
+    >>> import numpy as np
+    >>> result = simulate_wakefield_acceleration(
+    ...     x0=0.0, v0=0.9, q=1.0, m=1.0, E0=0.05, k=1.0, v_phase=1.0, dt=0.01, steps=2000
+    ... )
+    >>> bool(result["kinetic_energy"][-1] > result["kinetic_energy"][0])
+    True
+    """
+    pos = np.array([x0, 0.0, 0.0])
+    vel = np.array([v0, 0.0, 0.0])
+    B = np.zeros(3)
+
+    n = steps + 1
+    x_hist = np.empty(n)
+    v_hist = np.empty(n)
+    x_hist[0], v_hist[0] = pos[0], vel[0]
+
+    t = 0.0
+    for i in range(steps):
+        Ez = wakefield_e_field(pos[0], t, E0, k, v_phase)
+        E = np.array([Ez, 0.0, 0.0])
+        pos, vel = boris_push(pos, vel, q, m, E, B, dt)
+        t += dt
+        x_hist[i + 1], v_hist[i + 1] = pos[0], vel[0]
+
+    t_hist = np.arange(n) * dt
+    kinetic_energy = 0.5 * m * v_hist**2
+    return {"t": t_hist, "x": x_hist, "v": v_hist, "kinetic_energy": kinetic_energy}