Image charge generation

The core.images module provides utilities for generating mirror-image charges representing conducting-wall boundaries in electromagnetic simulations. The primary function generate_conducting_image creates virtual particle bunches that reproduce the boundary conditions of a conducting surface with a circular aperture.

As of January 2025, the module includes macroparticle simulation support, allowing stochastic position and momentum spread errors to be applied to image subcharges for realistic beam emittance modeling.

Module reference

Mirror-image computations used by the retarded integrator.

Conducting boundaries can be represented via image charges. The helpers here construct those synthetic bunches while preserving the validated reference behavior, including the stochastic aperture spill model.

core.images.generate_conducting_image(vector: Dict[str, ndarray], wall_z: float, aperture_radius: float, subcharge_count: int = 12, *, use_weighting: bool = True, macroparticle_charge_multiplier: float = 1.0, macroparticle_sigma_multiplier: float = 1.0, macroparticle_use_momentum_errors: bool = True, bunch_transv_dist: float = 0.0, bunch_transv_mom: float = 0.0, timestep: float = 0.0, step_number: int = 0) → 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.
use_weighting – When True (default) apply radial attenuation to the subcharges based on their cylindrical distance from the aperture axis.
macroparticle_charge_multiplier – Multiplier for the charge of both test particle and image subcharges. Default 1.0 (no scaling). Use > 1.0 for macroparticle simulations.
macroparticle_sigma_multiplier – Multiplier applied to bunch spread parameters when computing image charge errors. Default 1.0 (errors = bunch spread). Position errors = bunch_transv_dist × multiplier, momentum errors = bunch_transv_mom × multiplier.
macroparticle_use_momentum_errors – Whether to include momentum-based cumulative errors. If False, only constant position errors are applied. Default True (include both position and momentum errors).
bunch_transv_dist – Transverse distribution half-width (mm) from particle bunch initialization. Used to compute position spread for image charge errors.
bunch_transv_mom – Transverse momentum spread (amu*mm/ns) from particle bunch initialization. Used to compute cumulative displacement errors that grow with step_number.
timestep – Integration timestep in proper time (ns). Required when bunch_transv_mom > 0.
step_number – Current integration step number (0-based). Used to compute cumulative displacement from momentum spread.

core.images.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.

Macroparticle simulation

The generate_conducting_image function accepts optional macroparticle parameters that enable realistic modeling of beam collective effects:

Charge scaling

The macroparticle_charge_multiplier parameter scales both the test particle charge and all image subcharge magnitudes by a constant factor. This is used to represent macroparticles (charge bundles) rather than individual particles. Default: 1.0 (no scaling).

Position spread

The macroparticle_position_spread parameter (σ_x in mm) applies independent Gaussian errors to the x and y positions of each image subcharge. These errors are drawn from N(0, σ_x²) and represent the transverse spatial extent of the beam. Default: 0.0 (no spread).

Momentum spread

The macroparticle_momentum_spread parameter (σ_p) creates cumulative transverse displacement that grows with each integration timestep. At step number n, the total spread is:

\[\sigma_{\text{total}}(n) = \sqrt{\sigma_x^2 + \left(\frac{\sigma_p}{m} \times h \times n\right)^2}\]

where h is the timestep size and m is the particle mass. This models the divergence of particles with different transverse momenta as they propagate. Default: 0.0 (no momentum spread).

Error application order

Position and momentum errors are applied to subcharge coordinates before the radial weighting and charge attenuation calculations. This ensures that the geometric suppression of charges near the aperture edge accounts for the stochastic displacement of the beam distribution.

Usage example

Basic conducting-wall image generation:

from core.images import generate_conducting_image
from core.types import ParticleState

# Generate image charges for a particle near a conducting wall
image_state = generate_conducting_image(
    vector=rider_state,
    wall_z=100.0,              # Wall at z = 100 mm
    aperture_radius=0.001,     # 1 mm aperture
    subcharge_count=12,        # 12 subcharges around aperture rim
    use_weighting=True,        # Apply radial attenuation
)

Macroparticle mode with beam emittance:

# Simulate 10× charge scaling with position and momentum spread
image_state = generate_conducting_image(
    vector=rider_state,
    wall_z=100.0,
    aperture_radius=0.001,
    subcharge_count=12,
    use_weighting=True,
    macroparticle_charge_multiplier=10.0,     # 10× charge
    macroparticle_position_spread=1e-5,       # 10 μm position σ
    macroparticle_momentum_spread=1e-6,       # Momentum spread
    timestep=3e-7,                            # Integration timestep (ns)
    step_number=500,                          # Current step number
)

The timestep and step_number parameters are required when macroparticle_momentum_spread > 0 to calculate the cumulative momentum- driven displacement.

Physical interpretation

The macroparticle simulation parameters correspond to physical beam properties:

Charge multiplier: Represents the effective number of real particles per simulation macroparticle. For example, a value of 100 means each simulated particle represents 100 actual particles with the total charge scaled accordingly.
Position spread: Models the RMS beam size (geometric emittance) in the transverse plane. For a Gaussian beam with RMS size σ_x, this parameter should be set to σ_x.
Momentum spread: Models the angular divergence of the beam. For a beam with RMS divergence σ_x’ (radians), the momentum spread is approximately σ_p ≈ p × σ_x’ where p is the characteristic momentum scale. The cumulative growth with timesteps reproduces the natural divergence of particles with different angles as they propagate.

The combined effect of position and momentum spread reproduces the normalized emittance evolution:

\[\epsilon_n = \beta \gamma \sqrt{\langle x^2 \rangle \langle x'^2 \rangle - \langle x x' \rangle^2}\]

where β and γ are the relativistic velocity and Lorentz factor.

Image charge generation

Module reference

Macroparticle simulation

Usage example

Physical interpretation

See also