# ocelot.cpbd.optics¶

## Module Contents¶

### Classes¶

 SecondOrderMult The class includes three different methods for transforming the particle TransferMap TransferMap is a basic linear transfer map for all elements. SecondTM TransferMap is a basic linear transfer map for all elements. CorrectorTM TransferMap is a basic linear transfer map for all elements. PulseTM TransferMap is a basic linear transfer map for all elements. MultipoleTM TransferMap is a basic linear transfer map for all elements. CavityTM TransferMap is a basic linear transfer map for all elements. CouplerKickTM TransferMap is a basic linear transfer map for all elements. KickTM TransferMap is a basic linear transfer map for all elements. UndulatorTestTM TransferMap is a basic linear transfer map for all elements. RungeKuttaTM TransferMap is a basic linear transfer map for all elements. RungeKuttaTrTM THe same method as RungeKuttaTM but only transverse dynamics is included, longitudinal dynamics is skipped TWCavityTM TransferMap is a basic linear transfer map for all elements. MethodTM The class creates a transfer map for elements that depend on user-defined parameters (“parameters”). ProcessTable Navigator Navigator defines step (dz) of tracking and which physical process will be applied during each step.

### Functions¶

 transform_vec_ent(X, dx, dy, tilt) transform_vec_ext(X, dx, dy, tilt) transfer_maps_mult_py(Ra, Ta, Rb, Tb) cell = [A, B] transfer_map_rotation(R, T, tilt) lattice_transfer_map(lattice, energy) Function calculates transfer maps, the first and second orders (R, T), for the whole lattice. trace_z(lattice, obj0, z_array) Z-dependent tracer (twiss(z) and particle(z)) trace_obj(lattice, obj, nPoints=None) track object through the lattice periodic_twiss(tws, R) initial conditions for a periodic Twiss solution twiss(lattice, tws0=None, nPoints=None) twiss parameters calculation twiss_fast(lattice, tws0=None) twiss parameters calculation get_map(lattice, dz, navi) merge_maps(t_maps) fodo_parameters(betaXmean=36.0, L=10.0, verbose=False)
ocelot.cpbd.optics.__author__ = Sergey
ocelot.cpbd.optics._logger
ocelot.cpbd.optics._logger_navi
ocelot.cpbd.optics.nb_flag = True
class ocelot.cpbd.optics.SecondOrderMult

The class includes three different methods for transforming the particle coordinates:

1. NUMBA module - DEACTIVATED, because new numpy implementation shows higher performance.

Slightly faster than NUMPY for simulations with a large number of time steps. Uses full matrix multiplication.

2. NUMPY module

Base method to be used. Uses full matrix multiplication.

numba_apply(self, X, R, T)
numpy_apply(self, X, R, T)
ocelot.cpbd.optics.transform_vec_ent(X, dx, dy, tilt)
ocelot.cpbd.optics.transform_vec_ext(X, dx, dy, tilt)
ocelot.cpbd.optics.transfer_maps_mult_py(Ra, Ta, Rb, Tb)

cell = [A, B] Rc = Rb * Ra :param Ra: :param Ta: :param Rb: :param Tb: :param sym_flag: :return:

ocelot.cpbd.optics.transfer_maps_mult
ocelot.cpbd.optics.transfer_map_rotation(R, T, tilt)
class ocelot.cpbd.optics.TransferMap

TransferMap is a basic linear transfer map for all elements.

map_x_twiss(self, tws0)
mul_p_array(self, rparticles, energy=0.0)
__mul__(self, m)
Parameters

m – TransferMap, Particle or Twiss

Returns

TransferMap, Particle or Twiss

Ma = {Ba, Ra, Ta} Mb = {Bb, Rb, Tb} X1 = R*(X0 - dX) + dX = R*X0 + B B = (E - R)*dX

apply(self, prcl_series)
Parameters

prcl_series – can be list of Particles [Particle_1, Particle_2, … ] or ParticleArray

Returns

None

__call__(self, s)
class ocelot.cpbd.optics.SecondTM(r_z_no_tilt, t_mat_z_e)

TransferMap is a basic linear transfer map for all elements.

t_apply(self, R, T, X, dx, dy, tilt, U5666=0.0)
__call__(self, s)
class ocelot.cpbd.optics.CorrectorTM(angle_x=0.0, angle_y=0.0, r_z_no_tilt=None, t_mat_z_e=None)

TransferMap is a basic linear transfer map for all elements.

kick_b(self, z, l, angle_x, angle_y)
kick(self, X, z, l, angle_x, angle_y, energy)
__call__(self, s)
class ocelot.cpbd.optics.PulseTM(kn)

TransferMap is a basic linear transfer map for all elements.

mul_parray(self, rparticles, energy=0.0)
class ocelot.cpbd.optics.MultipoleTM(kn)

TransferMap is a basic linear transfer map for all elements.

kick(self, X, kn)
__call__(self, s)
class ocelot.cpbd.optics.CavityTM(v=0, freq=0.0, phi=0.0)

TransferMap is a basic linear transfer map for all elements.

map4cav(self, X, E, V, freq, phi, z=0)
__call__(self, s)
class ocelot.cpbd.optics.CouplerKickTM(v=0, freq=0.0, phi=0.0, vx=0.0, vy=0.0)

TransferMap is a basic linear transfer map for all elements.

kick_b(self, v, phi, energy)
kick(self, X, v, phi, energy)
__call__(self, s)
class ocelot.cpbd.optics.KickTM(angle=0.0, k1=0.0, k2=0.0, k3=0.0, nkick=1)

TransferMap is a basic linear transfer map for all elements.

kick(self, X, l, angle, k1, k2, k3, energy, nkick=1)

does not work for dipole

kick_apply(self, X, l, angle, k1, k2, k3, energy, nkick, dx, dy, tilt)
__call__(self, s)
class ocelot.cpbd.optics.UndulatorTestTM(lperiod, Kx, ax=0, ndiv=10)

TransferMap is a basic linear transfer map for all elements.

map4undulator(self, u, z, lperiod, Kx, ax, energy, ndiv)
__call__(self, s)
class ocelot.cpbd.optics.RungeKuttaTM(s_start=0, npoints=200)

TransferMap is a basic linear transfer map for all elements.

__call__(self, s)
class ocelot.cpbd.optics.RungeKuttaTrTM(s_start=0, npoints=200)

THe same method as RungeKuttaTM but only transverse dynamics is included, longitudinal dynamics is skipped

class ocelot.cpbd.optics.TWCavityTM(l=0, v=0, phi=0, freq=0)

TransferMap is a basic linear transfer map for all elements.

tw_cavity_R_z(self, z, V, E, freq, phi=0.0)
Parameters
• z – length

• de – delta E

• f – frequency

• E – initial energy

Returns

matrix

f_entrance(self, z, V, E, phi=0.0)
f_exit(self, z, V, E, phi=0.0)
__call__(self, s)
class ocelot.cpbd.optics.MethodTM(params=None)

The class creates a transfer map for elements that depend on user-defined parameters (“parameters”). By default, the parameters = {“global”: TransferMap}, which means that all elements will have linear transfer maps. You can also specify different transfer maps for any type of element.

# use linear matrices for all elements except Sextupole which will have nonlinear kick map (KickTM) method = MethodTM() method.global_method = TransferMap method.params[Sextupole] = KickTM

# All elements are assigned matrices of the second order. # For elements for which there are no matrices of the second order are assigned default matrices, e.g. linear matrices. method2 = MethodTM() method2.global_method = SecondTM

create_tm(self, element)
set_tm(self, element, method)
ocelot.cpbd.optics.sym_matrix(T)
ocelot.cpbd.optics.unsym_matrix(T)
ocelot.cpbd.optics.lattice_transfer_map(lattice, energy)

Function calculates transfer maps, the first and second orders (R, T), for the whole lattice. Second order matrices are attached to lattice object: lattice.T_sym - symmetric second order matrix lattice.T - second order matrix lattice.R - linear R matrix

Parameters
• lattice – MagneticLattice

• energy – the initial electron beam energy [GeV]

Returns

R - matrix

ocelot.cpbd.optics.trace_z(lattice, obj0, z_array)

Z-dependent tracer (twiss(z) and particle(z)) usage: twiss = trace_z(lattice,twiss_0, [1.23, 2.56, …]) , to calculate Twiss params at 1.23m, 2.56m etc.

ocelot.cpbd.optics.trace_obj(lattice, obj, nPoints=None)

track object through the lattice obj must be Twiss or Particle

ocelot.cpbd.optics.periodic_twiss(tws, R)

initial conditions for a periodic Twiss solution

ocelot.cpbd.optics.twiss(lattice, tws0=None, nPoints=None)

twiss parameters calculation

Parameters
• lattice – lattice, MagneticLattice() object

• tws0 – initial twiss parameters, Twiss() object. If None, try to find periodic solution.

• nPoints – number of points per cell. If None, then twiss parameters are calculated at the end of each element.

Returns

list of Twiss() objects

ocelot.cpbd.optics.twiss_fast(lattice, tws0=None)

twiss parameters calculation

Parameters
• lattice – lattice, MagneticLattice() object

• tws0 – initial twiss parameters, Twiss() object. If None, try to find periodic solution.

• nPoints – number of points per cell. If None, then twiss parameters are calculated at the end of each element.

Returns

list of Twiss() objects

class ocelot.cpbd.optics.ProcessTable(lattice)
searching_kick_proc(self, physics_proc, elem1)

function finds kick physics process. Kick physics process applies kick only once between two elements with zero length (e.g. Marker) or at the beginning of the element if it is the same element, others physics processes are applied during finite lengths. :return:

add_physics_proc(self, physics_proc, elem1, elem2)
class ocelot.cpbd.optics.Navigator(lattice)

Navigator defines step (dz) of tracking and which physical process will be applied during each step. lattice - MagneticLattice Attributes:

unit_step = 1 [m] - unit step for all physics processes

Methods:

physics_proc - physics process, can be CSR, SpaceCharge or Wake, elem1 and elem2 - first and last elements between which the physics process will be applied.

reset_position(self)

method to reset Navigator position. :return:

go_to_start(self)
get_phys_procs(self)

method return list of all physics processes which were added

Returns

list, list of PhysProc(s)

add_physics_proc(self, physics_proc, elem1, elem2)

Parameters
• physics_proc – PhysicsProc, e.g. SpaceCharge, CSR, Wake …

• elem1 – the element in the lattice where to start applying the physical process.

• elem2 – the element in the lattice where to stop applying the physical process, can be the same as starting element.

Returns

activate_apertures(self, start=None, stop=None)

activate apertures if thea exist in the lattice from

Parameters
• start – element, activate apertures starting form element ‘start’ element

• stop – element, activate apertures up to ‘stop’ element

Returns

check_overjump(self, dz, processes, phys_steps)
get_proc_list(self)
hard_edge_step(self, dz)
check_proc_bounds(self, dz, proc_list, phys_steps, active_process)
remove_used_processes(self, processes)

in case physics processes are applied and do not more needed they are removed from table

Parameters

processes – list of processes are about to apply

Returns

None

get_next(self)
ocelot.cpbd.optics.get_map(lattice, dz, navi)
ocelot.cpbd.optics.merge_maps(t_maps)
ocelot.cpbd.optics.fodo_parameters(betaXmean=36.0, L=10.0, verbose=False)