Core integrator

Compatibility facade exposing the retarded integrator public API.

The legacy codebase imported functionality directly from core.trajectory_integrator. The implementation has since been modularised into smaller, focused modules. This wrapper re-exports the public symbols to maintain import compatibility while also providing a light-weight class based API used by historical notebooks and regression tests.

class core.trajectory_integrator.IntegratorConfig(steps: int, time_step: float, wall_position: float, aperture_radius: float, simulation_type: SimulationType, bunch_mean: float = 0.0, cavity_spacing: float = 0.0, z_cutoff: float = 0.0)[source]

Bases: object

Structured configuration for core.integrator.run_integrator().

steps

Total number of integration iterations to perform.

Type:

int

time_step

Temporal spacing between successive states (h in the literature).

Type:

float

wall_position

Reference position of the conducting wall in millimetres.

Type:

float

aperture_radius

Radius of the conducting aperture in millimetres.

Type:

float

simulation_type

Boundary condition / interaction model, expressed as SimulationType.

Type:

core.types.SimulationType

bunch_mean

Optional mean bunch separation used by legacy notebooks. Not every integration path consumes it, but the value is retained for API compatibility.

Type:

float

cavity_spacing

Distance between cavities used by the switching-wall configuration.

Type:

float

z_cutoff

Longitudinal position at which the switching-wall stops mirroring charges. Defaults to 0 which effectively disables the cutoff.

Type:

float

__init__(steps: int, time_step: float, wall_position: float, aperture_radius: float, simulation_type: SimulationType, bunch_mean: float = 0.0, cavity_spacing: float = 0.0, z_cutoff: float = 0.0) → None
class core.trajectory_integrator.SimulationType(value)[source]

Bases: IntEnum

Supported simulation modes (mirrors the legacy integer flags).

The enum inherits from int so that existing code using literal values (0, 1, 2) continues to work. When writing new code, prefer the descriptive enum members for readability.

CONDUCTING_WALL = 0
SWITCHING_WALL = 1
BUNCH_TO_BUNCH = 2
core.trajectory_integrator.chrono_match_indices(trajectory: List[Dict[str, ndarray]], trajectory_ext: List[Dict[str, ndarray]], index_traj: int, index_part: int) → ndarray[source]

Find retarded indices for a particle using chrono-matching.

The solver needs to know which historical states of trajectory_ext influence each particle of trajectory. Retardation is approximated by walking backwards in time until the causal signal arrives, matching the behaviour of the benchmarked legacy routine.

core.trajectory_integrator.compute_instantaneous_distance(vector: Dict[str, ndarray], vector_ext: Dict[str, ndarray], index: int) → Dict[str, ndarray][source]

Compute Euclidean distance and direction cosines for a particle pair.

Parameters:

  • vector – Reference particle state (typically the bunch being updated).

  • vector_ext – External particle state sampled at the same trajectory index.

  • index – Index of the particle within vector to evaluate against the entire vector_ext bunch.

core.trajectory_integrator.compute_retarded_distance(trajectory: List[Dict[str, ndarray]], trajectory_ext: List[Dict[str, ndarray]], index_traj: int, index_part: int, indices_ret: Iterable[int]) → Dict[str, ndarray][source]

Compute retarded distance quantities between two trajectories.

The input indices_ret should already be chrono-matched; this function simply evaluates the geometric terms for each matched particle.

core.trajectory_integrator.generate_conducting_image(vector: Dict[str, ndarray], wall_z: float, aperture_radius: float) → Dict[str, ndarray][source]

Generate mirror charges for a conducting wall boundary.

Parameters:

  • vector – Particle bunch used to generate the mirror image.

  • wall_z – Location of the conducting wall in the simulation coordinate system.

  • aperture_radius – Radius of the circular aperture carved into the wall.

core.trajectory_integrator.generate_switching_image(vector: Dict[str, ndarray], wall_z: float, aperture_radius: float, cut_z: float) → Dict[str, ndarray][source]

Generate mirror charges for a switching wall boundary.

The switching wall behaves like a conductor until particles pass the longitudinal cut_z threshold, after which the mirror image is removed to emulate an opening absorber.

core.trajectory_integrator.retarded_equations_of_motion(h: float, trajectory: List[Dict[str, ndarray]], trajectory_ext: List[Dict[str, ndarray]], index_traj: int, aperture_radius: float, sim_type: SimulationType) → Dict[str, ndarray][source]

Core equations of motion mirroring the validated legacy implementation.

Parameters:

  • h – Time step between trajectory samples.

  • trajectory – Mutable view over the rider bunch history.

  • trajectory_ext – History of the external bunch (driver, image or opposing bunch).

  • index_traj – Index of the current time step within trajectory.

  • aperture_radius – Aperture radius supplied to the image generators.

  • sim_type – Simulation boundary type encoded as SimulationType.

Returns:

Updated particle state for the next time step.

Return type:

ParticleState

core.trajectory_integrator.retarded_integrator(steps: int, h_step: float, wall_z: float, aperture_radius: float, sim_type: SimulationType, init_rider: Dict[str, ndarray], init_driver: Dict[str, ndarray] | None, mean: float, cav_spacing: float, z_cutoff: float, self_consistency: SelfConsistencyConfig | None = None) → Tuple[List[Dict[str, ndarray]], List[Dict[str, ndarray]]][source]

Run the retarded-field integrator for rider and driver trajectories.

Parameters:

  • steps – Total number of integration updates to compute.

  • h_step – Temporal step between states (Δτ in the covariant formulation).

  • wall_z – Conducting wall location for boundary-condition simulations.

  • aperture_radius – Aperture radius used by the wall/image generators.

  • sim_type – Boundaries and interaction type encoded as SimulationType.

  • init_rider – Initial state of the primary bunch.

  • init_driver – Optional initial state of the opposing bunch (for BUNCH_TO_BUNCH).

  • mean – Historical bunch separation parameter retained for compatibility.

  • cav_spacing – Longitudinal spacing between cavities when using switching walls.

  • z_cutoff – Threshold beyond which the switching wall no longer mirrors charges.

  • self_consistency – Optional SelfConsistencyConfig to iterate each step until the Lorentz factor converges.

Returns:

Two trajectories: the rider (primary bunch) and the driver (image or opposing bunch), each represented as a list of particle states.

Return type:

tuple[Trajectory, Trajectory]

core.trajectory_integrator.run_integrator(config: IntegratorConfig, init_rider: Dict[str, ndarray], init_driver: Dict[str, ndarray] | None) → Tuple[List[Dict[str, ndarray]], List[Dict[str, ndarray]]][source]

Convenience wrapper using IntegratorConfig.

All parameters are supplied via config which mirrors the keyword arguments accepted by retarded_integrator().

class core.trajectory_integrator.LienardWiechertIntegrator(config: IntegratorConfig | None = None)[source]

Bases: object

Compatibility wrapper mimicking the legacy integrator facade.

The historic API exposed a mutable class with helper methods that several notebooks and regression tests relied upon. The present codebase is function-oriented, but a class wrapper keeps downstream integrations working without modification.

__init__(config: IntegratorConfig | None = None) → None[source]
equations_of_motion_static_internal(h_step: float, state: Dict[str, ndarray], _index: int) → Dict[str, ndarray][source]

Propagate particles forward assuming a field-free drift.

This mirrors the legacy helper used for static warm-up steps: particles drift according to their current velocity while conjugate momentum and Lorentz factor remain constant.

integrate_retarded_fields(static_steps: int, ret_steps: int, h_step: float, wall_Z: float, apt_R: float, sim_type: SimulationType | int, init_rider: ParticleState, init_driver: ParticleState | None, bunch_dist: float, z_cutoff: float, *, extra_config: MutableMapping[str, Any] | None = None) → tuple[Trajectory, Trajectory][source]

Execute retarded-field integration using the modern core runner.

Parameters mirror the legacy signature but are forwarded to core.integrator.retarded_integrator(). static_steps is preserved for backwards compatibility and contributes to the total step count.