Framework Objects

Simframe Objects Module

Various objects and functions to handle simulation lattices, commands, and elements.

Classes:

• runSetup: Defines simulation run settings, allowing

for single runs, element scans or jitter/error studies.

• frameworkObject: Base class for generic objects in SimFrame,

including lattice elements and simulation code commands.

• frameworkElement: Base class for generic

lattice elements in SimFrame, including lattice elements and simulation code commands.

• csrdrift: Drift element including CSR effects.

• lscdrift: Drift element including LSC effects.

• edrift: Basic drift element.

• frameworkLattice: Base class for simulation lattices,

consisting of a line of frameworkObject s.

• frameworkCounter: Used for counting elements of the same

type in ASTRA and CSRTrack

• frameworkGroup: Used for grouping together

frameworkObject s and controlling them all simultaneously.

• element_group: Subclass of

frameworkGroup for grouping elements. # TODO is this ever used?

• r56_group: Subclass of

frameworkGroup for grouping elements with an R56. # TODO is this ever used?

• chicane: Subclass of frameworkGroup for a 4-dipole bunch compressor chicane.

• getGrids: Used for determining the appropriate number

of space charge grids given a number of particles.

class chicane(name, elementObjects, type, elements, **kwargs)

Bases: frameworkGroup

Class defining a 4-dipole chicane.

property angle: float

Bending angle of the chicane

Returns:

The bending angle

Return type:

float

set_angle(a)

Set the chicane bending angle, including updating the inter-dipole drift lengths.

Parameters:

a (float) – The angle to be set

Return type:

None

update(**kwargs)

Update the bending angle and/or dipole width and/or dipole gap of all magnets in the chicane.

Parameters:

**kwargs (Dict) – Dictionary containing parameters to be updated – must be in [“dipoleangle”, “width”, “gap”]

Return type:

None

class csrdrift(*args, **kwargs)

Bases: frameworkElement

Class defining a drift including CSR effects.

Parameters:

• args (Any)

• kwargs (Any)

csr_enable: bool = True

Enable CSR drift calculations

csrdz: float = 0.01

Step size for CSR calculations

lsc_bins: int = 20

Number of bins for LSC calculations

lsc_enable: bool = True

Enable LSC drift calculations

lsc_high_frequency_cutoff_end: float = -1

Spatial frequency at which smoothing filter is 0. See Elegant manual LSC drift

lsc_high_frequency_cutoff_start: float = -1

Spatial frequency at which smoothing filter begins. If not positive, no frequency filter smoothing is done. See Elegant manual LSC drift

lsc_interpolate: int = 1

Flag to allow for interpolation of computed longitudinal space charge wake. See Elegant manual LSC drift

lsc_low_frequency_cutoff_end: float = -1

Lowest spatial frequency at which low-frequency cutoff filter is 1. See Elegant manual LSC drift

lsc_low_frequency_cutoff_start: float = -1

Highest spatial frequency at which low-frequency cutoff filter is zero. See Elegant manual LSC drift

use_stupakov: int = 1

Use Stupakov formula; see Elegant manual LSC drift

class edrift(*args, **kwargs)

Bases: csrdrift

Class defining a drift.

Parameters:

• args (Any)

• kwargs (Any)

class element_group(name, elementObjects, type, elements, **kwargs)

Bases: frameworkGroup

Class defining a group of elements, which is used to group together elements to perform coordinated actions on them.

class frameworkCommand(*args, **kwargs)

Bases: frameworkObject

Class defining a framework command, which is used to generate commands used in setup files for various simulation codes.

Parameters:

• args (Any)

• kwargs (Any)

write_Elegant()

Writes the command string for ELEGANT.

Returns:

String representation of the command for ELEGANT

Return type:

str

write_MAD8()

Writes the command string for MAD8. # TODO deprecated?

Returns:

String representation of the command for MAD8

Return type:

str

class frameworkCounter(sub={})

Bases: dict

Class defining a counter object, used for numbering elements of the same type in ASTRA and CSRTrack

add(typ, n=1)

Add to count of elements of a given type in the lattice.

Parameters:

• typ (str) – Element type

• n (PositiveInt, optional) – Add more than one element at a time

Returns:

The number of elements of a given type defined so far

Return type:

int

counter(typ)

Increment count of elements of a given type in the lattice.

Parameters:

typ (str) – Element type

Returns:

The updated number of elements of a given type defined so far

Return type:

int

subtract(typ)

Reduce count of elements of a given type in the lattice.

Parameters:

typ (str) – Element type

Returns:

The updated number of elements of a given type defined so far

Return type:

int

value(typ)

Number of elements of a given type in the lattice.

Parameters:

typ (str) – Element type

Returns:

The number of elements of a given type defined so far

Return type:

int

class frameworkElement(*args, **kwargs)

Bases: frameworkObject

Class defining a framework element, which is a specific type of framework object that represents a physical component in a simulation lattice. It extends the frameworkObject class with additional properties and methods specific to elements, such as position, rotation, and field definitions.

Parameters:

• args (Any)

• kwargs (Any)

PV: str | None = None

EPICS PV root for the element

array_names_string()

Get the array names for a given element (i.e. the parameters in the field file)

Returns:

A formatted string containing the array names for the element.

Return type:

str

centre: Tuple[float, float, float] = (0.0, 0.0, 0.0)

Centre of the element in the simulation [x,y,z].

conversion_rules_elegant: Dict = {}

Conversion rules for keywords when exporting to Elegant format.

conversion_rules_ocelot: Dict = {}

Conversion rules for keywords when exporting to Ocelot format.

property dx: float

Returns the x-offset of the element.

Returns:

The x-offset of the element.

Return type:

float

property dx_rot: float

Returns the local x-rotation of the element.

Returns:

The local x-rotation of the element.

Return type:

float

property dy

Returns the y-offset of the element.

Returns:

The y-offset of the element.

Return type:

float

property dy_rot

Returns the local y-rotation of the element.

Returns:

The local y-rotation of the element.

Return type:

float

property dz

Returns the z-offset of the element.

Returns:

The z-offset of the element.

Return type:

float

property dz_rot

Returns the local z-rotation of the element.

Returns:

The local z-rotation of the element.

Return type:

float

property end: list

Returns the end position of the element, which is calculated based on its starting position and length.

Returns:

The end position of the element, which is the position at the end of the element’s length.

Return type:

list

field_definition: field | str | None = None

Field definition for the element, can be a field object or a string representing a file.

generate_field_file_name(param, code)

Generates a field file name based on the provided frameworkElement and tracking code.

Parameters:

• param (field) – The field object for which the field file is being generated.

• code (str) – The tracking code for which the field file is being generated (e.g., ‘elegant’, ‘ocelot’).

Returns:

The name of the field file if it exists, otherwise None.

Return type:

str | None

property get_field_amplitude: float | None

Returns the field amplitude of the element, scaled by field_scale if it exists.

Returns:

The field amplitude of the element, which is either scaled by field_scale or directly taken from field_amplitude. Returns None if field_amplitude is not defined

Return type:

float or None

get_field_reference_position()

Returns the position of the field reference point based on the field_reference_position attribute.

Returns:

The position of the field reference point, which can be ‘start’, ‘middle’, or ‘end’. If field_reference_position is not set, it defaults to the start position.

Return type:

list

Raises:

ValueError – If field_reference_position is set to an invalid value that is not ‘start’, ‘middle’, or ‘end’.

global_rotation: Tuple[float, float, float] = (0.0, 0.0, 0.0)

Global rotation of the element in the simulation [x,y,z].

gpt_ccs(ccs)

Get the GPT coordinate system for the element.

Parameters:

ccs (str) – The GPT coordinate system.

Returns:

The GPT coordinate system

Return type:

str

gpt_coordinates(position, rotation)

Get the GPT coordinates for a given position and rotation

Parameters:

• position (list) – The lattice position.

• rotation (float) – The element rotation

Returns:

A GPT-formatted position string.

Return type:

str

property k1: None

property k2: None

property k3: None

length: float = 0.0

Length of the element in the simulation, typically in meters.

property middle: list | tuple

Returns the middle position of the element, which is the center of the element’s length.

Returns:

The middle position of the element, which is the center point of the element’s length.

Return type:

list

property position_end: list | ndarray

Returns the end position of the element, which is calculated based on its starting position and length.

Returns:

The end position of the element, which is the position at the end of the element’s length.

Return type:

list

position_errors: Tuple[float, float, float] = (0.0, 0.0, 0.0)

Position errors of the element in the simulation [x,y,z].

property position_start: list

Returns the starting position of the element, which is calculated based on its center and length.

Returns:

The starting position of the element, which is the position at the beginning of the element’s length.

Return type:

list

property propertiesDict: dict

Returns a dictionary of the object’s properties, excluding disallowed keywords.

Returns:

A dictionary containing the object’s properties.

Return type:

dict

relative_position_from_centre(vec=(0, 0, 0))

Returns the position relative to the centre of the element, taking into account the element’s rotation and offset.

Parameters:

vec (tuple, optional) – A tuple representing the vector to be added to the centre position.

Returns:

The position relative to the centre of the element, adjusted for rotation and offset.

Return type:

list

relative_position_from_start(vec=(0, 0, 0))

Returns the position relative to the start of the element,

Parameters:

vec (tuple, optional) – A tuple representing the vector to be added to the start position.

Returns:

The position relative to the start of the element, adjusted for rotation and offset.

Return type:

list

rotated_position(pos=(0, 0, 0), offset=None, theta=None)

Returns the position of the element after applying a rotation and an offset.

Parameters:

• pos (tuple, optional) – A tuple representing the position to be rotated. Default is (0, 0, 0).

• offset (list, optional) – A list representing the offset to be applied to the position. If not provided, it defaults to the element’s starting offset or [0, 0, 0] if not set.

• theta (float, optional) – The rotation angle in radians to be applied to the position. If not provided, it defaults to the element’s global rotation angle.

Returns:

The rotated position of the element, adjusted for the specified offset and rotation angle. If offset is not provided, it uses the element’s starting_offset or defaults to [0, 0, 0].

Return type:

int | float | complex | list

rotation: Tuple[float, float, float], float] = (0.0, 0.0, 0.0)

Local rotation of the element in the simulation [x,y,z].

rotation_errors: Tuple[float, float, float] = (0.0, 0.0, 0.0)

Rotation errors of the element in the simulation [x,y,z].

property rotation_matrix: ndarray

Returns the rotation matrix for the element based on its global rotation angle theta.

Returns:

The rotation matrix corresponding to the global rotation angle of the element.

Return type:

np.ndarray

property start: list

Returns the starting position of the element, which is calculated based on its center and length, see position_start.

Returns:

The starting position of the element, which is the position at the beginning of the element’s length.

Return type:

list

starting_offset: Tuple[float, float, float] = (0.0, 0.0, 0.0)

Initial offset of the element, used for positioning in the simulation.

starting_rotation: Tuple[float, float, float]] = (0.0, 0.0, 0.0)

Initial rotation of the element, used for specific simulation setups.

subelement: bool = False

Flag indicating whether the element is a sub-element of a larger structure.

property theta: float

Returns the global rotation angle of the element in radians.

Returns:

The global rotation angle of the element, which is derived from global_rotation. If global_rotation is not set, it defaults to 0 radians.

Return type:

float

property tilt

Returns the local z-rotation of the element.

Returns:

The local z-rotation of the element.

Return type:

float

update_field_definition()

Updates the field definitions to allow for the relative sub-directory location

Return type:

None

wakefield_definition: field | str | None = None

Wakefield definition for the element, can be a field object or a string representing a file.

write_ASTRA(n=0, **kwargs)

Parameters:

• n (int)

• kwargs (dict)

Return type:

str

write_CSRTrack(n=0, **kwargs)

Parameters:

• n (int)

• kwargs (dict)

Return type:

str

write_Elegant()

Generates a string representation of the object’s properties in the Elegant format, see _write_Elegant().

Returns:

A formatted string representing the object’s properties in Elegant format.

Return type:

str

write_GPT(Brho, ccs='wcs', *args, **kwargs)

Parameters:

• Brho (float)

• ccs (str)

Return type:

str

write_Ocelot()

Generates an Ocelot object based on the element’s properties and type, see _write_Ocelot().

Returns:

An Ocelot object representing the element, initialized with its properties.

Return type:

object

property x: float

Returns the x-coordinate of the element’s centre.

Returns:

The x-coordinate of the element’s centre.

Return type:

float

property x_rot: float

Returns the global x-rotation of the element.

Returns:

The global x-rotation of the element.

Return type:

float

property y: float

Returns the y-coordinate of the element’s centre.

Returns:

The y-coordinate of the element’s centre.

Return type:

float

property y_rot: float

Returns the global y-rotation of the element.

Returns:

The global y-rotation of the element.

Return type:

float

property z

Returns the z-coordinate of the element’s centre.

Returns:

The z-coordinate of the element’s centre.

Return type:

float

property z_rot: float

Returns the global z-rotation of the element.

Returns:

The global z-rotation of the element.

Return type:

float

class frameworkGroup(name, elementObjects, type, elements, **kwargs)

Bases: object

Class defining a framework group, which is used to group together elements to perform coordinated actions on them.

change_Parameter(p, v)

Set a parameter on all elements in the group.

Parameters:

• p (str) – The parameter to be set

• v (Any) – The value to be set.

Return type:

None

get_Parameter(p)

Get a specific parameter associated with the group, i.e. bunch compressor angle

Parameters:

p (str) – A parameter associated with the group

Returns:

The parameter, if defined.

Return type:

Any

update(**kwargs)

class frameworkLattice(*args, **kwargs)

Bases: BaseModel

Class defining a framework lattice object, which contains all elements and groups of elements in a simulation lattice. It also contains methods to manipulate and retrieve information about the elements and groups, as well as methods to run simulations and process results.

See Creating the Lattice Elements

Parameters:

• args (Any)

• kwargs (Any)

allElements: List = []

List of all element names in the lattice.

allow_negative_drifts: bool = False

If True, allows negative drifts in the lattice.

property apertures: list

Property to get all aperture and collimator elements in the lattice.

Returns:

A list of aperture and collimator elements in the lattice.

Return type:

list

property cavities: list

Property to get all cavity elements in the lattice.

Returns:

A list of cavity elements in the lattice.

Return type:

list

createDrifts(drift_elements=('screen', 'beam_position_monitor'))

Insert drifts into a sequence of ‘elements’. This method creates drifts for elements that are not subelements and have a length greater than zero. It calculates the start and end positions of each element and creates drift elements accordingly.

Parameters:

drift_elements (tuple, optional) – A tuple of element types for which drifts should be created. Default is (“screen”, “beam_position_monitor”).

Returns:

A dictionary containing the new drift elements created for the lattice. The keys are the names of the new drift elements, and the values are the corresponding drift objects.

Return type:

dict

csrDrifts: bool = True

Flag to enable CSR drifts in the lattice.

property csr_enable: bool

Property to get or set the CSR enable flag.

property dipoles: list

Property to get all dipole elements in the lattice.

Returns:

A list of dipole elements in the lattice.

Return type:

list

property dipoles_and_kickers: list

Property to get all dipole and kicker elements in the lattice.

Returns:

A list of dipole and kicker elements in the lattice.

Return type:

list

elementObjects: Dict

Dictionary of element objects, where keys are element names and values are element instances.

property elements: dict

Property to get a dictionary of elements in the lattice.

Returns:

A dictionary where keys are element names and values are the corresponding element objects.

Return type:

dict

property end: frameworkElement

Property to get the ending element of the lattice. This method checks if the file block contains an “end_element” key or a “zstop” key. If “end_element” is present, it returns the corresponding element. If “zstop” is present, it iterates through the elementObjects to find the element with the matching end position. If no match is found, it returns the last element in the elementObjects.

Returns:

The final element of the lattice.

Return type:

frameworkElement

property endObject: frameworkElement

Property to get the final element of the lattice. See end() for more details.

Returns:

The final element of the lattice.

Return type:

frameworkElement

executables: Executables

Executable commands for running simulations, defined in the Executables class. See Executables for more details.

file_block: Dict

File block containing input and output settings for the lattice.

findS(elem)

Find the S values for a specific element in the lattice.

Parameters:

elem (str) – The name of the element to find in the lattice.

Returns:

A list of tuples, where each tuple contains the name of the element and its corresponding S value. If the element does not exist in the lattice, returns an empty list.

Return type:

list

getElement(element, param=None)

Get an element or group object by its name and optionally a specific parameter. This method checks if the element exists in the allElements dictionary or in the groupObjects dictionary. If the element exists, it returns the element object or the specified parameter of the element.

Parameters:

• element (str)

• param (str, optional) – The parameter to retrieve from the element object. If None, returns the entire element object.

Returns:

The element object or the specified parameter of the element.

Return type:

dict | frameworkElement

getElementType(typ, param=None)

Get all elements of a specific type or types from the lattice.

Parameters:

• typ (list, tuple, or str) – The type or types of elements to retrieve. If a list or tuple is provided, it retrieves elements of all specified types.

• param (list, tuple, or str, optional) – The specific parameter to retrieve from each element.

Returns:

A list or tuple of elements of the specified type(s), or a zip object if multiple parameters are specified. If param is provided, it returns the specified parameter for each element.

Return type:

list | tuple | zip

getElems(drifts=True, as_dict=False)

Get the elements in the lattice.

Parameters:

• drifts (bool, optional) – If True, includes drift elements in the list of elements.

• as_dict (bool, optional) – If True, returns a dictionary with element names as keys and their corresponding element objects as values.

Returns:

A list or dictionary of elements in the lattice.

Return type:

list | dict

getInitialTwiss()

Get the initial Twiss parameters from the file block This method checks if the file block contains an “input” key with a “twiss” subkey. If the “twiss” subkey exists and contains values, it retrieves the alpha, beta, and normalized emittance parameters for both horizontal and vertical planes.

Returns:

A dictionary containing the initial Twiss parameters for horizontal and vertical planes. If the parameters are not found, it returns False for each parameter.

Return type:

dict

getNames(drifts=True)

Get the names of the elements in the lattice.

Parameters:

drifts (bool, optional) – If True, includes drift elements in the list of names.

Returns:

A list of names of the elements in the lattice. If drifts is True, includes drift elements; otherwise, only includes main elements.

Return type:

list

getSNames()

Get the names and S values of the elements in the lattice.

Returns:

A list of tuples, where each tuple contains the name of an element and its corresponding S value.

Return type:

list

getSNamesElems()

Get the names, elements, and S values of the elements in the lattice.

Returns:

A tuple containing three elements: - A list of names of the elements. - A list of element objects. - A list of S values corresponding to the elements.

Return type:

tuple

getSValues(as_dict=False, at_entrance=False)

Get the S values for the elements in the lattice. This method calculates the cumulative length of the elements in the lattice, starting from the entrance or the first element, depending on the at_entrance parameter. It returns a list or dict of S values, which represent the positions of the elements along the lattice.

Parameters:

• as_dict (bool, optional) – If True, returns a dictionary with element names as keys and their S values as values.

• at_entrance (bool, optional) – If True, calculates S values starting from the entrance of the lattice. If False, calculates S values starting from the first element.

Returns:

A list or dictionary of S values for the elements in the lattice. If as_dict is True, returns a dictionary with element names as keys and their S values as values. If as_dict is False, returns a list of S values.

Return type:

list | dict

getZNamesElems()

Get the names, elements, and Z values of the elements in the lattice.

Returns:

A tuple containing three elements: - A list of names of the elements. - A list of element objects. - A list of Z values corresponding to the elements.

Return type:

tuple

getZValues(drifts=True, as_dict=False)

Get the Z values for the elements in the lattice. This method calculates the cumulative length of the elements in the lattice, starting from the entrance or the first element, depending on the at_entrance parameter. It returns a list or dict of S values, which represent the positions of the elements along the lattice.

Parameters:

• drifts (bool, optional) – If True, includes drift elements in the calculation. If False, only considers the main elements in the lattice.

• as_dict (bool, optional) – If True, returns a dictionary with element names as keys and their Z values as values.

Returns:

A list or dictionary of Z values for the elements in the lattice. If as_dict is True, returns a dictionary with element names as keys and their Z values as values. If as_dict is False, returns a list of Z values.

Return type:

list | dict

get_prefix()

Get the prefix from the input file block.

Returns:

The prefix string used in the input file block.

Return type:

str

globalSettings: Dict = {'charge': None}

Global settings for the lattice, including charge and other parameters.

global_parameters: Dict

Global parameters for the lattice, including master subdirectory and other configuration settings.

groupObjects: Dict

Dictionary of group objects, where keys are group names and values are group instances.

groupSettings: Dict = {}

Group settings for the lattice, including group-specific parameters.

initial_twiss: Dict = {}

Initial Twiss parameters for the lattice, used for tracking and analysis.

insert_element(index, element)

Insert an element at a specific index in the elements dictionary.

Parameters:

• index (int) – The index at which to insert the element.

• element (SimulationFramework.Framework_objects.frameworkElement) – The element to insert into the elements dictionary.

Return type:

None

property kickers: list

Property to get all kicker elements in the lattice.

Returns:

A list of kicker elements in the lattice.

Return type:

list

property lines: list

Property to get all lines in the lattice.

Returns:

A list of lines in the lattice.

Return type:

list

lscDrifts: bool = True

Flag to enable LSC drifts in the lattice.

lsc_bins: int = 20

Number of bins for LSC drifts.

lsc_high_frequency_cutoff_end: float = -1

Spatial frequency at which smoothing filter is 0. See Elegant manual LSC drift

lsc_high_frequency_cutoff_start: float = -1

Spatial frequency at which smoothing filter begins. If not positive, no frequency filter smoothing is done. See Elegant manual LSC drift

lsc_low_frequency_cutoff_end: float = -1

Lowest spatial frequency at which low-frequency cutoff filter is 1. See Elegant manual LSC drift

lsc_low_frequency_cutoff_start: float = -1

Highest spatial frequency at which low-frequency cutoff filter is zero. See Elegant manual LSC drift

name: str

Name of the lattice, used as a prefix for output files and commands.

objectname: str | None = ''

Name of the lattice, used as a prefix for output files and commands.

objecttype: str | None = ''

Type of the lattice, used as a prefix for output files and commands.

postProcess()

preProcess()

Pre-process the lattice before running the simulation. This method initializes the initial Twiss parameters by calling the getInitialTwiss method.

Return type:

None

prefix(prefix)

Parameters:

prefix (str)

Return type:

None

property quadrupoles: list

Property to get all quadrupole elements in the lattice.

Returns:

A list of quadrupole elements in the lattice.

Return type:

list

run()

Run the code with input ‘filename’ This method constructs the command to run the simulation using the specified executable and the name of the lattice. It redirects the output to a log file in the master subdirectory.

Raises:

FileNotFoundError – If the executable for the specified code is not found in the executables dictionary.

Return type:

None

runSettings: runSetup

Run settings for the lattice, including number of runs and random seed.

sample_interval: int = 1

Sample interval for downsampling particles, in units of 2**(3*sample_interval)

property screens: list

Property to get all screen elements in the lattice.

Returns:

A list of screen elements in the lattice.

Return type:

list

property screens_and_bpms: list

Property to get all screen and BPM elements in the lattice.

Returns:

A list of screen and BPM elements in the lattice.

Return type:

list

property screens_and_markers_and_bpms: list

Property to get all screen and BPM and marker elements in the lattice.

Returns:

A list of screen and BPM and marker elements in the lattice.

Return type:

list

setElementType(typ, setting, values)

Set a specific setting for all elements of a specific type or types in the lattice.

Parameters:

• typ (list, tuple, or str) – The type or types of elements to set the setting for.

• setting (str) – The setting to be updated for the elements. This can be a single setting or a list of settings.

• values (list, tuple, or Any) – The values to set for the specified setting.

Raises:

ValueError – If the number of elements of the specified type does not match the number of values provided.

Return type:

None

set_prefix(prefix)

Set the prefix for the input file block.

Parameters:

prefix (str) – The prefix string used in the input file block.

Return type:

None

settings: FrameworkSettings

Instance of FrameworkSettings

property solenoids: list

Property to get all solenoid elements in the lattice.

Returns:

A list of solenoid elements in the lattice.

Return type:

list

property start: frameworkElement

Property to get the starting element of the lattice. This method checks if the file block contains a “start_element” key or a “zstart” key. If “start_element” is present, it returns the corresponding element. If “zstart” is present, it iterates through the elementObjects to find the element with the matching start position. If no match is found, it returns the first element in the elementObjects.

Returns:

The starting element of the lattice.

Return type:

frameworkElement

property startObject: frameworkElement

Property to get the starting element of the lattice. See start() for more details.

Returns:

The starting element of the lattice.

Return type:

frameworkElement

updateRunSettings(runSettings)

Update the run settings for the lattice.

Parameters:

runSettings (runSetup) – An instance of runSetup containing the new run settings.

Raises:

TypeError – If the runSettings argument is not an instance of runSetup.

Return type:

None

update_groups()

Update the group objects in the lattice with their settings.

Return type:

None

property wakefields: list

Property to get all wakefield elements in the lattice.

Returns:

A list of wakefield elements in the lattice.

Return type:

list

property wakefields_and_cavity_wakefields: list

Property to get all wakefield and cavity wakefield elements in the lattice.

Returns:

A list of wakefield and cavity wakefield elements in the lattice.

Return type:

list

write()

class frameworkObject(*args, **kwargs)

Bases: BaseModel

Class defining a framework object, which is the base class for all elements in a simulation lattice. It provides methods to add properties, validate parameters, and handle various simulation-specific functionalities.

Parameters:

• args (Any)

• kwargs (Any)

add_default(key, value)

Add a default value for a property of the object, updating objectdefaults.

Parameters:

• key (str) – The name of the property to set a default value for.

• value (Any) – The name of the property to set a default value for and the value to set.

Return type:

None

add_properties(**keyvalues)

Add multiple properties to the object by setting attributes for each key-value pair.

Parameters:

**keyvalues (dict) – A dictionary of key-value pairs where keys are property names and values are the corresponding values to set.

Return type:

None

add_property(key, value)

Add a property to the object by setting an attribute if the key is allowed.

Parameters:

• key (str) – The name of the property to add.

• value (Any) – The value to set for the property.

Return type:

None

allowedkeywords: Union[List, Dict] = {}

List of allowed keywords for the object, which defines what properties can be set.

change_Parameter(key, value)

Change a parameter of the object by setting an attribute.

Parameters:

• key (str) – The name of the parameter to change.

• value (Any) – The new value to set for the parameter.

Return type:

None

global_parameters: Dict = {}

Global parameters to be cascaded through all objects.

objectdefaults: Dict = {}

Default values for the object’s properties, used when no specific value is provided.

property objectproperties

Returns a dictionary of the object’s properties, excluding disallowed keywords.

Returns:

The object itself, allowing for method chaining.

Return type:

frameworkObject

property parameters: list

Returns a list of all parameters (keys) of the object.

Returns:

A list of keys representing the parameters of the object.

Return type:

list

validate_objectname()

Validate the objectname to ensure it is a string.

validate_objecttype()

Validate the objecttype to ensure it is a string.

class getGrids

Bases: object

Class defining the appropriate number of space charge bins given the number of particles, defined as the closest power of 8 to the cube root of the number of particles.

find_nearest(array, value)

Get the nearest value in an array to the value provided; in this case the array should be a list of powers of 8.

Parameters:

• array (np.ndarray or list) – Array of values to be checked

• value (Value to be found in the array)

Returns:

The closest value in array to value

Return type:

int

getGridSizes(x)

Calculate the 3D space charge grid size given the number of particles, minimum of 4

Parameters:

x (PositiveInt) – Number of particles

Returns:

The number of space charge grids

Return type:

int

has_symlink_privilege()

class lscdrift(*args, **kwargs)

Bases: csrdrift

Class defining a drift including LSC effects.

Parameters:

• args (Any)

• kwargs (Any)

class r56_group(name, elementObjects, type, elements, ratios, keys, **kwargs)

Bases: frameworkGroup

Class defining a group of elements with a total R56.

get_Parameter(p)

Get a parameter associated with the group.

Parameters:

p (str) – The parameter to be retrieved.

Returns:

The parameter.

Return type:

Any

property r56: float

Get the R56 of the group of elements

Returns:

The R56 pararmeter

Return type:

float

updateElements(element, key, value)

Update one or more elements in the group.

Parameters:

• element (str, list or tuple) – The element(s) to be updated

• key (str) – The parameter in the element or group of elements to be changed

• value (Any) – The value to which the parameter should be set

Return type:

None

class runSetup

Bases: object

Class defining settings for simulations that include multiple runs such as error studies or parameter scans.

loadElementErrors(file)

Load error definitions from a file or dictionary and assign them to the elementErrors attribute. This method can handle both a YAML file and a dictionary containing error definitions.

Parameters:

file (str or dict) –

• str: Path to a YAML file containing error definitions.

• dict: A dictionary containing error definitions.

Return type:

None

setElementScan(name, item, scanrange, multiplicative=False)

Define a parameter scan for a single parameter of a given machine element

Parameters:

• name (str) – Name of the machine element to be scanned.

• item (str) – Name of the item (parameter) to be scanned within the machine element.

• scanrange (list or tuple or np.ndarray) – A list or tuple containing two floats, representing the minimum and maximum values of the scan range.

• multiplicative (bool, optional) – If True, the scan will be multiplicative; otherwise, it will be additive. Default is False.

Return type:

None

setNRuns(nruns)

Sets the number of simulation runs to a new value.

Parameters:

nruns (int or float) – The number of runs to set. If a float is passed, it will be converted to an integer.

Raises:

TypeError – If nruns is not an integer or float.

Return type:

None

setSeedValue(seed)

Sets the random number seed to a new value for all lattice objects

Parameters:

seed (int or float) – The random number seed to set. If a float is passed, it will be converted to an integer.

Raises:

TypeError – If seed is not an integer or float.

Return type:

None

class s_chicane(name, elementObjects, type, elements, **kwargs)

Bases: chicane

Class defining an s-type chicane; in this case the bending ratios for set_angle() are different.