simba.Codes.Ocelot package

Submodules

simba.Codes.Ocelot.Ocelot module

SIMBA Ocelot Module

Various objects and functions to handle OCELOT lattices and commands. See Ocelot github for more details.

Classes:

• ocelotLattice: The Ocelot lattice object, used for

converting the frameworkObject s defined in the frameworkLattice into an Ocelot lattice object, and for tracking through it.

class ocelotLattice(*args, **kwargs)

Bases: frameworkLattice

Class for defining the OCELOT lattice object, used for converting the frameworkLattice into an Ocelot lattice object, and for tracking through it.

Parameters:

• args (Any)

• kwargs (Any)

code: str = 'ocelot'

String indicating the lattice object type

final_screen: Any = None

Final screen object

grids: getGrids = None

Class for calculating the required number of space charge grids

hdf5_to_npz(prefix='', write=True)

Convert the initial HDF5 particle distribution to Ocelot format and set pin accordingly.

Parameters:

• prefix (str) – Prefix for particle file

• write (bool) – Flag to indicate whether to save the file

Return type:

None

lat_obj: Any = None

Lattice object as an Ocelot MagneticLattice

lsc: bool = True

Flag to enable LSC calculations

mbi: Dict = {}

Dictionary containing settings for microbunching gain calculation

mbi_navi: Optional[Any] = None

Physics process for calculating microbunching gain

mbin_csr: int = 5

Number of macroparticle bins for CSR calculations

names: List = None

Names of elements in the lattice

navi_setup()

Set up the physics processes for Ocelot (i.e. space charge, CSR, wakes etc).

Returns:

An Ocelot Navigator object

Return type:

Navigator

nbin_csr: int = 10

Number of longitudinal bins for CSR calculations

oceglobal: Dict = {}

Global settings for Ocelot, read in from ocelotLattice.settings[“global”][“OCELOTsettings”] and ocelot_defaults.yaml

particle_definition: str = None

Initial particle distribution as a string

physproc_beamtransform(tws)

Get an Ocelot `BeamTransform`_ physics process based on the wakefield provided.

Parameters:

tws (Ocelot Twiss object) – Object containing Twiss parameters

Returns:

A BeamTransform PhysProc

Return type:

tuple

physproc_csr()

Get Ocelot CSR physics processes based on the start and end positions provided in file_block. If these are not provided, just include CSR for the entire lattice.

Returns:

A list of CSR PhysProcs, and their start and end positions

Return type:

tuple

physproc_lsc()

Get an Ocelot `LSC`_ physics process

Returns:

The Ocelot LSC PhysProc

Return type:

LSC

physproc_sc(grids)

Get an Ocelot SpaceCharge physics process

Parameters:

grids (List[int]) – The space charge grid number in x,y,z

Returns:

The Ocelot SpaceCharge PhysProc

Return type:

SpaceCharge

physproc_wake(name, loc, ncell)

Get an Ocelot `Wake`_ physics process based on the wakefield provided.

Parameters:

• name (str) – Name of lattice object associated with the wake

• loc (field or str) – If field, then write the field file to ASTRA format

• ncell (int) – Number of cells, which provides a multiplication factor for the wake

Returns:

A Wake PhysProc, and its index in the lattice

Return type:

tuple

pin: Any = None

Initial particle distribution as an Ocelot ParticleArray

postProcess()

Convert the outputs from Ocelot to HDF5 format and save them to master_subdir.

Return type:

None

pout: Any = None

Final particle distribution as an Ocelot ParticleArray

preProcess()

Get the initial particle distribution defined in file_block[‘input’][‘prefix’] if it exists.

Return type:

None

random_mesh: bool = True

Random meshing for space charge calculations

ref_idx: int = None

Reference particle index

ref_s: float = None

Reference s position

run()

Run the code, and set tws and pout

Return type:

None

screen_threaded_function

Function for converting all screen outputs from ELEGANT into the SIMBA generic beam object and writing files

alias of ScatterGatherDescriptor

sigmamin_csr: float = 1e-05

Minimum size for CSR calculations

smooth_param: float = 0.01

Smoothing parameter

trackBeam: bool = True

Flag to indicate whether to track the beam

tws: List = None

List containing Ocelot Twiss objects

unit_step: float = 0.01

Step for Ocelot PhysProc objects

wake_factor: float = 1.0

Multiplication factor for wakefields

wake_filter: int = 10

Filter parameter for wake calculations

wake_sampling: int = 1000

Number of samples for wake calculations

write()

Create the lattice object via writeElements() and save it as a python file to master_subdir.

Return type:

None

writeElements()

Create Ocelot objects for all the elements in the lattice and set the lat_obj and names.

Return type:

None

simba.Codes.Ocelot.mbi module

@author: Alex Brynes Created on 09.12.2024

class MBI(lattice, step=1, lamb_range=(1e-06, 5e-05, 10), slices=0, lsc=True, csr=True)

Bases: PhysProc

Microbunching Gain (MBI) calculation physics process

The beam bunching factor is calculated sequentially along the beamline, following Tsai et al. [All equations referenced herein refer to this paper.] At each simulation step, the bunch slice properties and lattice transfer map up to that point are extracted. The bunching factor in the absence of collective effects – b0 – is also calculated. Based on these parameters, the microbunching integral kernel at each previous step is evaluated and multiplied with b0. The bunching factor at a given location z is then the sum of all previous bunching factors. These bunching factors [bf, pf] are then made attributes of the ~ocelot.cpbd.beam.ParticleArray object.

lattice

MagneticLattice Lattice used during tracking

step

int [in Navigator.unit_step] step of the MBI calculation

lamb_range

tuple Initial wavelength modulation range (metres) [min, max, num_steps]

slices

int

Number of time-slices across which to calculate beam slice properties

Type:

zero takes only the central slice

lsc

bool Include LSC impedance

csr

bool Include CSR impedance

Parameters:

• lattice (MagneticLattice)

• step (float)

• lamb_range (list)

• slices (int)

• lsc (bool)

• csr (bool)

apply(p_array, dz)

Apply MBI calculation. Calculates beam slice parameters and optics map, used as input to ~get_bf or ~get_bf_slice. Then updates self.bf and self.pf.

Parameters:

• p_array (ParticleArray) – particle array object

• dz (float) – step

Return type:

None

csrimpedance(lamb, elem)

CSR impedance (Eq. (51))

Parameters:

• lamb (float) – initial modulation wavelength

• elem (Element) – Ocelot element object

Return type:

float

Returns:

CSR impedance

get_bf(lamb_range, slice_params, optics_map, elem)

Calculate bunching factor at the current position (see Eq. (58))

Parameters:

• lamb_range (list) – range of initial modulation wavelengths [m]

• slice_params (list) – list of dicts containing beam slice properties

• optics_map (list) – list of first-order transfer matrices

• elem (Element) – Ocelot element at the current position

Return type:

list

Returns:

bunching factors in z and p

get_bf_slice(lamb_range, slice_params, optics_map, slices, elem)

Calculate bunching factor at the current position (see Eq. (58)) across longitudinal bunch slices

Parameters:

• lamb_range (list) – range of initial modulation wavelengths [m]

• slice_params (list) – list of dicts containing beam slice properties

• optics_map (list) – list of first-order transfer matrices

• slices (int) – number of slices over which to calculate beam slice properties and bunching factors

• elem (Element) – Ocelot element at the current position

Return type:

list

Returns:

bunching factors in z and p

get_slice_params(p_array, slices=False)

Calculate beam slice parameters

Parameters:

• p_array (ParticleArray) – Particle array object

• slices (bool) – if true, calculate beam properties along the full slice; if false, calculate slice properties of the central slice

Return type:

dict

Returns:

dictionary containing relevant slice parameters obtained from Ocelot global slice analysis

kernel_K0(lamb, slice_params, optics_map, i1, elem)

Kernel K0 (Eq. (A17a))

Parameters:

• lamb (float) – initial modulation wavelength [m]

• slice_params (list) – list of dicts containing beam slice properties

• optics_map (list) – list of first-order transfer matrices

• i1 (int) – index from which to calculate

• elem (Element) – Ocelot element at the current position

Return type:

float

Returns:

K0

kernel_K1(lamb, slice_params, optics_map, i1, elem)

Kernel K1 (Eq. (A17b))

Parameters:

• lamb (float) – initial modulation wavelength [m]

• slice_params (list) – list of dicts containing beam slice properties

• optics_map (list) – list of first-order transfer matrices

• i1 (int) – index from which to calculate

• elem (Element) – Ocelot element at the current position

Return type:

float

Returns:

K1

kernel_K2(lamb, slice_params, optics_map, i1, elem)

Kernel K2 (Eq. (A17c))

Parameters:

• lamb (float) – initial modulation wavelength [m]

• slice_params (list) – list of dicts containing beam slice properties

• optics_map (list) – list of first-order transfer matrices

• i1 (int) – index from which to calculate

• elem (Element) – Ocelot element at the current position

Return type:

float

Returns:

K2

kernels(lamb, slice_params, optics_map, i1, elem)

Kernels (Eq. (A17a + b))

Parameters:

• lamb (float) – initial modulation wavelength [m]

• slice_params (list) – list of dicts containing beam slice properties

• optics_map (list) – list of first-order transfer matrices

• i1 (int) – index from which to calculate

• elem (Element) – Ocelot element at the current position

Return type:

list

Returns:

K0, K1, K2

ld0s(lamb, slice_params, optics_map)

Landau damping between first lattice point and subsequent points (Eq. (46))

Parameters:

• lamb (list) – initial modulation wavelength [m]

• slice_params (list) – list of dicts containing beam slice properties

• optics_map (list) – list of first-order transfer matrices

Return type:

float

Returns:

Landau damping factor LD(0->s)

ldtaus(lamb, slice_params, optics_map, i1)

Landau damping between two lattice elements (Eq. (50))

Parameters:

• lamb (list) – initial modulation wavelength [m]

• slice_params (list) – list of dicts containing beam slice properties

• optics_map (list) – list of first-order transfer matrices

• i1 (int) – index from which to calculate

Return type:

float

Returns:

Landau damping factor LD(tau,s)

lscimpedance(lamb, slice_params, i1)

LSC impedance (Eq. (52), although here we use a function from PRAB. 23, 014403 (Eq. 26))

Parameters:

• lamb (float) – initial modulation wavelength

• slice_params (list) – list of dicts containing beam slice properties

• i1 (int) – index from which to calculate

Return type:

float

Returns:

LSC impedance

r56taus(optics_map, i1)

R56 transport parameter between beamline elements (Eq. (49))

Parameters:

• optics_map (list) – list of first-order transfer matrices

• i1 (int) – index from which to calculate

Return type:

float

Returns:

R56(tau->s)

set_lamb_range(lamb_range)

Set initial modulation wavelength and update buching factor lists

Parameters:

lamb_range – range of initial modulation wavelengths

Return type:

None

set_slice(slices)

Set number of slices for calculating variation in gain along the beam

Parameters:

slices – number of slices (zero for beam core only)

Return type:

None

b0(lamb, I0)

initial longitudinal bunch factor form shot noise

Parameters:

• lamb (float) – initial modulation wavelength [m]

• I0 (float) – beam current [A]

k_wn(lamb)

uncompressed wave number in [1/m]

Parameters:

lamb (float) – initial modulation wavelength [m]

Returns:

conversion from lambda to k [1/m]

lattice_transfer_map_z(lattice, energy, zfin)

Function calculates transfer maps, first order only, for the whole lattice, up to zfin.

Parameters:

• lattice – MagneticLattice

• energy – the initial electron beam energy [GeV]

• zfin – the final z position in the accelerator lattice [m]

Returns:

first_order_tms - matrix

Returns:

elem - element located at zfin

p0(lamb, compression_factor, sdelta, r56, b0)

initial momentum bunch factor form shot noise

Parameters:

• lamb (float) – initial modulation wavelength [m]

• compression_factor (float) – beam longitudinal compression factor

• sdelta (float) – fractional energy spread

• r56 (float) – R56 from initial to current simulation step [m]

• b0 (float) – bunching factor from shot noise (see ~b0

• I0 – beam current [A]

simba.Codes.Ocelot.ocelot_conversion module

Module contents