at.tracking.track#

Functions

`fortran_align`(func)	decorator to ensure that r_in is Fortran-aligned
`lattice_pass`(lattice, r_in[, nturns, refpts])	`lattice_pass()` tracks particles through each element of a lattice calling the element-specific tracking function specified in the Element's PassMethod field.
`element_pass`(element, r_in, **kwargs)	Tracks particles through a single element.
`atpass`(line, r_in, nturns[, refpts, reuse, ...])	Track input particles r_in along line for nturns turns.
`elempass`(element, r_in)	Track input particles r_in through a single element.

element_pass(element, r_in, **kwargs)[source]#

Tracks particles through a single element.

Parameters:

element (Element) – AT element
r_in – (6, N) array: input coordinates of N particles. r_in is modified in-place and reports the coordinates at the end of the element. For the best efficiency, r_in should be given as F_CONTIGUOUS numpy array.

Keyword Arguments:

particle (Particle) – circulating particle. Default: lattice.particle if existing, otherwise Particle('relativistic')
energy (float) – lattice energy. Default 0.

If energy is not available, relativistic tracking if forced, rest_energy is ignored.

Returns:: r_out – (6, N) array containing output the coordinates of the particles at the exit of the element.

fortran_align(func)[source]#

decorator to ensure that r_in is Fortran-aligned

fortran_align() ensures that the 2nd argument (usually r_in) of the decorated function is Fortran-aligned before calling the function

Example

>>> @fortran_align
... def element_pass(element: Element, r_in, **kwargs):
... ...

Ensure than r_in is Fortran-aligned

lattice_pass(lattice, r_in, nturns=1, refpts=RefptsCode.End, **kwargs)[source]#

lattice_pass() tracks particles through each element of a lattice calling the element-specific tracking function specified in the Element’s PassMethod field.

Parameters:

lattice (Iterable[Element]) – list of elements
r_in – (6, N) array: input coordinates of N particles. r_in is modified in-place and reports the coordinates at the end of the element. For the best efficiency, r_in should be given as F_CONTIGUOUS numpy array.
nturns (int) – number of turns to be tracked
refpts (Union[Type[Element], Element, Callable[[Element], bool], str, None, int, Sequence[int], bool, Sequence[bool], RefptsCode]) – Selects the location of coordinates output. See “Selecting elements in a lattice”

Keyword Arguments:

keep_lattice (bool) – Use elements persisted from a previous call. If True, assume that the lattice has not changed since the previous call.
keep_counter (bool) – Keep the turn number from the previous call.
turn (int) – Starting turn number. Ignored if keep_counter is True. The turn number is necessary to compute the absolute path length used in RFCavityPass.
losses (bool) – Boolean to activate loss maps output
omp_num_threads (int) – Number of OpenMP threads (default: automatic)

The following keyword arguments overload the Lattice values

Keyword Arguments:

particle (Optional[Particle]) – circulating particle. Default: lattice.particle if existing, otherwise Particle('relativistic')
energy (Optiona[float]) – lattice energy. Default 0.
unfold_beam (bool) – Internal beam folding activate, this assumes the input particles are in bucket 0, works only if all bucket see the same RF Voltage. Default: True

If energy is not available, relativistic tracking if forced, rest_energy is ignored.

Returns:

r_out – (6, N, R, T) array containing output coordinates of N particles at R reference points for T turns.

loss_map – If losses is True: dictionary with the following key:

islost	(npart,) bool array indicating lost particles
turn	(npart,) int array indicating the turn at which the particle is lost
element	((npart,) int array indicating the element at which the particle is lost
coord	(6, npart) float array giving the coordinates at which the particle is lost (zero for surviving particles)

Note

lattice_pass(lattice, r_in, refpts=len(line)) is the same as lattice_pass(lattice, r_in) since the reference point len(line) is the exit of the last element.
lattice_pass(lattice, r_in, refpts=0) is a copy of r_in since the reference point 0 is the entrance of the first element.
To resume an interrupted tracking (for instance to get intermediate results), one must use one of the turn or keep_counter keywords to ensure the continuity of the turn number.
For multiparticle tracking with large number of turn the size of r_out may increase excessively. To avoid memory issues lattice_pass(lattice, r_in, refpts=None) can be used. An empty list is returned and the tracking results of the last turn are stored in r_in.
To model buckets with different RF voltage unfold_beam=False has to be used. The beam can be unfolded using the function unfold_beam(). This function takes into account the true voltage in each bucket and distributes the particles in the bunches defined by ring.fillpattern using a 6D orbit search.