Input/output helpers

Bunch initialization helpers for the core Liénard–Wiechert integrator.

input_output.bunch_initialization.ELEMENTARY_CHARGE_GU = 4.803204712570263e-10

Elementary charge in statcoulombs, retained for cgs analysis compatibility.

Do not use this value directly in particle states. The integrator evolves charges in native solver units, so state dictionaries must use ELEMENTARY_CHARGE.

class input_output.bunch_initialization.BunchRequest(kinetic_energy_mev: float, mass_amu: float, charge_sign: float, position_z: float = 0.0, particle_count: int = 1, transverse_radius: float = 0.0, transverse_momentum: float = 0.0, transverse_offset_x: float = 0.0, transverse_offset_y: float = 0.0, transverse_spread: float = 0.0, transverse_geometry: str = 'square')[source]

Bases: object

Input parameters for create_bunch_from_energy().

kinetic_energy_mev: float
mass_amu: float
charge_sign: float
position_z: float = 0.0
particle_count: int = 1
transverse_radius: float = 0.0
transverse_momentum: float = 0.0
transverse_offset_x: float = 0.0
transverse_offset_y: float = 0.0
transverse_spread: float = 0.0
transverse_geometry: str = 'square'
__init__(kinetic_energy_mev: float, mass_amu: float, charge_sign: float, position_z: float = 0.0, particle_count: int = 1, transverse_radius: float = 0.0, transverse_momentum: float = 0.0, transverse_offset_x: float = 0.0, transverse_offset_y: float = 0.0, transverse_spread: float = 0.0, transverse_geometry: str = 'square') → None
input_output.bunch_initialization.create_bunch_from_energy(*, kinetic_energy_mev: float, mass_amu: float, charge_sign: float, position_z: float = 0.0, particle_count: int = 1, transverse_radius: float = 0.0, transverse_momentum: float = 0.0, transverse_offset_x: float = 0.0, transverse_offset_y: float = 0.0, transverse_spread: float = 0.0, transverse_geometry: str = 'square', longitudinal_spread: float = 0.0) → Tuple[Dict[str, ndarray], float][source]

Generate a particle state dictionary from kinetic energy inputs.

Parameters:

  • kinetic_energy_mev (float) – Kinetic energy in MeV

  • mass_amu (float) – Particle mass in atomic mass units

  • charge_sign (float) – Charge sign (+1 or -1)

  • position_z (float, optional) – Starting z position in mm (default: 0.0)

  • particle_count (int, optional) – Number of particles in bunch (default: 1)

  • transverse_radius (float, optional) – DEPRECATED: Use transverse_offset_x/y instead. Single transverse offset in mm (default: 0.0)

  • transverse_momentum (float, optional) – Transverse momentum spread (uniform ±transverse_momentum) in amu*mm/ns (default: 0.0)

  • transverse_offset_x (float, optional) – Center x-position of bunch in mm (default: 0.0, on-axis)

  • transverse_offset_y (float, optional) – Center y-position of bunch in mm (default: 0.0, on-axis)

  • transverse_spread (float, optional) – Size parameter for the selected transverse geometry in mm (default: 0.0). For square geometry this is the uniform half-width, for gaussian geometry this is sigma, and for ring geometry this is radius.

  • transverse_geometry (str, optional) – Transverse layout: “square”/”uniform_square”, “point”, “gaussian”, or “ring”/”circle” (default: “square”).

  • longitudinal_spread (float, optional) – Longitudinal Gaussian sigma in mm around position_z. The default 0.0 keeps all particles at position_z.

Returns:

  • state (ParticleState) – Dictionary with particle state arrays

  • rest_energy_mev (float) – Rest energy in MeV

Notes

  • If transverse_spread > 0, particles are uniformly distributed in a square: x ∈ [transverse_offset_x - transverse_spread, transverse_offset_x + transverse_spread] y ∈ [transverse_offset_y - transverse_spread, transverse_offset_y + transverse_spread]

  • If transverse_spread = 0, all particles are placed at (transverse_offset_x, transverse_offset_y)

  • transverse_radius is deprecated but maintained for backward compatibility

input_output.bunch_initialization.create_bunch_from_params(*, starting_distance: float, transv_mom: float, starting_Pz: float, stripped_ions: float, m_particle: float, transv_dist: float = 0.0, long_dist: float = 0.0, transv_offset_x: float = 0.0, transv_offset_y: float = 0.0, pcount: int = 1, charge_sign: float = 1.0, seed: int | None = None, transverse_geometry: str = 'square') → Tuple[ParticleState, float][source]

Generate particle state from historical parameter names.

This function is the maintained particle-bunch initializer for configs that still use the original parameter naming scheme, with support for transverse offset.

Parameters:

  • starting_distance (float) – Starting z-position in mm

  • transv_mom (float) – Transverse momentum spread (uniform ±transv_mom) in amu*mm/ns

  • starting_Pz (float) – Initial longitudinal momentum per unit mass (specific momentum) in mm/ns

  • stripped_ions (float) – Number of elementary charges

  • m_particle (float) – Particle mass in amu

  • transv_dist (float, optional) – Half-width of transverse distribution in mm (default: 0.0)

  • transv_offset_x (float, optional) – Center x-position of bunch in mm (default: 0.0)

  • transv_offset_y (float, optional) – Center y-position of bunch in mm (default: 0.0)

  • pcount (int, optional) – Number of particles (default: 1)

  • charge_sign (float, optional) – Charge sign (+1 or -1, default: 1.0)

  • seed (int, optional) – Random seed for reproducibility (default: None)

  • transverse_geometry (str, optional) – Transverse layout: “square”/”uniform_square”, “point”, “gaussian”, or “ring”/”circle” (default: “square”). For ring layout, transv_dist is interpreted as ring radius.

Returns:

  • state (ParticleState) – Particle state dictionary

  • rest_energy_mev (float) – Rest energy in MeV