ImpactZInput

impact.z.ImpactZInput

Bases: BaseModel

Input settings for an IMPACT-Z run.

In the docstring, parameters are grouped by their line number in the file, where ncpu_y starts on line 1.

String values may be used in place of enumeration instances. For example,

ImpactZInput(integrator_type="linear_map")

is equivalent to:

ImpactZInput(integrator_type=IntegratorType.linear_map)

Parameters:

Name	Type	Description	Default
initial_particles	ParticleGroup or None	Initial particle distribution. Default is None.	required
file_data	dict[str, NDArray]	User-provided external file data, indexed by either file ID or name of element - both as strings. Default is an empty dict.	required
ncpu_y	int	Number of processors in y direction. Default is 1.	required
ncpu_z	int	Number of processors in z direction. Default is 1.	required
seed	int	Random number seed. Default is 0.	required
n_particle	int	Number of particles. Default is 0.	required
integrator_type	IntegratorType or str	Type of integrator. Default is IntegratorType.linear_map (equivalently "linear_map").	required
err	int	Error flag. Default is 1.	required
diagnostic_type	DiagnosticType	Type of diagnostics. Default is DiagnosticType.extended.	required
nx	int	Number of mesh points in x. Default is 0.	required
ny	int	Number of mesh points in y. Default is 0.	required
nz	int	Number of mesh points in z. Default is 0.	required
boundary_type	BoundaryType	Boundary condition type. Default is BoundaryType.trans_open_longi_open.	required
radius_x	float	Pipe radius in x direction. Default is 0.0.	required
radius_y	float	Pipe radius in y direction. Default is 0.0.	required
z_period_size	float	Period size in z direction. Default is 0.0.	required
distribution	DistributionType	Particle distribution type. Default is DistributionType.uniform.	required
restart	int	Restart flag. Default is 0.	required
subcycle	int	Subcycling flag. Default is 0.	required
nbunch	int	Number of bunches. Default is 0.	required
particle_list	list[int]	List of particles. Default is [0]. This must be the same length as current_list and charge_over_mass_list.	required
current_list	list[float]	List of currents for each particle type. Default is [0.0]. This is used with: * DistributionType.waterbag and DistributionType.multi_charge_state_gaussian.	required
charge_over_mass_list	list[float]	List of charge-to-mass ratios for each particle type. Default is [0.0]. This is used with: * DistributionType.waterbag and DistributionType.multi_charge_state_gaussian. * CollimateBeam elements * Calculating space charge forces	required
twiss_alpha_x	float	Alpha Twiss parameter in x plane. Default is 0.0.	required
twiss_beta_x	float	Beta Twiss parameter in x plane. Default is 1.0.	required
twiss_norm_emit_x	float	Normalized emittance in x plane. Default is 1e-6.	required
twiss_mismatch_x	float	Mismatch factor for x coordinate. Default is 1.0.	required
twiss_mismatch_px	float	Mismatch factor for px coordinate. Default is 1.0.	required
twiss_offset_x	float	Offset in x coordinate. Default is 0.0.	required
twiss_offset_px	float	Offset in px coordinate. Default is 0.0.	required
twiss_alpha_y	float	Alpha Twiss parameter in y plane. Default is 0.0.	required
twiss_beta_y	float	Beta Twiss parameter in y plane. Default is 1.0.	required
twiss_norm_emit_y	float	Normalized emittance in y plane. Default is 1e-6.	required
twiss_mismatch_y	float	Mismatch factor for y coordinate. Default is 1.0.	required
twiss_mismatch_py	float	Mismatch factor for py coordinate. Default is 1.0.	required
twiss_offset_y	float	Offset in y coordinate. Default is 0.0.	required
twiss_offset_py	float	Offset in py coordinate. Default is 0.0.	required
twiss_alpha_z	float	Alpha Twiss parameter in z plane. Default is 1e-9. This must be non-zero, or compute domain calculations in IMPACT-Z may lead to crashes.	required
twiss_beta_z	float	Beta Twiss parameter in z plane. Default is 1.0.	required
twiss_norm_emit_z	float	Normalized emittance in z plane. Default is 1e-6.	required
twiss_mismatch_z	float	Mismatch factor for z coordinate. Default is 1.0.	required
twiss_mismatch_e_z	float	Mismatch factor for energy coordinate. Default is 1.0.	required
twiss_offset_phase_z	float	Offset in z phase. Default is 0.0.	required
twiss_offset_energy_z	float	Offset in energy. Default is 0.0.	required
average_current	float	Average beam current in Amperes. Default is 1.0.	required
reference_kinetic_energy	float	Reference particle kinetic energy. Default is 0.0.	required
reference_particle_mass	float	Reference particle mass. Default is 0.0.	required
reference_particle_charge	float	Reference particle charge. Default is 0.0.	required
reference_frequency	float	Reference RF frequency. Default is 0.0.	required
initial_phase_ref	float	Initial phase of reference particle. Default is 0.0.	required
lattice	list[AnyInputElement]	List of lattice elements. Default is empty list.	required
filename	Path or None	Input file path. Default is None. (Excluded from JSON serialization.)	required
verbose	bool	Verbose output flag when running IMPACT-Z. Default is False.	required

Attributes

impact.z.ImpactZInput.beam_energy_spread property

beam_energy_spread

Get the sole BeamEnergySpread if it is defined.

impact.z.ImpactZInput.beam_energy_spreads property

beam_energy_spreads

List of all BeamEnergySpread instances.

impact.z.ImpactZInput.beam_kicker_by_rf_nonlinearity property

beam_kicker_by_rf_nonlinearity

Get the sole BeamKickerByRFNonlinearity if it is defined.

impact.z.ImpactZInput.beam_kicker_by_rf_nonlinearitys property

beam_kicker_by_rf_nonlinearitys

List of all BeamKickerByRFNonlinearity instances.

impact.z.ImpactZInput.beam_shift property

beam_shift

Get the sole BeamShift if it is defined.

impact.z.ImpactZInput.beam_shifts property

beam_shifts

List of all BeamShift instances.

impact.z.ImpactZInput.bounds property

bounds

Calculate the phase bounds based on the Twiss settings and distribution type.

Returns:

Type	Description
(xmin, xmax)
(ymin, ymax)
(zmin, zmax)

impact.z.ImpactZInput.bunch_charge property writable

bunch_charge

Bunch charge, if space charge is enabled.

impact.z.ImpactZInput.by_element property

by_element

Get beamline elements organized by their class.

impact.z.ImpactZInput.by_z property

by_z

Get all (flattened) beamline elements by Z location.

Returns:

Type	Description
list of (zend, element)	Each list item is a ZElement, a namedtuple which has .zend and .element that is also usable as a normal tuple.

impact.z.ImpactZInput.ccdtl property

ccdtl

Get the sole CCDTL if it is defined.

impact.z.ImpactZInput.ccdtls property

ccdtls

List of all CCDTL instances.

impact.z.ImpactZInput.ccl property

ccl

Get the sole CCL if it is defined.

impact.z.ImpactZInput.ccls property

ccls

List of all CCL instances.

impact.z.ImpactZInput.collimate_beam property

collimate_beam

Get the sole CollimateBeam if it is defined.

impact.z.ImpactZInput.collimate_beams property

collimate_beams

List of all CollimateBeam instances.

impact.z.ImpactZInput.constant_focusing property

constant_focusing

Get the sole ConstantFocusing if it is defined.

impact.z.ImpactZInput.constant_focusings property

constant_focusings

List of all ConstantFocusing instances.

impact.z.ImpactZInput.cov_t__energy property

cov_t__energy

Calculated (eV*s).

impact.z.ImpactZInput.density_3d property

density_3d

Get the sole Density3D if it is defined.

impact.z.ImpactZInput.density_3ds property

density_3ds

List of all Density3D instances.

impact.z.ImpactZInput.density_profile property

density_profile

Get the sole DensityProfile if it is defined.

impact.z.ImpactZInput.density_profile_input property

density_profile_input

Get the sole DensityProfileInput if it is defined.

impact.z.ImpactZInput.density_profile_inputs property

density_profile_inputs

List of all DensityProfileInput instances.

impact.z.ImpactZInput.density_profiles property

density_profiles

List of all DensityProfile instances.

impact.z.ImpactZInput.dipole property

dipole

Get the sole Dipole if it is defined.

impact.z.ImpactZInput.dipoles property

dipoles

List of all Dipole instances.

impact.z.ImpactZInput.drift property

drift

Get the sole Drift if it is defined.

impact.z.ImpactZInput.drifts property

drifts

List of all Drift instances.

impact.z.ImpactZInput.dtl property

dtl

Get the sole DTL if it is defined.

impact.z.ImpactZInput.dtls property

dtls

List of all DTL instances.

impact.z.ImpactZInput.energy_modulation property

energy_modulation

Get the sole EnergyModulation if it is defined.

impact.z.ImpactZInput.energy_modulations property

energy_modulations

List of all EnergyModulation instances.

impact.z.ImpactZInput.halt_execution property

halt_execution

Get the sole HaltExecution if it is defined.

impact.z.ImpactZInput.halt_executions property

halt_executions

List of all HaltExecution instances.

impact.z.ImpactZInput.integrator_type_switch property

integrator_type_switch

Get the sole IntegratorTypeSwitch if it is defined.

impact.z.ImpactZInput.integrator_type_switchs property

integrator_type_switchs

List of all IntegratorTypeSwitch instances.

impact.z.ImpactZInput.kick_beam_using_multipole property

kick_beam_using_multipole

Get the sole KickBeamUsingMultipole if it is defined.

impact.z.ImpactZInput.kick_beam_using_multipoles property

kick_beam_using_multipoles

List of all KickBeamUsingMultipole instances.

impact.z.ImpactZInput.multipole property

multipole

Get the sole Multipole if it is defined.

impact.z.ImpactZInput.multipoles property

multipoles

List of all Multipole instances.

impact.z.ImpactZInput.nproc property writable

nproc

Number of MPI processors.

impact.z.ImpactZInput.projection_2d property

projection_2d

Get the sole Projection2D if it is defined.

impact.z.ImpactZInput.projection_2ds property

projection_2ds

List of all Projection2D instances.

impact.z.ImpactZInput.quadrupole property

quadrupole

Get the sole Quadrupole if it is defined.

impact.z.ImpactZInput.quadrupoles property

quadrupoles

List of all Quadrupole instances.

impact.z.ImpactZInput.rfcavity_structure_wakefield property

rfcavity_structure_wakefield

Get the sole RfcavityStructureWakefield if it is defined.

impact.z.ImpactZInput.rfcavity_structure_wakefields property

rfcavity_structure_wakefields

List of all RfcavityStructureWakefield instances.

impact.z.ImpactZInput.rotate_beam property

rotate_beam

Get the sole RotateBeam if it is defined.

impact.z.ImpactZInput.rotate_beams property

rotate_beams

List of all RotateBeam instances.

impact.z.ImpactZInput.scale_mismatch_particle_6d_coordinates property

scale_mismatch_particle_6d_coordinates

Get the sole ScaleMismatchParticle6DCoordinates if it is defined.

impact.z.ImpactZInput.scale_mismatch_particle_6d_coordinatess property

scale_mismatch_particle_6d_coordinatess

List of all ScaleMismatchParticle6DCoordinates instances.

impact.z.ImpactZInput.shift_beam_centroid property

shift_beam_centroid

Get the sole ShiftBeamCentroid if it is defined.

impact.z.ImpactZInput.shift_beam_centroids property

shift_beam_centroids

List of all ShiftBeamCentroid instances.

impact.z.ImpactZInput.shift_centroid property

shift_centroid

Get the sole ShiftCentroid if it is defined.

impact.z.ImpactZInput.shift_centroids property

shift_centroids

List of all ShiftCentroid instances.

impact.z.ImpactZInput.sigma_energy property

sigma_energy

Calculated RMS energy spread (eV).

impact.z.ImpactZInput.sigma_t property

sigma_t

Calculated RMS bunch duration (s).

impact.z.ImpactZInput.solenoid property

solenoid

Get the sole Solenoid if it is defined.

impact.z.ImpactZInput.solenoid_with_rf_cavity property

solenoid_with_rf_cavity

Get the sole SolenoidWithRFCavity if it is defined.

impact.z.ImpactZInput.solenoid_with_rf_cavitys property

solenoid_with_rf_cavitys

List of all SolenoidWithRFCavity instances.

impact.z.ImpactZInput.solenoids property

solenoids

List of all Solenoid instances.

impact.z.ImpactZInput.superconducting_cavity property

superconducting_cavity

Get the sole SuperconductingCavity if it is defined.

impact.z.ImpactZInput.superconducting_cavitys property

superconducting_cavitys

List of all SuperconductingCavity instances.

impact.z.ImpactZInput.toggle_space_charge property

toggle_space_charge

Get the sole ToggleSpaceCharge if it is defined.

impact.z.ImpactZInput.toggle_space_charges property

toggle_space_charges

List of all ToggleSpaceCharge instances.

impact.z.ImpactZInput.total_charge property writable

total_charge

Returns the total bunch charge in C. Can be set.

impact.z.ImpactZInput.traveling_wave_rf_cavity property

traveling_wave_rf_cavity

Get the sole TravelingWaveRFCavity if it is defined.

impact.z.ImpactZInput.traveling_wave_rf_cavitys property

traveling_wave_rf_cavitys

List of all TravelingWaveRFCavity instances.

impact.z.ImpactZInput.user_defined_rf_cavity property

user_defined_rf_cavity

Get the sole UserDefinedRFCavity if it is defined.

impact.z.ImpactZInput.user_defined_rf_cavitys property

user_defined_rf_cavitys

List of all UserDefinedRFCavity instances.

impact.z.ImpactZInput.wiggler property

wiggler

Get the sole Wiggler if it is defined.

impact.z.ImpactZInput.wigglers property

wigglers

List of all wiggler instances.

impact.z.ImpactZInput.write_full property

write_full

Get the sole WriteFull if it is defined.

impact.z.ImpactZInput.write_fulls property

write_fulls

List of all WriteFull instances.

impact.z.ImpactZInput.write_phase_space_info property

write_phase_space_info

Get the sole WritePhaseSpaceInfo if it is defined.

impact.z.ImpactZInput.write_phase_space_infos property

write_phase_space_infos

List of all WritePhaseSpaceInfo instances.

impact.z.ImpactZInput.write_slice_info property

write_slice_info

Get the sole WriteSliceInfo if it is defined.

impact.z.ImpactZInput.write_slice_infos property

write_slice_infos

List of all WriteSliceInfo instances.

Functions

impact.z.ImpactZInput.archive

archive(h5)

Dump input data into the given HDF5 group.

Parameters:

Name	Type	Description	Default
h5	Group	The HDF5 file in which to write the information.	required

Source code in impact/z/input.py

def archive(self, h5: h5py.Group) -> None:
    """
    Dump input data into the given HDF5 group.

    Parameters
    ----------
    h5 : h5py.Group
        The HDF5 file in which to write the information.
    """
    _archive.store_in_hdf5_file(h5, self)

impact.z.ImpactZInput.from_archive classmethod

from_archive(h5)

Loads input from archived h5 file.

Parameters:

Name	Type	Description	Default
h5	str or File	The filename or handle on h5py.File from which to load data.	required

Source code in impact/z/input.py

@classmethod
def from_archive(cls, h5: h5py.Group) -> ImpactZInput:
    """
    Loads input from archived h5 file.

    Parameters
    ----------
    h5 : str or h5py.File
        The filename or handle on h5py.File from which to load data.
    """
    loaded = _archive.restore_from_hdf5_file(h5)
    if not isinstance(loaded, ImpactZInput):
        raise ValueError(
            f"Loaded {loaded.__class__.__name__} instead of a "
            f"ImpactZInput instance.  Was the HDF group correct?"
        )
    return loaded

impact.z.ImpactZInput.from_tao classmethod

from_tao(tao, track_start=None, track_end=None, *, radius_x=0.0, radius_y=0.0, ncpu_y=1, ncpu_z=1, nx=None, ny=None, nz=None, which='model', ix_uni=1, ix_branch=0, reference_frequency=1300000000.0, verbose=False, initial_particles_file_id=100, final_particles_file_id=101, initial_rfdata_file_id=500, initial_write_full_id=200, write_beam_eles=('monitor::*', 'marker::*'), include_collimation=True, integrator_type=linear_map)

Create an ImpactZInput object from a Tao instance's lattice.

This function converts a Tao model into an ImpactZInput by extracting the relevant lattice and particle information, and packages it into a structure suitable for running IMPACT-Z simulations.

Parameters:

Name	Type	Description	Default
tao	Tao	The Tao instance.	required
track_start	str or None	Name of the element in the Tao model where tracking begins. If None, defaults to the first element.	None
track_end	str or None	Name of the element in the Tao model where tracking ends. If None, defaults to the last element.	None
radius_x	float	The transverse aperture radius in the x-dimension.	0.0
radius_y	float	The transverse aperture radius in the y-dimension.	0.0
ncpu_y	int	Number of processor divisions along the y-axis.	1
ncpu_z	int	Number of processor divisions along the z-axis.	1
nx	int	Space charge grid mesh points along the x-axis. Defaults to space_charge_mesh_size.	None
ny	int	Space charge grid mesh points along the y-axis. Defaults to space_charge_mesh_size.	None
nz	int	Space charge grid mesh points along the z-axis. Defaults to space_charge_mesh_size.	None
which	"model", "base", or "design"	Specifies the source of lattice data used from Tao.	'model'
ix_uni	int	The universe index.	1
ix_branch	int	The branch index.	0
reference_frequency	float	The reference frequency for IMPACT-Z.	1300000000.0
verbose	bool	If True, prints additional diagnostic information.	False
initial_particles_file_id	int	File ID for the initial particle distribution.	100
final_particles_file_id	int	File ID for the final particle distribution.	101
initial_rfdata_file_id	int	File ID for the first RF data file.	500
initial_write_full_id	int	File ID for the first WriteFull instance.	200
write_beam_eles	str or Sequence[str]	Element(s) by name or Tao-supported match to use at which to write particle data via WriteFull.	('monitor::*', 'marker::*')
include_collimation	bool	If True, includes collimation elements in the lattice conversion. Defaults to True.	True
integrator_type	IntegratorType	The integrator scheme to be used in the lattice conversion. Defaults to 'linear_map', but this may be switched automatically to Runge-Kutta depending on IMPACT-Z run requirements.	linear_map

Returns:

Type	Description
ImpactZInput

Source code in impact/z/input.py

@classmethod
def from_tao(
    cls,
    tao: Tao,
    track_start: str | None = None,
    track_end: str | None = None,
    *,
    radius_x: float = 0.0,
    radius_y: float = 0.0,
    ncpu_y: int = 1,
    ncpu_z: int = 1,
    nx: int | None = None,
    ny: int | None = None,
    nz: int | None = None,
    which: TaoWhich = "model",
    ix_uni: int = 1,
    ix_branch: int = 0,
    reference_frequency: float = 1300000000.0,
    verbose: bool = False,
    initial_particles_file_id: int = 100,
    final_particles_file_id: int = 101,
    initial_rfdata_file_id: int = 500,
    initial_write_full_id: int = 200,
    write_beam_eles: str | Sequence[str] = ("monitor::*", "marker::*"),
    include_collimation: bool = True,
    integrator_type: IntegratorType = IntegratorType.linear_map,
) -> ImpactZInput:
    """
    Create an ImpactZInput object from a Tao instance's lattice.

    This function converts a Tao model into an ImpactZInput by extracting the
    relevant lattice and particle information, and packages it into a structure
    suitable for running IMPACT-Z simulations.

    Parameters
    ----------
    tao : Tao
        The Tao instance.
    track_start : str or None, optional
        Name of the element in the Tao model where tracking begins.
        If None, defaults to the first element.
    track_end : str or None, optional
        Name of the element in the Tao model where tracking ends.
        If None, defaults to the last element.
    radius_x : float, optional
        The transverse aperture radius in the x-dimension.
    radius_y : float, optional
        The transverse aperture radius in the y-dimension.
    ncpu_y : int, optional
        Number of processor divisions along the y-axis.
    ncpu_z : int, optional
        Number of processor divisions along the z-axis.
    nx : int, optional
        Space charge grid mesh points along the x-axis.
        Defaults to space_charge_mesh_size.
    ny : int, optional
        Space charge grid mesh points along the y-axis.
        Defaults to space_charge_mesh_size.
    nz : int, optional
        Space charge grid mesh points along the z-axis.
        Defaults to space_charge_mesh_size.
    which : "model", "base", or "design", optional
        Specifies the source of lattice data used from Tao.
    ix_uni : int, optional
        The universe index.
    ix_branch : int, optional
        The branch index.
    reference_frequency : float, optional
        The reference frequency for IMPACT-Z.
    verbose : bool, optional
        If True, prints additional diagnostic information.
    initial_particles_file_id : int, optional
        File ID for the initial particle distribution.
    final_particles_file_id : int, optional
        File ID for the final particle distribution.
    initial_rfdata_file_id : int, optional
        File ID for the first RF data file.
    initial_write_full_id : int, optional
        File ID for the first WriteFull instance.
    write_beam_eles : str or Sequence[str], optional
        Element(s) by name or Tao-supported match to use at which to write
        particle data via `WriteFull`.
    include_collimation : bool, optional
        If True, includes collimation elements in the lattice conversion.
        Defaults to True.
    integrator_type : IntegratorType, optional
        The integrator scheme to be used in the lattice conversion.
        Defaults to 'linear_map', but this may be switched automatically to
        Runge-Kutta depending on IMPACT-Z run requirements.

    Returns
    -------
    ImpactZInput
    """
    from .interfaces.bmad import ConversionState

    state = ConversionState.from_tao(
        tao=tao,
        track_start=track_start,
        track_end=track_end,
        reference_frequency=reference_frequency,
        ix_uni=ix_uni,
        ix_branch=ix_branch,
        which=which,
        integrator_type=integrator_type,
    )

    lattice, file_data = state.convert_lattice(
        tao=tao,
        verbose=verbose,
        initial_particles_file_id=initial_particles_file_id,
        final_particles_file_id=final_particles_file_id,
        initial_rfdata_file_id=initial_rfdata_file_id,
        initial_write_full_id=initial_write_full_id,
        write_beam_eles=write_beam_eles,
        include_collimation=include_collimation,
    )

    input = state.to_input(
        # tao=tao,
        lattice=lattice,
        file_data=file_data,
        radius_x=radius_x,
        radius_y=radius_y,
        ncpu_y=ncpu_y,
        ncpu_z=ncpu_z,
        nx=nx,
        ny=ny,
        nz=nz,
    )
    return input

impact.z.ImpactZInput.get_aligned_initial_particles

get_aligned_initial_particles(phase_ref=None)

A copy of the initial particles, with time shifted to align with the initial phase.

Source code in impact/z/input.py

def get_aligned_initial_particles(
    self, phase_ref: float | None = None
) -> ParticleGroup | None:
    """A copy of the initial particles, with time shifted to align with the initial phase."""
    if self.initial_particles is None:
        return None

    if phase_ref is None:
        phase_ref = self.initial_phase_ref

    t_offset = phase_ref / (2 * np.pi * self.reference_frequency)
    particles = self.initial_particles.copy()
    particles.t = particles.t - t_offset

    if len(particles) == 1:
        particles.weight = [0]
    return particles

impact.z.ImpactZInput.plot

plot(*, ax=None, bounds=None, include_labels=True, include_markers=True, include_marker_labels=None, figsize=(6, 2))

Make a matplotlib plot of the lattice layout.

Parameters:

Name	Type	Description	Default
ax	Axes	Axes object on which to draw the layout. If None, a new figure and axes are created.	None
bounds	(float, float)	Lower and upper bounds for z position. Defaults to None.	None
include_labels	bool	Whether to include element labels in the plot. Defaults to True.	True
include_markers	bool	If True, include zero length markers in the plot. Default is True.	True
include_marker_labels	bool	If True, include labels for markers when include_markers is set. Default is include_labels.	None
figsize	tuple of int	Size of the figure in inches (width, height) when a new figure is created. Defaults to (6, 2).	(6, 2)

Returns:

Type	Description
Axes	The axes object containing the plotted layout.

Source code in impact/z/input.py

def plot(
    self,
    *,
    ax: matplotlib.axes.Axes | None = None,
    bounds: tuple[float, float] | None = None,
    include_labels: bool = True,
    include_markers: bool = True,
    include_marker_labels: bool | None = None,
    figsize: tuple[int, int] = (6, 2),
):
    """
    Make a matplotlib plot of the lattice layout.

    Parameters
    ----------
    ax : matplotlib.axes.Axes, optional
        Axes object on which to draw the layout. If None, a new figure and axes
        are created.
    bounds : (float, float), optional
        Lower and upper bounds for z position. Defaults to None.
    include_labels : bool, optional
        Whether to include element labels in the plot. Defaults to True.
    include_markers : bool, optional
        If True, include zero length markers in the plot. Default is True.
    include_marker_labels : bool, optional
        If True, include labels for markers when `include_markers` is set.
        Default is `include_labels`.
    figsize : tuple of int, optional
        Size of the figure in inches (width, height) when a new figure is created.
        Defaults to (6, 2).

    Returns
    -------
    matplotlib.axes.Axes
        The axes object containing the plotted layout.
    """
    from .plot import plot_layout

    if include_marker_labels is None:
        include_marker_labels = include_labels

    return plot_layout(
        by_z=self.by_z,
        ax=ax,
        bounds=bounds,
        include_labels=include_labels,
        include_markers=include_markers,
        include_marker_labels=include_marker_labels,
        figsize=figsize,
    )

impact.z.ImpactZInput.set_twiss_z

set_twiss_z(sigma_t, sigma_energy, cov_t__energy=0.0)

Sets twiss_alpha_z, twiss_beta_z, and twiss_norm_emit_z from standard physical beam quantities.

Note

Requires that sigma_t * sigma_energy >= abs(cov_t__energy).

Parameters:

Name	Type	Description	Default
sigma_t	float	Initial RMS bunch duration (s)	required
sigma_energy	float	Initial RMS energy spread (eV)	required
cov_t__energy	float	Initial (eV*s)	0.0

Source code in impact/z/input.py

def set_twiss_z(
    self,
    sigma_t: float,
    sigma_energy: float,
    cov_t__energy: float = 0.0,
) -> None:
    """
    Sets `twiss_alpha_z`, `twiss_beta_z`, and `twiss_norm_emit_z` from
    standard physical beam quantities.

    Note
    ----
    Requires that `sigma_t * sigma_energy >= abs(cov_t__energy)`.

    Parameters
    ----------
    sigma_t : float
        Initial RMS bunch duration (s)
    sigma_energy : float
        Initial RMS energy spread (eV)
    cov_t__energy : float
        Initial <t, energy>  (eV*s)
    """

    if sigma_t * sigma_energy < abs(cov_t__energy):
        raise ValueError(
            f"sigma_t * sigma_energy ({sigma_t * sigma_energy} eV*s) must be >= abs(cov_t__energy) ({abs(cov_t__energy)} eV*s)"
        )

    fref = self.reference_frequency
    scale_z = self.twiss_mismatch_z
    scale_e_z = self.twiss_mismatch_e_z

    sig_t = sigma_t / scale_z
    sig_e = sigma_energy / scale_e_z
    cov = cov_t__energy / (scale_z * scale_e_z)

    emit = np.sqrt(
        (fref * sig_t * 360) ** 2 * (sig_e / 1e6) ** 2
        - (fref * cov / 1e6 * 360) ** 2
    )
    if emit <= 0.0:
        raise ValueError("Calculated `twiss_norm_emit_z` <= 0.0")

    alpha_z = -cov * fref * 360 / 1e6 / emit

    if alpha_z == 0.0:
        # twiss_alpha_z must be nonzero
        alpha_z = 1e-9

    self.twiss_norm_emit_z = emit
    self.twiss_alpha_z = alpha_z
    self.twiss_beta_z = (fref * sig_t * 360) ** 2 / emit

impact.z.ImpactZInput.update_particle_parameters

update_particle_parameters()

Update all relevant parameters from self.initial_particles.

This method configures particle-related parameters based on the initial particle distribution. If no initial particles are defined, it sets default values. Otherwise, it configures the distribution type, particle count, current, and charge-to-mass ratio based on the initial particles.

Notes

It is not typically required to call this separately. When setting initial_particles, a Pydantic validator will set these appropriately.

The following attributes are updated: - self.distribution: Set to DistributionType.read if initial particles exist - self.n_particle: The number of particles - self.particle_list: List containing the number of particles - self.current_list: List containing the particle charge scaled by reference frequency - self.charge_over_mass_list: List containing the charge-to-mass ratio

Source code in impact/z/input.py

def update_particle_parameters(self) -> None:
    """
    Update all relevant parameters from `self.initial_particles`.

    This method configures particle-related parameters based on the initial particle
    distribution. If no initial particles are defined, it sets default values. Otherwise,
    it configures the distribution type, particle count, current, and charge-to-mass ratio
    based on the initial particles.

    Notes
    -----
    It is not typically required to call this separately.  When setting
    `initial_particles`, a Pydantic validator will set these appropriately.

    The following attributes are updated:
    - `self.distribution`: Set to DistributionType.read if initial particles exist
    - `self.n_particle`: The number of particles
    - `self.particle_list`: List containing the number of particles
    - `self.current_list`: List containing the particle charge scaled by reference frequency
    - `self.charge_over_mass_list`: List containing the charge-to-mass ratio
    """
    if self.initial_particles is None:
        self.particle_list = [self.n_particle]
        self.current_list = [0.0]
        self.charge_over_mass_list = [0.0]
        return

    self.distribution = DistributionType.read
    self.n_particle = len(self.initial_particles)
    self.particle_list = [self.n_particle]
    self.current_list = [self.initial_particles.charge * self.reference_frequency]
    self.charge_over_mass_list = [
        self.initial_particles.species_charge / e / self.initial_particles.mass
    ]

impact.z.ImpactZInput.write_particles_at

write_particles_at(elements=(), *, every=None, initial_particles=True, final_particles=True, start_file_id=100, suffix='_WRITE', in_place=True)

Insert WriteFull elements in the lattice to record particle data at specified points.

This function inserts WriteFull elements after each given lattice element index or name, and can optionally add them at the beginning and end of the lattice to record initial and final particle data, respectively.

Specify every to write particles after each element of that type(s).

Parameters:

Name	Type	Description	Default
elements	Sequence[int | str] or int or str	One or more element indices or names where new WriteFull elements will be inserted.	()
every	Sequence[class], class or None	If provided, a WriteFull element will also be inserted after each lattice element whose class is in this sequence. By default None.	None
initial_particles	bool	If True, adds a WriteFull element at the beginning of the lattice to record the initial particle distribution, by default True.	True
final_particles	bool	If True, adds a WriteFull element at the end of the lattice to record the final particle distribution, by default True.	True
start_file_id	int	The file ID to assign to the first newly inserted WriteFull element, by default 1.	100
suffix	str	Suffix appended to the names of newly inserted WriteFull elements, by default "_WRITE".	'_WRITE'
in_place	bool	If True, the lattice is modified in place; otherwise, a new lattice with the modifications is returned, by default True.	True

Returns:

Type	Description
list[AnyInputElement] or None	If in_place is False, returns the new lattice list with WriteFull elements inserted. If in_place is True, the lattice is modified in place and None is returned.

Raises:

Type	Description
ValueError	If an element name in the input cannot be found in the lattice.

Source code in impact/z/input.py

def write_particles_at(
    self,
    elements: Sequence[int | str] | int | str = (),
    *,
    every: Sequence[type[AnyInputElement]] | type[AnyInputElement] | None = None,
    initial_particles: bool = True,
    final_particles: bool = True,
    start_file_id: int = 100,
    suffix: str = "_WRITE",
    in_place: bool = True,
) -> list[AnyInputElement] | None:
    """
    Insert WriteFull elements in the lattice to record particle data at
    specified points.

    This function inserts WriteFull elements after each given lattice
    element index or name, and can optionally add them at the beginning and
    end of the lattice to record initial and final particle data,
    respectively.

    Specify `every` to write particles after each element of that type(s).

    Parameters
    ----------
    elements : Sequence[int | str] or int or str
        One or more element indices or names where new WriteFull elements
        will be inserted.
    every : Sequence[class], class or None, optional
        If provided, a WriteFull element will also be inserted after each
        lattice element whose class is in this sequence. By default None.
    initial_particles : bool, optional
        If True, adds a WriteFull element at the beginning of the lattice
        to record the initial particle distribution, by default True.
    final_particles : bool, optional
        If True, adds a WriteFull element at the end of the lattice to
        record the final particle distribution, by default True.
    start_file_id : int, optional
        The file ID to assign to the first newly inserted WriteFull
        element, by default 1.
    suffix : str, optional
        Suffix appended to the names of newly inserted WriteFull elements,
        by default "_WRITE".
    in_place : bool, optional
        If True, the lattice is modified in place; otherwise, a new lattice
        with the modifications is returned, by default True.

    Returns
    -------
    list[AnyInputElement] or None
        If in_place is False, returns the new lattice list with WriteFull
        elements inserted. If in_place is True, the lattice is modified in
        place and None is returned.

    Raises
    ------
    ValueError
        If an element name in the input cannot be found in the lattice.
    """
    if isinstance(elements, (str, int)):
        elements = [elements]

    if every is None:
        every = []
    elif not isinstance(every, Iterable):
        every = [every]

    every = list(every)

    def get_save_indices():
        by_name = self.by_name
        for ele in elements:
            if isinstance(ele, int):
                idx = ele
            else:
                try:
                    idx = new_lattice.index(by_name[ele])
                except Exception:
                    raise ValueError(
                        f"Element {ele} not found in the lattice. Note that WriteFull elements are not supported here."
                    )
            yield idx + 1

        for cls in every:
            for ele in self.by_element.get(cls, []):
                try:
                    yield new_lattice.index(ele) + 1
                except IndexError:
                    pass

    new_lattice: list[AnyInputElement] = [
        ele for ele in self.lattice if not isinstance(ele, WriteFull)
    ]
    save_indices = sorted(set(get_save_indices()), reverse=True)

    for idx in save_indices:
        ele = new_lattice[idx - 1]
        if not isinstance(ele, WriteFull):
            new_lattice.insert(idx, WriteFull(name=f"{ele.name}{suffix}"))

    if initial_particles:
        new_lattice.insert(0, WriteFull(name="initial_particles"))
    if final_particles:
        new_lattice.append(WriteFull(name="final_particles"))

    file_id = start_file_id
    for elem in new_lattice:
        if isinstance(elem, WriteFull):
            elem.file_id = file_id
            file_id += 1

    if in_place:
        self.lattice = new_lattice
        return
    return new_lattice

Beamline elements

impact.z.CCDTL

Bases: InputElement

A CCDTL (Cell-Coupled Drift Tube Linac) input element represented by its parameters.

Attributes:

Name	Type	Description
length	float	Length of the element in meters.
steps	int	Number of space-charge kicks through the beamline element. Each "step" consists of a half-step, a space-charge kick, and another half-step.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
field_scaling	float	Field scaling factor.
rf_frequency	float	RF frequency in Hertz.
phase_deg	float	Driven phase in degrees.
file_id	float	Input field ID (if ID<0, use simple sinusoidal model, only works for the map integrator). The phase is the design phase with 0 for maximum energy gain.
radius	float	Radius in meters.
misalignment_x	float	X misalignment error in meters.
misalignment_error_y	float	Y misalignment error in meters.
rotation_error_x	float	Rotation error around the x-axis in radians.
rotation_error_y	float	Rotation error around the y-axis in radians.
rotation_error_z	float	Rotation error around the z-axis in radians.

impact.z.CCL

Bases: InputElement

CCL input element with specific parameters.

Attributes:

Name	Type	Description
length	float	Length of the element in meters.
steps	int	Number of space-charge kicks through the beamline element. Each "step" consists of a half-step, a space-charge kick, and another half-step.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
field_scaling	float	Field scaling factor.
rf_frequency	float	RF frequency in Hertz.
phase_deg	float	Driven phase in degrees.
file_id	float	Input field ID. If ID < 0, use the simple sinusoidal model (only works for the map integrator, phase is the design phase with 0 for maximum energy gain).
radius	float	Radius of the element in meters.
misalignment_error_x	float	X-axis misalignment error in meters.
misalignment_error_y	float	Y-axis misalignment error in meters.
rotation_error_x	float	Rotation error about the x-axis in radians.
rotation_error_y	float	Rotation error about the y-axis in radians.
rotation_error_z	float	Rotation error about the z-axis in radians.

impact.z.ConstantFocusing

Bases: InputElement

3D constant focusing.

Attributes:

Name	Type	Description
length	float	Length of the element in meters.
steps	int	Number of space-charge kicks through the beamline element. Each "step" consists of a half-step, a space-charge kick, and another half-step.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
kx0_squared	float	The square of the kx0 parameter.
ky0_squared	float	The square of the ky0 parameter.
kz0_squared	float	The square of the kz0 parameter.
radius	float	The radius of the focusing element in meters.

Notes

This class does not work for the Lorentz integrator option.

impact.z.DTL

Bases: InputElement

Discrete-Transmission-Line element with specified parameters.

Attributes:

Name	Type	Description
length	float	Length of the element in meters.
steps	int	Number of space-charge kicks through the beamline element. Each "step" consists of a half-step, a space-charge kick, and another half-step.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
field_scaling	float	Scaling factor for the electrical/magnetic field.
rf_frequency	float	RF frequency in Hertz.
phase_deg	float	Driven phase in degrees.
file_id	float	Input field ID (using a simple sinusoidal model if ID<0).
radius	float	Radius in meters.
quad1_length	float	Length of the first quadrupole in meters.
quad1_gradient	float	Gradient of the first quadrupole in Tesla/meter.
quad2_length	float	Length of the second quadrupole in meters.
quad2_gradient	float	Gradient of the second quadrupole in Tesla/meter.
misalignment_error_x	float	Misalignment error in the x-direction in meters.
misalignment_error_y	float	Misalignment error in the y-direction in meters.
rotation_error_x	float	Rotation error around the x-axis in radians.
rotation_error_y	float	Rotation error around the y-axis in radians.
rotation_error_z	float	Rotation error around the z-axis in radians.
displacement_x	float	Displacement in the x-direction in meters.
displacement_y	float	Displacement in the y-direction in meters.
rotation_error_rf_x	float	Rotation error around the x-axis for the RF field in radians.
rotation_error_rf_y	float	Rotation error around the y-axis for the RF field in radians.
rotation_error_rf_z	float	Rotation error around the z-axis for the RF field in radians.

impact.z.Dipole

Bases: InputElement

Represents a dipole element used in beam simulations.

Attributes:

Name	Type	Description
length	float	Length of the element in meters.
steps	int	Number of space-charge kicks through the beamline element. Each "step" consists of a half-step, a space-charge kick, and another half-step.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
angle	(float, optional)	Bending angle [rad]. Must be non-zero.
k1	(float, optional)	Field strength.
input_switch	(float, optional)	CSR settings. - input_switch <= 200: no CSR - 200 < input_switch <=500: CSR in the bend - input_switch > 500: CSR in the bend and the next following drift Ref: https://github.com/impact-lbl/IMPACT-Z/blob/96ae896517bcb83fa741cd203892cb42a88f0e4f/src/Contrl/AccSimulator.f90#L999-L1004
hgap	(float, optional)	Half gap [m].
e1	(float, optional)	Entrance pole face angle [rad].
e2	(float, optional)	Exit pole face angle [rad].
entrance_curvature	(float, optional)	Curvature of entrance face [rad].
exit_curvature	(float, optional)	Curvature of exit face [rad].
fint	(float, optional)	Integrated fringe field K of entrance (Kf). Fringe field K of exit assumed to be equal (Kb = Kf).
misalignment_error_x	(float, optional)	Misalignment error in the x direction.
misalignment_error_y	(float, optional)	Misalignment error in the y direction.
rotation_error_x	(float, optional)	Rotation error around the x axis.
rotation_error_y	(float, optional)	Rotation error around the y axis.
rotation_error_z	(float, optional)	Rotation error around the z axis.

Notes

hd0 = angle/blength !k0
tanphiF = tan(e1)
psi1 = hd0*2*hgap*fint*(1.0+sin(e1)*sin(e1))/cos(e1)
tanphiFb = tan(e1-psi1)
tanphiB = tan(e2)
psi2 = hd0*2*hgap*fint*(1.0+sin(e2)*sin(e2))/cos(e2)
tanphiBb = tan(e2-psi2)
qm0 = Bpts%Charge/Bpts%Mass
r0  = abs(1.0d0/hd0)

Functions

impact.z.Dipole.set_csr

set_csr(enabled, following_drift)

Set the input switch CSR setting.

Parameters:

Name	Type	Description	Default
enabled	bool	Enable CSR for the dipole bend.	required
following_drift	bool	In addition to CSR for the dipole, also use CSR on the following drift element. Only applies when enabled.	required

Source code in impact/z/input.py

def set_csr(self, enabled: bool, following_drift: bool) -> None:
    """
    Set the input switch CSR setting.

    Parameters
    ----------
    enabled : bool
        Enable CSR for the dipole bend.
    following_drift : bool
        In addition to CSR for the dipole, also use CSR on the following
        drift element.  Only applies when `enabled`.
    """
    if not enabled:
        value = 0.0
    elif following_drift:
        value = 501.0
    else:
        value = 201.0
    self.input_switch = value

impact.z.Drift

Bases: InputElement

Drift element.

Attributes:

Name	Type	Description
length	float	Length of the element in meters.
steps	int	Number of space-charge kicks through the beamline element. Each "step" consists of a half-step, a space-charge kick, and another half-step.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
radius	float	Radius of the pipe, in meters.

impact.z.Multipole

Bases: InputElement

Represents a multipole element used in beam simulations.

Attributes:

Name	Type	Description
length	float	Length of the element in meters.
steps	int	Number of space-charge kicks through the beamline element. Each "step" consists of a half-step, a space-charge kick, and another half-step.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
multipole_type	MultipoleType	The type of multipole element, sextupole, octupole, or decapole.
field_strength	(float, optional)	The strength of the magnetic field. Units of T/m^n.
file_id	(float, optional)	Identifier for related input data file.
radius	(float, optional)	The radius of the multipole.
misalignment_error_x	(float, optional)	Misalignment error in the x-direction.
misalignment_error_y	(float, optional)	Misalignment error in the y-direction.
rotation_error_x	(float, optional)	Rotation error around the x-axis.
rotation_error_y	(float, optional)	Rotation error around the y-axis.
rotation_error_z	(float, optional)	Rotation error around the z-axis.

impact.z.Quadrupole

Bases: InputElement

A quadrupole element.

Attributes:

Name	Type	Description
length	float	Length of the element in meters.
steps	int	Number of space-charge kicks through the beamline element. Each "step" consists of a half-step, a space-charge kick, and another half-step.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
k1	float	The quadrupole strength, 1/m^2. (NOTE: the manual is actually wrong here, this is not B1 in units of T/m)
file_id	float	An ID for the input gradient file. Determines profile behavior: if greater than 0, a fringe field profile is read; if less than -10, a linear transfer map of an undulator is used; if between -10 and 0, it's the k-value linear transfer map; if equal to 0, it uses the linear transfer map with the gradient.
radius	float	The radius of the quadrupole, measured in meters.
misalignment_error_x	(float, optional)	The x-direction misalignment error, given in meters.
misalignment_error_y	(float, optional)	The y-direction misalignment error, given in meters.
rotation_error_x	(float, optional)	Rotation error in radians.
rotation_error_y	(float, optional)	Rotation error in radians.
rotation_error_z	(float, optional)	Rotation error in radians.

impact.z.Solenoid

Bases: InputElement

Solenoid used in beam dynamics simulations.

Attributes:

Name	Type	Description
length	float	The effective length of the solenoid in meters, including two linear fringe regions and a flat top region (solenoid integrator).
steps	int	Number of space-charge kicks through the beamline element. Each "step" consists of a half-step, a space-charge kick, and another half-step.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
Bz0	float	The axial magnetic field at the center of the solenoid in Tesla.
file_id	float	The identifier for the input field file.
radius	float	The radius of the solenoid in meters.
misalignment_error_x	float	Misalignment error in the x-direction in meters.
misalignment_error_y	float	Misalignment error in the y-direction in meters.
x_rotation_error	float	Rotation error in the x-direction in radians.
rotation_error_y	float	Rotation error in the y-direction in radians.
rotation_error_z	float	Rotation error in the z-direction in radians.

Cavities

impact.z.SolenoidWithRFCavity

Bases: InputElement

A solenoid with an RF cavity.

Attributes:

Name	Type	Description
length	float	Length of the element in meters.
steps	int	Number of space-charge kicks through the beamline element. Each "step" consists of a half-step, a space-charge kick, and another half-step.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
field_scaling	float	The field scaling factor.
rf_frequency	float	The RF frequency in Hertz.
phase_deg	float	The driven phase in degrees.
file_id	float	The input field ID.
radius	float	The radius of the solenoid in meters.
misalignment_error_x	float	The x-axis misalignment error in meters.
misalignment_error_y	float	The y-axis misalignment error in meters.
rotation_error_x	float	The error in rotation about the x-axis in radians.
rotation_error_y	float	The error in rotation about the y-axis in radians.
rotation_error_z	float	The error in rotation about the z-axis in radians.
bz0	float	The Bz0 field value in Tesla.
aperture_size_for_wakefield	float	The aperture size for wakefield computations.
gap_size_for_wakefield	float	The gap size for the wake field.
length_for_wakefield	float	The length for wake, indicating RF structure wakefield should be turned on if this value is greater than zero.

Attributes

impact.z.SolenoidWithRFCavity.rf_wavelength property writable

rf_wavelength

RF wavelength.

impact.z.SuperconductingCavity

Bases: InputElement

Attributes:

Name	Type	Description
length	float	Length of the element in meters.
steps	int	Number of space-charge kicks through the beamline element. Each "step" consists of a half-step, a space-charge kick, and another half-step.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
scale	float	Field scaling factor.
rf_frequency	float	RF frequency in Hz.
phase_deg	float	Driven phase in degrees (design phase with 0 for maximum energy gain).
file_id	float	Input field ID (if ID < 0, only works for the map integrator).
radius	float	Radius in meters.

impact.z.TravelingWaveRFCavity

Bases: InputElement

Traveling Wave RF Cavity element.

This element represents a traveling wave RF cavity specified by several parameters that define its physical and operational characteristics.

Attributes:

Name	Type	Description
length	float	Length of the element in meters.
steps	int	Number of space-charge kicks through the beamline element. Each "step" consists of a half-step, a space-charge kick, and another half-step.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
field_scaling	float	Scaling factor for the field.
rf_frequency	float	RF frequency, in Hertz.
phase_deg	float	Driven phase in degrees.
file_id	float	Input field ID.
radius	float	Radius of the cavity in meters.
misalignment_error_x	float	X misalignment error in meters.
misalignment_error_y	float	Y misalignment error in meters.
rotation_error_x	float	Rotation errors in x [rad].
rotation_error_y	float	Rotation errors in x [rad].
rotation_error_z	float	Rotation errors in x [rad].
phase_diff	float	Phase difference B and A (pi - beta * d).
aperture_size_for_wakefield	float	Aperture size for wakefield. An aperture size >0 enables the wakefield calculation.
gap_size	float	Gap size for wakefield.

Note

RF structure wakefield is only turned on with a non-zero length_for_wakefield.

impact.z.UserDefinedRFCavity

Bases: InputElement

A user-defined RF cavity element in the simulation.

EMfld in IMPACT-Z.

Attributes:

Name	Type	Description
length	float	Length of the element in meters.
steps	int	Number of space-charge kicks through the beamline element. Each "step" consists of a half-step, a space-charge kick, and another half-step.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
field_scaling	float	Scaling factor for the field.
rf_frequency	float	RF frequency in Hertz.
phase_deg	float	Driven phase in degrees.
file_id	float	ID of the input field.
x_radius	float	X radius in meters.
radius_y	float	Y radius in meters.
misalignment_error_x	float	Misalignment error in the X direction, in meters.
misalignment_error_y	float	Misalignment error in the Y direction, in meters.
rotation_error	tuple	Rotation error in X, Y, Z directions, in radians.
data_mode	float	Mode of using field data. 1.0 uses discrete data only, 2.0 uses both discrete data and analytical function, other values use analytical function only.
coordinate_type	float	Coordinate type for the field. 2.0 for Cartesian coordinates, 1.0 for Cylindrical coordinates.

Notes

The class allocates electric and magnetic field grids with grid sizes defined in the given data format. The grid is adjusted by +1 in each dimension compared to the input intervals.

Control elements

impact.z.BeamEnergySpread

Bases: InputElement

Input element: a beam energy spread input element.

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
radius	float	The radius (not used).
energy_spread	float	The increased energy spread in eV.

impact.z.BeamKickerByRFNonlinearity

Bases: InputElement

Beam kicker element that applies a longitudinal kick to the beam by the RF nonlinearity.

Note that the linear part has been included in the map integrator and subtracted.

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
radius	float	Radius in meters (not used).
vmax	float	Maximum voltage in volts (V).
phi0	float	Initial phase offset in degrees.
harm	int	Harmonic number with respect to the reference frequency.

impact.z.BeamShift

Bases: InputElement

BeamShift shifts the beam longitudinally to the bunch centroid.so that

==0.

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
unused	float

impact.z.CollimateBeam

Bases: InputElement

Collimate the beam with transverse rectangular aperture sizes.

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
radius	float	Radius in meters (not used).
xmin	float	Minimum x value in meters.
xmax	float	Maximum x value in meters.
ymin	float	Minimum y value in meters.
ymax	float	Maximum y value in meters.

impact.z.Density3D

Bases: InputElement

Input element: 3D density.

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
radius	float	Radius in meters.
xmax	float	Maximum x value in meters.
pxmax	float	Maximum px value in mc.
ymax	float	Maximum y value in meters.
pymax	float	Maximum py value in mc.
zmax	float	Maximum z value in degrees.
pzmax	float	Maximum pz value in mc^2.

impact.z.DensityProfile

Bases: InputElement

Input element: write the density along R, X, Y into files.

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
radius	float	Radius in meters.
xmax	float	Maximum value in X direction in meters.
pxmax	float	Maximum value in X direction momentum in mc.
ymax	float	Maximum value in Y direction in meters.
pymax	float	Maximum value in Y direction momentum in mc.
zmax	float	Maximum value in Z direction in radians.
pzmax	float	Maximum value in Z direction momentum in mc^2.

impact.z.DensityProfileInput

Bases: InputElement

Input element: density profile input parameters.

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
radius	float	Radius in meters.
xmax	float	Maximum X in meters.
pxmax	float	Maximum Px in mc.
ymax	float	Maximum Y in meters.
pymax	float	Maximum Py in mc.
zmax	float	Maximum Z in meters.
pzmax	float	Maximum Pz in mc^2.

impact.z.EnergyModulation

Bases: InputElement

Input element: energy modulation (emulate laser heater).

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
beam_size	float	The matched beam size in meters.
laser_wavelength	float	The laser wavelength in meters.
energy_spread	float	The uncorrelated energy spread in eV.

impact.z.HaltExecution

Bases: InputElement

Halt execution at this point in the input file.

This is useful if you have a big file and want to run part-way through it without deleting a lot of lines.

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
map_steps	int	Unused.

impact.z.IntegratorTypeSwitch

Bases: InputElement

Input element: switch the integrator type.

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
integrator_type	IntegratorType	Integrator type.
unused	float

impact.z.KickBeamUsingMultipole

Bases: InputElement

Input element: kick the beam using thin lens multipole.

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
unused	float	First parameter, "1.0" not used.
k0	float	Dipole strength.
k1	float	Quadrupole strength.
k2	float	Sextupole strength.
k3	float	Octupole strength.
k4	float	Decapole strength.
k5	float	Dodecapole strength.

impact.z.Projection2D

Bases: InputElement

Represents the 2D projections of a 6D distribution.

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
radius	float	The radius of the projection.
xmax	float	The maximum x value.
pxmax	float	The maximum px value.
ymax	float	The maximum y value.
pymax	float	The maximum py value.
zmax	float	The maximum z value.
pzmax	float	The maximum pz value.

impact.z.RfcavityStructureWakefield

Bases: InputElement

Input element: read in RF cavity structure wakefield.

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
file_id	float	The file ID to load from.
enable_wakefield	float	-1.0 RF off, 1.0 RF on, < 10 no transverse wakefield effects included

impact.z.RotateBeam

Bases: InputElement

Rotate the beam with respect to the longitudinal axis.

Both (x,y), and (px,py) are rotated.

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
radius	float	The radius in meters.
tilt	float	The rotation angle in radians.

impact.z.ScaleMismatchParticle6DCoordinates

Bases: InputElement

Scale/mismatch the particle 6D coordinates.

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
radius	float	The radius, not used in computations.
xmis	float	The x-coordinate mismatch.
pxmis	float	The px-coordinate mismatch.
ymis	float	The y-coordinate mismatch.
pymis	float	The py-coordinate mismatch.
tmis	float	The time-coordinate mismatch.
ptmis	float	The pt-coordinate mismatch.

impact.z.ShiftBeamCentroid

Bases: InputElement

Shift the beam centroid in 6D phase space.

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
radius	float	Radius in meters (not used).
xshift	float	Shift in x direction in meters.
pxshift	float	Shift in x momentum in radians.
yshift	float	Shift in y direction in meters.
pyshift	float	Shift in y momentum in radians.
zshift	float	Shift in z direction in degrees.
pzshift	float	Shift in z momentum in MeV.

impact.z.ShiftCentroid

Bases: InputElement

Shift the centroid.

Attributes:

Name	Type	Description
length	float	Length of the element in meters.
steps	int	Number of space-charge kicks through the beamline element. Each "step" consists of a half-step, a space-charge kick, and another half-step.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.

impact.z.ToggleSpaceCharge

Bases: InputElement

Toggle space charge. Available in IMPACT-Z v2.5+.

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
map_steps	int	Number of "map steps". Each half-step involves computing a map for that half-element which is computed by numerical integration.
unused	float	Not used.
enable	float	Toggle space charge on or off.

impact.z.WriteFull

Bases: InputElement

Write the particle distribution into a fort.N file.

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
file_id	int	The File ID.
unused_2	float	Unused
sample_frequency	int	Write every Nth particle.

Notes

• The file written will not support N values of 5, 6, 24, 25, 26, 27, 29, 30, or 32 when using Fortran code.
• The printed dataset uses sample frequency 10, meaning every 10th particle is output.
• Particles recorded are dimensionless, in an IMPACT internal unit.
• A positive sample frequency specifies magnitude in standard units; a negative implies adoption of the ImpactT format (z as delta z and pz as gamma).

impact.z.WritePhaseSpaceInfo

Bases: InputElement

Input element: write the 6D phase space information and local computation domain information.

Writes to files fort.1000, fort.1001, fort.1002, ..., fort.(1000+Nprocessor-1). This function is used for restart purposes.

impact.z.WriteSliceInfo

Bases: InputElement

Write slice information into file fort.{file_id} using specific slices.

If the twiss mismatch parameters (alpha_x, etc.) are not provided, the mismatch factor will be ignored.

Attributes:

Name	Type	Description
length	float	Unused.
steps	int	Unused.
file_id	float	The file ID to write slice information to.
slices	int	Number of slices.
alpha_x	float	Twiss parameter alpha_x at the location.
beta_x	float	Twiss parameter beta_x at the location (m).
alpha_y	float	Twiss parameter alpha_y at the location.
beta_y	float	Twiss parameter beta_y at the location (m).

Internal / Helpers

impact.z.input.ElementListProxy

Bases: list[T_InputElement]

A list proxy class for input elements.

Getting or setting an attribute on an instance of this class will get or set that attribute on each element of the list.

May be used as a normal list with indexing and standard methods such as .append().

impact.z.input.ZElement

Bases: NamedTuple

A tuple of a Z position and its corresponding beamline element.