at.tracking.track#

Functions

lattice_track(lattice, r_in[, nturns, ...])

track_function() tracks particles through each element of a lattice or throught a single Element calling the element-specific tracking function specified in the Element's PassMethod field.

element_track(element, r_in[, in_place])

element_track() tracks particles through one element of a calling the element-specific tracking function specified in the Element's PassMethod field

internal_lpass(lattice, r_in[, nturns, ...])

internal_epass(element, r_in, **kwargs)

internal_plpass(lattice, r_in[, nturns, ...])

element_track(element, r_in, in_place=False, **kwargs)[source]#

element_track() tracks particles through one element of a calling the element-specific tracking function specified in the Element’s PassMethod field

Usage:
>>> element_track(element, r_in)
>>> element.track(r_in)
Parameters:

  • element (Element) – element to track through

  • r_in – (6, N) array: input coordinates of N particles. For the best efficiency, r_in should be given as F_CONTIGUOUS numpy array.

Keyword Arguments:

  • in_place (bool) – If True r_in is modified in-place and reports the coordinates at the end of the element. (default: False)

  • omp_num_threads (int) – Number of OpenMP threads (default: automatic)

  • particle (Optional[Particle]) – circulating particle. Default: lattice.particle if existing, otherwise Particle('relativistic')

  • energy (Optiona[float]) – lattice energy. Default 0.

Returns:

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

internal_epass(element, r_in, **kwargs)#
internal_lpass(lattice, r_in, nturns=1, refpts=RefptsCode.End, no_varelem=True, **kwargs)#
internal_plpass(lattice, r_in, nturns=1, refpts=RefptsCode.End, pool_size=None, start_method=None, **kwargs)#
lattice_track(lattice, r_in, nturns=1, refpts=RefptsCode.End, in_place=False, **kwargs)[source]#

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

Usage:
>>> lattice_track(lattice, r_in)
>>> lattice.track(r_in)
Parameters:

  • lattice (Iterable[Element]) – list of elements

  • r_in – (6, N) array: input coordinates of N particles. r_in is modified in-place only if in_place is True 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:

  • nturns – number of turns to be tracked

  • refpts – Selects the location of coordinates output. See “Selecting elements in a lattice”

  • in_place (bool) – If True r_in is modified in-place and reports the coordinates at the end of the element. (default: False)

  • 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)

  • use_mp (bool) – Flag to activate multiprocessing (default: False)

  • pool_size – number of processes used when use_mp is True. If None, min(npart,nproc) is used. It can be globally set using the variable at.lattice.DConstant.patpass_poolsize

  • start_method – python multiprocessing start method. None uses the python default that is considered safe. Available values: 'fork', 'spawn', 'forkserver'. Default for linux is 'fork', default for macOS and Windows is 'spawn'. 'fork' may be used on macOS to speed up the calculation or to solve Runtime Errors, however it is considered unsafe. Used only when use_mp is True. It can be globally set using the variable at.lattice.DConstant.patpass_startmethod

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

  • trackparam – A dictionary containing tracking input parameters with the following keys:

    npart

    number of particles

    rout

    final particle coordinates

    turn

    starting turn

    refpts

    array of index where particle coordinate are saved (only for lattice tracking)

    nturns

    number of turn

  • trackdata – A dictionary containing tracking data with the following keys:

    loss_map:

    recarray containing the loss_map (only for lattice tracking)

    The loss_map is filled only if losses is True, it contains the following keys:

    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

    (npart, 6) float array giving the coordinates at which the particle is lost (zero for surviving particles)

Note

  • track_function(lattice, r_in, refpts=len(line)) is the same as track_function(lattice, r_in) since the reference point len(line) is the exit of the last element.

  • track_function(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 track_function(lattice, r_in, refpts=None, in_place=True) 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.