simba.Modules.Twiss package

Submodules

simba.Modules.Twiss.astra module

cumtrapz(x=[], y=[])

interpret_astra_data(self, lattice_name, xemit, yemit, zemit)

Return type:

None

read_astra_twiss_files(self, filename, reset=True)

Return type:

None

simba.Modules.Twiss.cheetah module

cumtrapz(x=[], y=[])

Parameters:

• x (list | ndarray)

• y (list | ndarray)

read_cheetah_twiss_files(self, filename, reset=True)

simba.Modules.Twiss.elegant module

read_elegant_floor_file(self, filename, offset=[0, 0, 0], rotation=[0, 0, 0], reset=True)

read_elegant_twiss_files(self, filename, startS=0, reset=True)

simba.Modules.Twiss.gpt module

read_gdf_emit_file_object(self, file)

read_gdf_twiss_files(self, filename=None, gdfbeam=None, reset=True)

simba.Modules.Twiss.hdf5 module

read_HDF5_twiss_file(self, filename)

read_hdf_summary(self, filename, reset=True)

write_HDF5_twiss_file(self, filename, sourcefilename=None, version=2)

simba.Modules.Twiss.ocelot module

cumtrapz(x=[], y=[])

interpret_ocelot_data(self, lattice_name, fdat)

read_ocelot_twiss_files(self, filename, reset=True)

read_ocelot_twiss_files_hdf(self, filename, reset=True)

save_ocelot_twiss_hdf(self, filename, twiss={})

Parameters:

• filename (str)

• twiss (dict)

simba.Modules.Twiss.opal module

cumtrapz(x=[], y=[])

read_opal_twiss_files(self, filename, startS=0, reset=True)

simba.Modules.Twiss.plot module

plot(twiss_object, ykeys=['sigma_x', 'sigma_y'], ykeys2=['sigma_z'], xkey='z', xlim=None, nice=True, include_labels=True, include_legend=True, **kwargs)

Plots stat output multiple keys.

If a list of ykeys2 is given, these will be put on the right hand axis. This can also be given as a single key.

Logical switches, all default to True:

nice: a nice SI prefix and scaling will be used to make the numbers reasonably sized.

include_legend: The plot will include the legend

include_labels: the layout will include element labels.

Copied almost verbatim from lume-impact’s Impact.plot.plot_stats_with_layout

simba.Modules.Twiss.xsuite module

interpret_xsuite_data(self, lattice_name, fdat)

read_xsuite_twiss_files(self, filename, reset=True)

Module contents

Simframe Twiss Module

Twiss module for reading and manipulating twiss parameters from various simulation codes.

Classes:

• twiss: Twiss object class

class initialTwiss(*args, **kwargs)

Bases: BaseModel

A class to represent the initial twiss parameters of a beam.

Parameters:

• args (Any)

• kwargs (Any)

alpha_x: float

The alpha parameter in the x-direction.

alpha_y: float

The alpha parameter in the y-direction.

beta_x: float

The beta parameter in the x-direction.

beta_y: float

The beta parameter in the y-direction.

enx: float

The normalized horizontal emittance.

eny: float

The normalized vertical emittance.

eta_x: float

The horizontal dispersion.

eta_xp: float

The horizontal dispersion derivative.

eta_y: float

The vertical dispersion.

eta_yp: float

The vertical dispersion derivative.

ex: float

The horizontal emittance.

ey: float

The vertical emittance.

load_directory(directory='.', types={'ASTRA': 'Xemit.001', 'GPT': 'emit.gdf', 'cheetah': '_twiss.cheetah.hdf5', 'elegant': '.twi', 'genesis': '.out.h5', 'ocelot': '_twiss.npz', 'ocelot_h5': '_twiss.oh5', 'opal': 'opal_twiss.h5', 'xsuite': '_twiss.csv'}, preglob='*', verbose=False, sortkey='z')

Load in all Twiss output files from a directory and create a twiss object.

Parameters:

• directory (str) – Directory from which to load the files

• types (Dict) – Codes and their file extensions

• preglob (str) – String for file pattern matching

• verbose (bool) – If true, print progress

• sortkey (str) – Key by which to sort Twiss parameters

Returns:

A new twiss object.

Return type:

twiss

load_file(filename, *args, **kwargs)

class twiss(*args: Any, **kwargs: Any)

Bases: BaseModel

A class to represent the twiss parameters of a beam in a simulation framework. This class includes various twiss parameters such as position, time, kinetic energy, momentum, emittance, beta functions, and dispersion parameters.

It also provides methods to read twiss data from different simulation codes (e.g., ELEGANT, GPT, ASTRA, Ocelot), save twiss data to HDF5 files, and perform various operations such as interpolation, sorting, and extracting values. The class is designed to be flexible and extensible, allowing for the addition of new parameters and methods as needed.

E0: float = 8.187105776823886e-14

The rest energy of the particle, in Joules. Default is the electron rest mass energy.

E0_eV: float = 510998.9499961642

The rest energy of the particle, in eV. Default is the electron rest mass energy in eV.

alpha_x: twissParameter = None

The alpha function in the x-direction.

alpha_x_beam: twissParameter = None

The alpha function in the x-direction, specifically for beam parameters.

alpha_y: twissParameter = None

The alpha function in the y-direction.

alpha_y_beam: twissParameter = None

The alpha function in the y-direction, specifically for beam parameters.

alpha_z: twissParameter = None

The alpha function in the z-direction.

append(array, data)

Append data to a specified twiss parameter array.

Parameters:

• array (str) – Name of existing Twiss parameter array

• data (List | np.ndarray) – Data to append

Return type:

None

beta_x: twissParameter = None

The beta function in the x-direction.

beta_x_beam: twissParameter = None

The beta function in the x-direction, specifically for beam parameters.

beta_y: twissParameter = None

The beta function in the y-direction.

beta_y_beam: twissParameter = None

The beta function in the y-direction, specifically for beam parameters.

beta_z: twissParameter = None

The beta function in the z-direction.

code_signatures: List[List[str]] = [['elegant', '.twi'], ['elegant', '.flr'], ['elegant', '.sig'], ['GPT', 'emit.gdf'], ['astra', 'Xemit.001'], ['ocelot', '_twiss.npz'], ['opal', 'opal_twiss.h5'], ['ocelot_h5', '_twiss.oh5'], ['cheetah', '_twiss.cheetah.hdf5'], ['genesis', '.out.h5'], ['xsuite', '_twiss.csv']]

A list of code signatures to identify twiss files from different simulation codes.

codes: Dict = {'astra': <function read_astra_twiss_files>, 'cheetah': <function read_cheetah_twiss_files>, 'elegant': <function read_elegant_twiss_files>, 'genesis': <function read_genesis_twiss_files>, 'gpt': <function read_gdf_twiss_files>, 'ocelot': <function read_ocelot_twiss_files>, 'ocelot_h5': <function read_ocelot_twiss_files_hdf>, 'opal': <function read_opal_twiss_files>, 'xsuite': <function read_xsuite_twiss_files>}

A dictionary of functions to read twiss data from different simulation codes.

covariance(u, up)

Calculate the covariance between two twiss parameters.

Parameters:

• u (array-like) – First Twiss parameter set

• up (array-like) – Second Twiss parameter set

Returns:

The covariance between the two twiss parameters. The covariance is calculated as the mean of the product of the deviations from their means. If the input arrays are empty, it returns NaN.

Return type:

float

cp: twissParameter = None

The momentum of the beam in eV/c.

ecnx: twissParameter = None

The normalized horizontal emittance of the beam, in m-mrad.

ecny: twissParameter = None

The normalized vertical emittance of the beam, in m-mrad.

elegantData: Dict = {}

A dictionary to store ELEGANT data.

elegantTwiss: Dict = {}

A dictionary to store ELEGANT twiss data.

element_name: twissParameter = None

The name of the element in the simulation.

enx: twissParameter = None

The normalized horizontal emittance of the beam.

eny: twissParameter = None

The normalized vertical emittance of the beam.

enz: twissParameter = None

The normalized longitudinal emittance of the beam, typically in eV*s.

eta_x: twissParameter = None

The horizontal dispersion of the beam.

eta_x_beam: twissParameter = None

The horizontal dispersion of the beam, specifically for beam parameters.

eta_xp: twissParameter = None

The horizontal dispersion derivative of the beam.

eta_xp_beam: twissParameter = None

The horizontal dispersion derivative of the beam, specifically for beam parameters.

eta_y: twissParameter = None

The vertical dispersion of the beam.

eta_y_beam: twissParameter = None

The vertical dispersion of the beam, specifically for beam parameters.

eta_yp: twissParameter = None

The vertical dispersion derivative of the beam.

eta_yp_beam: twissParameter = None

The vertical dispersion derivative of the beam, specifically for beam parameters.

ex: twissParameter = None

The horizontal emittance of the beam.

extract_values(name, start, end)

Extract values from a specified twiss parameter array between two z positions.

Parameters:

• name (str) – Name of Twiss parameter

• start (float) – Initial z position

• end (float) – Final z position

Returns:

An array of values from the specified twiss parameter array between the start and end z positions.

Return type:

np.ndarray

ey: twissParameter = None

The vertical emittance of the beam.

ez: twissParameter = None

The longitudinal emittance of the beam, typically in eV*s.

find_nearest(array, value)

Find the nearest value in a sorted array to a given value.

Parameters:

• array (List) – A sorted array to search within.

• value (float) – The value to find the nearest element for in the array.

Returns:

The value in the array

Return type:

float

find_nearest_idx(array, value)

Find the index of the nearest value in a sorted array.

Parameters:

• array (List) – A sorted array to search within.

• value (float) – The value to find the nearest index for in the array.

Returns:

The index of the nearest value in the array. If the value is exactly equal to an element, it returns that index. If the value is less than the first element, it returns 0. If the value is greater than the last element, it returns the last index.

Return type:

int

gamma: twissParameter = None

The Lorentz factor of the beam, defined as E/mc^2.

gamma_x: twissParameter = None

The twiss gamma function in the x-direction.

gamma_y: twissParameter = None

The twiss gamma function in the y-direction.

gamma_z: twissParameter = None

The twiss gamma function in the z-direction.

get_parameter_at_element(param, element_name)

Get the value of a twiss parameter at a specific element name.

Parameters:

• param (str) – The Twiss parameter of interest

• element_name (str) – The element name

Returns:

The value of the specified twiss parameter at the given element name. If the element name is found, it returns the corresponding value; otherwise, it returns None.

Return type:

float | None

get_parameter_at_z(param, z, tol=0.001)

Get the value of a twiss parameter at a specific z position.

Parameters:

• param (str) – The name of the Twiss parameter

• z (float) – The z position of interest

• tol (float, optional) – The z-position tolerance

Returns:

The value of the specified twiss parameter at the given z position. If z is exactly in the list of z positions, it returns the corresponding value. If z is not found, it finds the nearest z position and checks if it’s within the tolerance. If it is, it returns the corresponding value; otherwise, it interpolates the value.

Return type:

float

get_twiss_at_element(element_name, before=False)

Get the twiss parameters at a specific element name.

Parameters:

• element_name (str) – The name of the element

• before (bool) – Get the parameters before the specified element

Returns:

A dictionary of twiss parameters at the specified element name. If the element name is found, it returns the corresponding twiss parameters; otherwise, it returns None. If before is True, it returns the parameters before the specified element.

Return type:

Dict[str, float] | None

get_twiss_at_z(z, tol=0.001)

Get the twiss parameters at a specific z position.

Parameters:

• z (float) – The z-position of interest

• tol (float, optional) – Tolerance on the z-position

Returns:

A dictionary of twiss parameters at the specified z position. If z is exactly in the list of z positions, it returns the corresponding twiss parameters. If z is not found, it finds the nearest z position and checks if it’s within the tolerance. If it is, it returns the corresponding twiss parameters; otherwise, it interpolates the values.

Return type:

Dict[str, float]

get_twiss_dict(idx)

Get a dictionary of twiss parameters at a specific index.

Parameters:

idx (int) – The index in the Twiss parameter list

Returns:

A dictionary containing the twiss parameters at the specified index. The keys are the parameter names, and the values are the corresponding values at that index.

Return type:

Dict[str, float]

classmethod initialise_directory(*args, **kwargs)

interpolate(z=None, value='z', index='z')

Interpolate a value at a given z position based on the twiss parameters.

Parameters:

• z (float or None, optional)

• value (str, optional)

• index (str, optional)

Returns:

The interpolated value at the specified z position. If z is None, it returns the interpolated value for the entire range. If z is greater than the maximum value in the index, it returns a large number (10^6). Otherwise, it returns the interpolated value at the specified z position.

Return type:

float

kinetic_energy: twissParameter = None

The kinetic energy of the beam.

lattice_name: twissParameter = None

The name of the lattice in the simulation.

load_directory(directory='.', types={'ASTRA': 'Xemit.001', 'GPT': 'emit.gdf', 'cheetah': '_twiss.cheetah.hdf5', 'elegant': '.twi', 'genesis': '.out.h5', 'ocelot': '_twiss.npz', 'opal': 'opal_twiss.h5', 'xsuite': '_twiss.csv'}, preglob='*', verbose=False, sortkey='z')

Load twiss files from a specified directory based on the provided types and preglob pattern.

Parameters:

• directory (str) – The directory to load

• types (Dict[str, str]) – Keys for codes and the Twiss file extensions that they produce

• preglob (str) – Territorial globbing

• verbose (bool, optional) – Print out status of loading

• sortkey (str, optional) – Sort Twiss data by the key provided

Returns:

The twiss object with the loaded twiss parameters. The method reads twiss files from the specified directory, processes them based on the types, and sorts the parameters based on the specified sortkey.

Return type:

twiss

mean_cp: twissParameter = None

The mean value of the beam momentum in eV/c.

mean_x: twissParameter = None

The mean position of the beam in the x-direction.

mean_y: twissParameter = None

The mean position of the beam in the y-direction.

mux: twissParameter = None

The horizontal phase advance of the beam, in units of 2 pi.

muy: twissParameter = None

The vertical phase advance of the beam, in units of 2 pi.

p: twissParameter = None

The momentum of the beam in kg*m/s, calculated as cp * q_over_c.

plot(*args, **kwargs)

property properties

q_over_c: float = 5.344285992678308e-28

The charge over the speed of light, used for momentum calculations.

read_GPT_twiss_files(*args, **kwargs)

Return type:

None

read_HDF5_twiss_file(*args, **kwargs)

Return type:

None

read_astra_twiss_files(*args, **kwargs)

Return type:

None

read_cheetah_twiss_files(*args, **kwargs)

read_elegant_twiss_files(*args, **kwargs)

Return type:

None

read_gdf_twiss_files(*args, **kwargs)

Return type:

None

read_genesis_twiss_files(*args, **kwargs)

Return type:

None

read_ocelot_twiss_files(*args, **kwargs)

Return type:

None

read_ocelot_twiss_files_hdf(*args, **kwargs)

Return type:

None

read_opal_twiss_files(*args, **kwargs)

Return type:

None

read_sdds_file(filename, ascii=False)

Read an SDDS file and extract the twiss parameters. #TODO deprecated????

Parameters:

• filename (str) – SDDS filename

• ascii (bool, optional) – Convert to ascii

Returns:

A dictionary containing the twiss parameters extracted from the SDDS file. The dictionary is stored in the elegantTwiss attribute of the twiss object.

Return type:

Dict[str, float]

read_xsuite_twiss_files(*args, **kwargs)

Return type:

None

reset_dicts()

Reset the twiss parameters to their initial state. This method initializes all twiss parameters to their default values and clears the elegantTwiss dictionary. This is useful for starting fresh with a new set of twiss parameters or when reloading data.

Return type:

None

rest_mass: float | None = None

The rest mass of the particle, in kg. If None, it will be set to the electron rest mass.

s: twissParameter = None

The longitudinal position of the beam in the simulation.

save_HDF5_twiss_file(*args, **kwargs)

Return type:

None

sddsindex: int = 0

An index for SDDS files, used to track the current file being processed.

set_E0(value)

Set the rest energy of the particle.

Parameters:

• value (float) – The rest energy in Joules to set for the particle.

• Returns

• -----------

• None

Return type:

None

sigma_cp: twissParameter = None

The standard deviation of the beam momentum in eV/c.

sigma_p: twissParameter = None

The standard deviation of the beam momentum in kg*m/s.

sigma_t: twissParameter = None

The standard deviation of the beam in time.

sigma_x: twissParameter = None

The standard deviation of the beam in the x-direction.

sigma_xp: twissParameter = None

The standard deviation of the beam in the xp-direction.

sigma_y: twissParameter = None

The standard deviation of the beam in the y-direction.

sigma_yp: twissParameter = None

The standard deviation of the beam in the yp-direction.

sigma_z: twissParameter = None

The standard deviation of the beam in the z-direction.

sort(key='s', reverse=False)

Sort the twiss parameters based on a specified key. This method sorts the twiss parameters in ascending order by default, or in descending order if reverse is set to True. The sorting is done based on the values of the specified key, which should be one of the twiss parameters (e.g., ‘z’, ‘beta_x’, etc.). If the key is not found, it raises an AttributeError.

Parameters:

• key (str) – The key by which to sort all the Twiss parameters

• reverse (bool, optional) – Reverse the Twiss parameter arrays

Return type:

None

stat(key)

Get the value of a twiss parameter by its key.

Parameters:

• key (str) – The key of the twiss parameter to retrieve, e.g., ‘z’, ‘beta_x’, etc.

• Returns

• -----------

• twissParameter – The value of the twiss parameter associated with the given key.

Return type:

twissParameter

t: twissParameter = None

The time coordinate of the beam in the simulation.

validate_fields(values)

z: twissParameter = None

The longitudinal position of the beam in the simulation.

class twissParameter(*args, **kwargs)

Bases: BaseModel

A class to represent a twiss parameter with its name, unit, value, label, and data type. This class is used to store and validate twiss parameters in the simulation framework.

Parameters:

• args (Any)

• kwargs (Any)

default_label()

dtype: str = 'f'

The data type of the twiss parameter, default is ‘f’ (float).

max()

Return type:

float

min()

Return type:

float

name: str

The name of the twiss parameter, e.g., ‘z’, ‘beta_x’, etc.

unit: str

The unit of the twiss parameter, e.g., ‘m’, ‘s’, ‘eV’, etc.

val: List = []

The value of the twiss parameter, stored as a list.