API Reference

This is the API reference. To learn how to use and work with apace, see User Guide.

  • __version__ = 0.1.0

  • __license__ = GNU General Public License v3.0

Classes

  • Base - Abstract base for all element and lattice classes.

  • Element - Abstract base for all element classes.

  • Drift - A drift space element.

  • Dipole - A dipole element.

  • Quadrupole - A quadrupole element.

  • Sextupole - A sextupole element.

  • Octupole - An octupole element.

  • Lattice - Defines the order of elements in the accelerator.

  • MatrixMethod - The transfer matrix method.

  • Twiss - Calculate the Twiss parameter for a given lattice.

  • TrackingMatrix - Particle tracking using the transfer matrix method.

  • Signal - A callable signal class to which callbacks can be registered.

Functions

Exceptions

Detailed Overview

class Base(name, length, info='')

Abstract base for all element and lattice classes.

Parameters

  • name (str) – The name of the object.

  • info (str, optional) – Additional information about the object.

Attributes

name :str

The name of the object.

info :str

Additional information about the object

parent_lattices :Set[Lattice]

All lattices which contain the object.

length

Length of the object (m).

Methods

__repr__()

Return repr(self).

__str__()

Return str(self).

class Element(name, length, info='')

Inherits: Base

Abstract base for all element classes.

Parameters

  • name (str) – The name of the element.

  • length (float) – The length of the element (m).

  • info (str, optional) – Additional information about the element.

Attributes

attribute_changed :apace.utils.Signal

Gets emitted when one of the attributes changes.

length

Length of the element (m).

Methods

_on_attribute_changed(element, attribute)
__repr__()

Return repr(self).

__str__()

Return str(self).

class Drift(name, length, info='')

Inherits: Element

A drift space element.

Parameters

  • name (str) – The name of the element.

  • length (float) – The length of the element (m).

  • info (str, optional) – Additional information about the element.

Attributes

attribute_changed :apace.utils.Signal

Gets emitted when one of the attributes changes.

length

Length of the element (m).

Methods

_on_attribute_changed(element, attribute)
__repr__()

Return repr(self).

__str__()

Return str(self).

class Dipole(name, length, angle, e1=0, e2=0, info='')

Inherits: Element

A dipole element.

Parameters

  • name (str) – Name of the element.

  • length (float) – Length of the element (m).

  • angle (float) – Deflection angle in rad.

  • e1 (float, optional) – Entrance angle in rad.

  • e2 (float, optional) – Exit angle in rad.

  • info (str, optional) – Additional information about the element.

Attributes

angle

Deflection angle (rad).

e1

Entrance angle (rad).

e2

Exit angle (rad).

radius

Radius of curvature (m).

k0

Geometric dipole strength or curvature of radius (m).

length

Length of the element (m).

Methods

_on_attribute_changed(element, attribute)
__repr__()

Return repr(self).

__str__()

Return str(self).

class Quadrupole(name, length, k1, info='')

Inherits: Element

A quadrupole element.

Parameters

  • name (str) – Name of the element.

  • length (float) – Length of the element (m).

  • k1 (float) – Geometric quadrupole strength (m^-2).

  • info (str, optional) – Additional information about the element.

Attributes

k1

Geometric quadrupole strength (m^-2).

length

Length of the element (m).

Methods

_on_attribute_changed(element, attribute)
__repr__()

Return repr(self).

__str__()

Return str(self).

class Sextupole(name, length, k2, info='')

Inherits: Element

A sextupole element.

Parameters

  • name (str) – Name of the element.

  • length (float) – Length of the element (m).

  • k1 (float) – Geometric quadrupole strength (m^-3).

  • info (str, optional) – Additional information about the element.

Attributes

k2

Geometric sextupole strength (m^-3).

length

Length of the element (m).

Methods

_on_attribute_changed(element, attribute)
__repr__()

Return repr(self).

__str__()

Return str(self).

class Octupole(name, length, k3, info='')

Inherits: Element

An octupole element.

Parameters

  • name (str) – Name of the element.

  • length (float) – Length of the element (m).

  • k3 (float) – Geometric quadrupole strength (m^-4).

  • info (str, optional) – Additional information about the element.

Attributes

k3

Geometric sextupole strength (m^-1).

length

Length of the element (m).

Methods

_on_attribute_changed(element, attribute)
__repr__()

Return repr(self).

__str__()

Return str(self).

class Lattice(name, children, info='')

Inherits: Base

Defines the order of elements in the accelerator.

Parameters

  • name (str) – Name of the lattice.

  • children (List[Union[Element, Lattice]]) – List of elements and sub-lattices.

  • info (str) – Additional information about the lattice.

Attributes

length_changed :apace.utils.Signal

Gets emitted when the length of lattice changes.

element_changed :apace.utils.Signal

Gets emitted when an attribute of an element within this lattice changes.

n_elements

The number of elements within this lattice.

length

Length of the lattice.

children

List of direct children (elements or sub-lattices) in physical order.

sequence

List of elements in physical order. (Flattend children)

indices

A dict which contains the a List of indices for each element. Can be thought of as inverse of sequence. Sub-lattices are associated with the list of indices of their first element.

objects

A Mapping from names to the given Element or Lattice object.

elements

Unordered set of all elements within this lattice.

sub_lattices

Unordered set of all sub-lattices within this lattice.

Methods

traverse_children() :staticmethod:

Returns iterator which traverses all children of a lattice.

_init_properties()

A recursive helper function to initialize the properties.

__getitem__(key)
__del__()
update_length()

Manually update the Length of the lattice (m).

_on_length_changed()
_on_element_changed(element, attribute)
print_tree()

Print the lattice as tree of objects. (Similar to unix tree command)

_print_tree( prefix='') :staticmethod:
from_file( location, file_format=None) :classmethod:

Creates a new Lattice from file at location (path or url). :param location: path-like or url-like string which locates the lattice file :type location: Union[AnyStr, Path] :param file_format str: File format of the lattice file :type file_format: str, optional (use file extension) :rtype Lattice

from_dict( data) :classmethod:

Creates a new Lattice object from a latticeJSON compliant dictionary.

as_file(path, file_format=None)
as_dict()

Serializes the Lattice object into a latticeJSON compliant dictionary.

__repr__()

Return repr(self).

__str__()

Return str(self).

class MatrixMethod(lattice, steps_per_element=10, steps_per_meter=None, start_index=None, start_position=None, energy=None)

The transfer matrix method.

Parameters

  • lattice – Lattice which transfer matrices gets calculated for.

  • steps_per_element (int) – Fixed number of steps per element. (ignored if steps_per_meter is passed)

  • steps_per_meter (number) – Fixed number of steps per meter.

  • start_index (int) – Start index for the one-turn matrix and for the accumulated transfer matrices.

  • start_position (number) – Same as start_index but uses position instead of index of the position. Is ignored if start_index is set.

  • energy (number) – Total energy per particle in MeV.

Attributes

energy
gamma
velocity
n_steps

Total number of steps.

element_indices

Contains the indices of each element within the transfer_matrices.

step_size

Contains the step_size for each point. Has length of n_kicks

s

Contains the orbit position s for each point. Has length of n_kicks + 1.

matrices

Array of transfer matrices with shape (6, 6, n_kicks)

k0

Array of deflections angles with shape (n_kicks).

k1

Array of geometric quadruole strenghts with shape (n_kicks).

start_index

Start index of the one-turn matrix and the accumulated transfer matrices.

start_position

Same as start_index, but position in meter instead of index.

matrices_acc

The accumulated transfer matrices starting from start_index.

Methods

_on_element_changed(element, attribute)
update_n_steps()

Manually update the total number of kicks.

_on_n_steps_changed()
update_element_indices()

Manually update the indices of each element.

_on_element_indices_changed()
update_step_size()

Manually update the step_size array.

_on_step_size_changed()
update_s()

Manually update the orbit position array s.

_on_s_changed()
update_matrices()

Manually update the transfer_matrices.

update_matrices_acc()
_on_matrices_accumulated_changed()
class Twiss(lattice, start_idx=0, **kwargs)

Inherits: apace.matrixmethod.MatrixMethod

Calculate the Twiss parameter for a given lattice.

Parameters

  • lattice (Lattice) – Lattice to calculate the Twiss parameter for.

  • start_idx (int, optional) – Index from which the accumulated array is calculated. This index is also used to calculated the initial twiss parameter using the periodicity condition.

  • energy (float, optional) – Energy of the beam in mev

Attributes

start_idx_changed

Gets emitted when the start index changes

one_turn_matrix_changed

Gets emitted when the one turn matrix changes.

twiss_array_changed

Gets emitted when the twiss functions change.

psi_changed

Gets emitted when the betatron phase changes.

tune_fractional_changed

Gets emitted when the fractional tune changes.

start_idx

Index from which the accumulated array is calculated. This index is also used to calculated the initial twiss parameter using the periodicity condition.

accumulated_array

Contains accumulated transfer matrices.

one_turn_matrix

The transfer matrix for a full turn.

term_x

Corresponds to \(2 - m_{11}^2 - 2 m_{12} m_{21} - m_{22}^2\), where \(m\) is the one turn matrix. Can be used to calculate the initial beta_x value \(\beta_{x0} = |2 m_{12}| / \sqrt{term_x}\). If term_x > 0, this means that there exists a periodic solution within the horizontal plane.

term_y

Corresponds to \(2 - m_{33}^2 - 2 m_{34} m_{43} - m_{44}^2\), where \(m\) is the one turn matrix. Can be used to calculate the initial beta_y value \(\beta_{y0} = |2 m_{12}| / \sqrt{term_y}\). If term_y > 0, this means that there exists a periodic solution within the vertical plane.

stable_x

Periodicity condition term_x > 0 for a stable solution in the horizontal plane.

stable_y

Periodicity condition term_y > 0 for a stable solution in the vertical plane.

stable

Periodicity condition term_x > 0 and term_y > 0 for a stable solution in both planes.

initial_twiss

Array containing the initial twiss parameter.

twiss_array

Contains the twiss parameter.

beta_x

Horizontal beta function.

beta_y

Vertical beta function.

alpha_x

Horizontal alpha function.

alpha_y

Vertical alpha function.

gamma_x

Horizontal gamma function.

gamma_y

Vertical gamma function.

eta_x

Horizontal dispersion function.

eta_x_dds

Derivative of the horizontal dispersion with respect to s.

psi_x

Horizontal betatron phase.

psi_y

Vertical betatron phase.

tune_x

Horizontal tune. Corresponds to psi_x[-1] / 2 pi. Strongly depends on the selected step size.

tune_y

Vertical tune. Corresponds to psi_y[-1] / 2 pi. Strongly depends on the selected step size.

tune_x_fractional

Fractional part of the horizontal tune (Calculated from one-turn matrix).

tune_y_fractional

Fractional part of the vertical tune (Calculated from one-turn matrix).

chromaticity_x

Natural Horizontal Chromaticity. Depends on n_kicks

chromaticity_y

Natural Vertical Chromaticity. Depends on n_kicks

curly_h

The curly H function.

i1

The first synchrotron radiation integral.

i2

The second synchrotron radiation integral.

i3

The third synchrotron radiation integral.

i4

The fourth synchrotron radiation integral.

i5

The fifth synchrotron radiation integral.

alpha_c

Momentum Compaction Factor. Depends on n_kicks

gamma
emittance_x
energy
velocity
n_steps

Total number of steps.

element_indices

Contains the indices of each element within the transfer_matrices.

step_size

Contains the step_size for each point. Has length of n_kicks

s

Contains the orbit position s for each point. Has length of n_kicks + 1.

matrices

Array of transfer matrices with shape (6, 6, n_kicks)

k0

Array of deflections angles with shape (n_kicks).

k1

Array of geometric quadruole strenghts with shape (n_kicks).

start_index

Start index of the one-turn matrix and the accumulated transfer matrices.

start_position

Same as start_index, but position in meter instead of index.

matrices_acc

The accumulated transfer matrices starting from start_index.

Methods

update_one_turn_matrix()

Manually update the one turn matrix and the accumulated array.

_on_one_turn_matrix_changed()
update_twiss_array()

Manually update the twiss_array.

_on_twiss_array_changed()
update_betatron_phase()

Manually update the betatron phase psi and the tune.

_on_psi_changed()
update_fractional_tune()

Manually update the fractional tune.

_on_tune_fractional_changed()
update_chromaticity()

Manually update the natural chromaticity.

_on_chromaticity_changed()
_on_curly_h_changed()
_on_i1_changed()
_on_i2_changed()
_on_i3_changed()
_on_i4_changed()
_on_i5_changed()
_on_alpha_c_changed()
_on_emittance_changed()
_on_element_changed(element, attribute)
update_n_steps()

Manually update the total number of kicks.

_on_n_steps_changed()
update_element_indices()

Manually update the indices of each element.

_on_element_indices_changed()
update_step_size()

Manually update the step_size array.

_on_step_size_changed()
update_s()

Manually update the orbit position array s.

_on_s_changed()
update_matrices()

Manually update the transfer_matrices.

update_matrices_acc()
_on_matrices_accumulated_changed()
class TrackingMatrix(lattice, initial_distribution, turns=1, watch_points=None, start_point=0, **kwargs)

Inherits: apace.matrixmethod.MatrixMethod

Particle tracking using the transfer matrix method.

Parameters

  • lattice (Lattice) – Lattice which particles will be tracked through.

  • initial_distribution (np.ndarray) – Initial particle distribution.

  • turns (int) – Number of turns.

  • watch_points (array-like, optional) – List of watch points. If unset all particle trajectory will be saved for all positions. Indices correspont to orbit_positions.

  • start_point (int) – Point at which the particle tracking begins.

Attributes

watch_points
initial_distribution
particle_trajectories

Contains the 6D particle trajectories.

orbit_position
x
x_dds
y
y_dds
lon
delta
energy
gamma
velocity
n_steps

Total number of steps.

element_indices

Contains the indices of each element within the transfer_matrices.

step_size

Contains the step_size for each point. Has length of n_kicks

s

Contains the orbit position s for each point. Has length of n_kicks + 1.

matrices

Array of transfer matrices with shape (6, 6, n_kicks)

k0

Array of deflections angles with shape (n_kicks).

k1

Array of geometric quadruole strenghts with shape (n_kicks).

start_index

Start index of the one-turn matrix and the accumulated transfer matrices.

start_position

Same as start_index, but position in meter instead of index.

matrices_acc

The accumulated transfer matrices starting from start_index.

Methods

update_particle_trajectories()

Manually update the 6D particle trajectories

_on_particle_trajectories_changed()
_on_element_changed(element, attribute)
update_n_steps()

Manually update the total number of kicks.

_on_n_steps_changed()
update_element_indices()

Manually update the indices of each element.

_on_element_indices_changed()
update_step_size()

Manually update the step_size array.

_on_step_size_changed()
update_s()

Manually update the orbit position array s.

_on_s_changed()
update_matrices()

Manually update the transfer_matrices.

update_matrices_acc()
_on_matrices_accumulated_changed()
class Signal(*signals)

A callable signal class to which callbacks can be registered.

When ever the signal is emitted all registered functions are called.

Parameters

signals (Signal, optional) – Signals which this signal gets registered to.

Attributes

callbacks

Functions called when the signal is emitted.

__repr__

Methods

__call__(*args, **kwargs)

Emit signal and call registered functions.

__str__()

Return str(self).

connect(callback)

Connect a callback to this signal.

Parameters

callback (function) – Function which gets called when the signal is emitted.

distribution(n_particles, x_dist=None, x_center=0, x_width=0, y_dist=None, y_center=0, y_width=0, x_dds_dist=None, x_dds_center=0, x_dds_width=0, y_dds_dist=None, y_dds_center=0, y_dds_width=0, l_dist=None, l_center=0, l_width=0, delta_dist=None, delta_center=0, delta_width=None)

Create a particle distribution array (6, N).

Parameters

  • n_particles (int) – Number of particles.

  • x_dist (str) – Type of distribution in horizontal phase space.

  • x_center (float) – Center of distribution.

  • x_width (float) – Width of distribution.

  • y_dist (str) – Type of distribution in vertical phase space.

  • y_center (float) – Center of distribution.

  • y_width (float) – Width of distribution.

  • x_dds_dist (str) – Type of distribution in horizontal slope phase space.

  • x_dds_center (float) – Center of distribution.

  • x_dds_width (float) – Width of distribution.

  • y_dds_dist (str) – Type of distribution in vertical slope phase space.

  • y_dds_center (float) – Center of distribution.

  • y_dds_width (float) – Width of distribution.

  • l_dist (str) – Type of distribution in longitudinal phase space.

  • l_center (float) – Center of distribution.

  • l_width (float) – Width of distribution.

  • delta_dist (str) – Type of distribution in momentum phase space.

  • delta_center (float) – Center of distribution.

  • delta_width (float) – Width of distribution.

Returns

Array of shape (6, n_particles)

Return type

numpy.ndarray

exception AmbiguousNameError(name)

Inherits: Exception

Raised if multiple elements or lattices have the same name.

Parameters

name (str) – The ambiguous name.

class __cause__

exception cause

class __context__

exception context

class __suppress_context__
class __traceback__
class args

Methods

__delattr__()

Implement delattr(self, name).

__dir__()

Default dir() implementation.

__eq__()

Return self==value.

__format__()

Default object formatter.

__ge__()

Return self>=value.

__getattribute__()

Return getattr(self, name).

__gt__()

Return self>value.

__hash__()

Return hash(self).

__le__()

Return self<=value.

__lt__()

Return self<value.

__ne__()

Return self!=value.

__reduce__()

Helper for pickle.

__reduce_ex__()

Helper for pickle.

__repr__()

Return repr(self).

__setattr__()

Implement setattr(self, name, value).

__setstate__()
__sizeof__()

Size of object in memory, in bytes.

__str__()

Return str(self).

__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception UnstableLatticeError(twiss)

Inherits: Exception

Raised if no stable solution exists for the lattice.

class __cause__

exception cause

class __context__

exception context

class __suppress_context__
class __traceback__
class args

Methods

__delattr__()

Implement delattr(self, name).

__dir__()

Default dir() implementation.

__eq__()

Return self==value.

__format__()

Default object formatter.

__ge__()

Return self>=value.

__getattribute__()

Return getattr(self, name).

__gt__()

Return self>value.

__hash__()

Return hash(self).

__le__()

Return self<=value.

__lt__()

Return self<value.

__ne__()

Return self!=value.

__reduce__()

Helper for pickle.

__reduce_ex__()

Helper for pickle.

__repr__()

Return repr(self).

__setattr__()

Implement setattr(self, name, value).

__setstate__()
__sizeof__()

Size of object in memory, in bytes.

__str__()

Return str(self).

__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

Submodules