xtrack 0.31.0__tar.gz → 0.32.1__tar.gz

{xtrack-0.31.0/xtrack.egg-info → xtrack-0.32.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: xtrack
-Version: 0.31.0
+Version: 0.32.1
 Summary: Tracking library for particle accelerators
 Home-page: https://xsuite.readthedocs.io/
 Download-URL: https://pypi.python.org/pypi/xtrack

{xtrack-0.31.0 → xtrack-0.32.1}/xtrack/__init__.py

@@ -9,8 +9,8 @@ from .base_element import BeamElement
 from .beam_elements import *
 from .random import *
 from .tracker_data import TrackerData
-from .line import Line, Node
-from .tracker import Tracker, freeze_longitudinal
+from .line import Line, Node, freeze_longitudinal, _temp_knobs
+from .tracker import Tracker
 from .match import Vary, Target, OrbitOnly
 from .loss_location_refinement import LossLocationRefinement
 from .internal_record import (RecordIdentifier, RecordIndex, new_io_buffer,

xtrack-0.32.1/xtrack/_version.py

@@ -0,0 +1 @@
+__version__ = '0.32.1'

{xtrack-0.31.0 → xtrack-0.32.1}/xtrack/beam_elements/apertures.py

@@ -16,6 +16,24 @@ UNLIMITED = 1e10  # could use np.inf but better safe than sorry
 
 
 class LimitRect(BeamElement):
+
+    '''
+    Beam element modeling a rectangular aperture limit.
+
+    Parameters
+    ----------
+    min_x : float
+        Lower x limit in meters.
+    max_x : float
+        Upper x limit in meters.
+    min_y : float
+        Lower y limit in meters.
+    max_y : float
+        Upper y limit in meters.
+
+    '''
+
+
     _xofields = {
         'min_x': xo.Float64,
         'max_x': xo.Float64,
@@ -24,14 +42,7 @@ class LimitRect(BeamElement):
         }
 
     def __init__(self, min_x=-UNLIMITED, max_x=UNLIMITED, min_y=-UNLIMITED, max_y=UNLIMITED, **kwargs):
-        """A rectangular aperture
-
-        Args:
-            min_x (float): Lower x limit in m
-            max_x (float): Upper x limit in m
-            min_y (float): Lower y limit in m
-            max_y (float): Upper y limit in m
-        """
+
         super().__init__(min_x=min_x, max_x=max_x, min_y=min_y, max_y=max_y, **kwargs)
 
     def get_backtrack_element(self, _context=None, _buffer=None, _offset=None):
@@ -42,6 +53,27 @@ class LimitRect(BeamElement):
 
 
 class LimitRacetrack(BeamElement):
+
+    '''
+    Beam element modeling a racetrack aperture limit.
+
+    Parameters
+    ----------
+    min_x : float
+        Lower x limit in meters.
+    max_x : float
+        Upper x limit in meters.
+    min_y : float
+        Lower y limit in meters.
+    max_y : float
+        Upper y limit in meters.
+    a : float
+        Horizontal semi-axis in meters of ellipse used for the rounding of the corners.
+    b : float
+        Vertical semi-axis in meters of ellipse used for the rounding of the corners.
+
+    '''
+
     _xofields = {
         'min_x': xo.Float64,
         'max_x': xo.Float64,
@@ -56,18 +88,6 @@ class LimitRacetrack(BeamElement):
 
     def __init__(self, min_x=-UNLIMITED, max_x=UNLIMITED, min_y=-UNLIMITED,
                  max_y=UNLIMITED, a=0, b=0, **kwargs):
-        """A racetrack shaped aperture
-
-        This is a rectangular aperture with rounded corners
-
-        Args:
-            min_x (float): Lower x limit in m
-            max_x (float): Upper x limit in m
-            min_y (float): Lower y limit in m
-            max_y (float): Upper y limit in m
-            a (float): Horizontal semi-axis of ellipse in m for the rounding of the corners
-            b (float): Vertical semi-axis of ellipse in m for the rounding of the corners
-        """
 
         if "_xobject" in kwargs:
             self.xoinitialize(_xobject=kwargs['_xobject'])
@@ -90,6 +110,19 @@ class LimitRacetrack(BeamElement):
 
 
 class LimitEllipse(BeamElement):
+
+    '''
+    Beam element modeling an elliptical aperture limit.
+
+    Parameters
+    ----------
+    a : float
+        Horizontal semi-axis in meters.
+    b : float
+        Vertical semi-axis in meters.
+
+    '''
+
     _xofields = {
             'a_squ': xo.Float64,
             'b_squ': xo.Float64,
@@ -103,12 +136,7 @@ class LimitEllipse(BeamElement):
         return dct
 
     def __init__(self, a=None, b=None, a_squ=None, b_squ=None, **kwargs):
-        """An elliptical aperture
 
-        Args:
-            a (float): Horizontal semi-axis of ellipse in m
-            b (float): Vertical semi-axis of ellipse in m
-        """
 
         if a is None and a_squ is None:
             a = UNLIMITED
@@ -151,6 +179,23 @@ class LimitEllipse(BeamElement):
 
 
 class LimitPolygon(BeamElement):
+
+    '''
+    Beam element modeling a polygonal aperture limit.
+
+    Parameters
+    ----------
+    x_vertices : array_like
+        x coordinates of the vertices of the polygon in meters.
+    y_vertices : array_like
+        y coordinates of the vertices of the polygon in meters.
+
+    Notes
+    -----
+    The polygon is closed automatically by connecting the last and first vertex.
+
+    '''
+
     _xofields = {
         'x_vertices': xo.Float64[:],
         'y_vertices': xo.Float64[:],
@@ -181,14 +226,7 @@ class LimitPolygon(BeamElement):
             n_threads='n_impacts')}
 
     def __init__(self, x_vertices=None, y_vertices=None, **kwargs):
-        """An aperture of arbitrary shape described by a polygon
 
-        Note: The polygon is closed automatically by connecting the last and first vertices.
-
-        Args:
-            x_vertices (list of float): Horizontal coordinates of the vertices in m
-            y_vertices (list of float): Vertical coordinates of the vertices in m
-        """
 
         if '_xobject' in kwargs.keys():
             super().__init__(**kwargs)
@@ -290,6 +328,25 @@ class LimitPolygon(BeamElement):
         return (cx,cy)
 
 class LimitRectEllipse(BeamElement):
+
+    '''
+    Element modeling an aperture limit given by the intersection of
+    a symmetric LimitRect and a LimitEllipse.
+
+    The particles are lost if they exceed either the rect or ellipse aperture.
+
+    Parameters
+    ----------
+    max_x : float
+        Horizontal semi-axis of rect in meters.
+    max_y : float
+        Vertical semi-axis of rect in meters.
+    a : float
+        Horizontal semi-axis of ellipse in meters.
+    b : float
+        Vertical semi-axis of ellipse in meters.
+    '''
+
     _xofields = {
             'max_x': xo.Float64,
             'max_y': xo.Float64,
@@ -302,16 +359,6 @@ class LimitRectEllipse(BeamElement):
         self, max_x=UNLIMITED, max_y=UNLIMITED, a_squ=None, b_squ=None,
         a=None, b=None, **kwargs
     ):
-        """An intersection of a symmetric LimitRect and a LimitEllipse
-
-        The particles are lost if they exceed either the rect or ellipse aperture
-
-        Args:
-            max_x (float): Horizontal semi-axis of rect in m
-            max_y (float): Vertical semi-axis of rect in m
-            a (float): Horizontal semi-axis of ellipse in m
-            b (float): Vertical semi-axis of ellipse in m
-        """
 
         if a is None and a_squ is None:
             a = UNLIMITED
@@ -362,6 +409,21 @@ class LimitRectEllipse(BeamElement):
 
 
 class LongitudinalLimitRect(BeamElement):
+
+    '''Beam element introducing a limit on the longitudinal coordinates.
+
+    Parameters
+    ----------
+    min_zeta : float
+        Lower limit on zeta coordinate in meters.
+    max_zeta : float
+        Upper limit on zeta coordinate in meters.
+    min_pzeta : float
+        Lower limit on pzeta coordinate.
+    max_pzeta : float
+        Upper limit on pzeta coordinate.
+    '''
+
     _xofields = {
         'min_zeta': xo.Float64,
         'max_zeta': xo.Float64,
@@ -370,16 +432,7 @@ class LongitudinalLimitRect(BeamElement):
         }
 
     def __init__(self, min_zeta=-UNLIMITED, max_zeta=UNLIMITED, min_pzeta=-UNLIMITED, max_pzeta=UNLIMITED, **kwargs):
-        """A limit on longitudinal coordinates
-
-        Particles are lost if they exceed either of the limits placed on the longitudinal coordinates
 
-        Args:
-            min_zeta (float): lower limit on zeta coordinate in m
-            max_zeta (float): upper limit on zeta coordinate in m
-            min_pzeta (float): lower limit on pzeta coordinate
-            max_pzeta (float): upper limit on pzeta coordinate
-        """
         super().__init__(min_zeta=min_zeta, max_zeta=max_zeta, min_pzeta=min_pzeta, max_pzeta=max_pzeta, **kwargs)
 
     def get_backtrack_element(self, _context=None, _buffer=None, _offset=None):

{xtrack-0.31.0 → xtrack-0.32.1}/xtrack/beam_elements/elements.py

@@ -17,9 +17,14 @@ from ..internal_record import RecordIndex, RecordIdentifier
 
 class ReferenceEnergyIncrease(BeamElement):
 
-    '''Beam element modeling a change of reference energy (acceleration, deceleration). Parameters:
+    '''Beam element modeling a change of reference energy (acceleration, 
+    deceleration).
+
+    Parameters
+    ----------
+    Delta_p0c : float
+        Change in reference energy in eV. Default is ``0``.
 
-             - Delta_p0c [eV]: Change in reference energy. Default is ``0``.
     '''
 
     _xofields = {
@@ -35,9 +40,6 @@ class ReferenceEnergyIncrease(BeamElement):
 
 class Marker(BeamElement):
     """A marker beam element with no effect on the particles.
-
-    Parameters:
-        - name (str): Name of the element
     """
 
     _xofields = {
@@ -56,9 +58,14 @@ class Marker(BeamElement):
 
 
 class Drift(BeamElement):
-    '''Beam element modeling a drift section. Parameters:
+    '''Beam element modeling a drift section.
+
+    Parameters
+    ----------
+
+    length : float
+        Length of the drift section in meters. Default is ``0``.
 
-             - length [m]: Length of the drift section. Default is ``0``.
     '''
 
     _xofields = {
@@ -76,11 +83,17 @@ class Drift(BeamElement):
 
 
 class Cavity(BeamElement):
-    '''Beam element modeling an RF cavity. Parameters:
+    '''Beam element modeling an RF cavity.
+
+    Parameters
+    ----------
+    voltage : float
+        Voltage of the RF cavity in Volts. Default is ``0``.
+    frequency : float
+        Frequency of the RF cavity in Hertz. Default is ``0``.
+    lag : float
+        Phase seen by the reference particle in degrees. Default is ``0``.
 
-             - voltage [V]: Voltage of the RF cavity. Default is ``0``.
-             - frequency [Hz]: Frequency of the RF cavity. Default is ``0``.
-             - lag [deg]: Phase seen by the reference particle. Default is ``0``.
     '''
 
     _xofields = {
@@ -102,10 +115,14 @@ class Cavity(BeamElement):
 
 
 class XYShift(BeamElement):
-    '''Beam element modeling an transverse shift of the reference system. Parameters:
+    '''Beam element modeling an transverse shift of the reference system.
 
-             - dx [m]: Horizontal shift. Default is ``0``.
-             - dy [m]: Vertical shift. Default is ``0``.
+    Parameters
+    ----------
+    dx : float
+        Horizontal shift in meters. Default is ``0``.
+    dy : float
+        Vertical shift in meters. Default is ``0``.
 
     '''
     _xofields = {
@@ -125,6 +142,31 @@ class XYShift(BeamElement):
 
 
 class Elens(BeamElement):
+    '''Beam element modeling a hollow electron lens.
+
+    Parameters
+    ----------
+    inner_radius : float
+        Inner radius of the electron lens in meters. Default is ``0``.
+    outer_radius : float
+        Outer radius of the electron lens in meters. Default is ``0``.
+    current : float
+        Current of the electron lens in Ampere. Default is ``0``.
+    elens_length : float
+        Length of the electron lens in meters. Default is ``0``.
+    voltage : float
+        Voltage of the electron lens in Volts. Default is ``0``.
+    residual_kick_x : float
+        Residual kick in the horizontal plane in radians. Default is ``0``.
+    residual_kick_y : float
+        Residual kick in the vertical plane in radians. Default is ``0``.
+    coefficients_polynomial : array
+        Array of coefficients of the polynomial. Default is ``[0]``.
+    polynomial_order : int
+        Order of the polynomial. Default is ``0``.
+
+    '''
+
 # if array is needed we do it like this
 #    _xofields={'inner_radius': xo.Float64[:]}
     _xofields={
@@ -186,6 +228,27 @@ class Elens(BeamElement):
 
 class Wire(BeamElement):
 
+    '''Beam element modeling a wire (used for long range beam-beam compensation).
+
+    Parameters
+    ----------
+
+    L_phy : float
+        Physical length of the wire in meters. Default is ``0``.
+    L_int : float
+        Interaction length of the wire in meters. Default is ``0``.
+    current : float
+        Current of the wire in Ampere. Default is ``0``.
+    xma : float
+        Horizontal position of the wire in meters. Default is ``0``.
+    yma : float
+        Vertical position of the wire in meters. Default is ``0``.
+    post_subtract_px : float
+        Horizontal post-subtraction kick in radians. Default is ``0``.
+    post_subtract_py : float
+        Vertical post-subtraction kick in radians. Default is ``0``.
+    '''
+
     _xofields={
                'L_phy'  : xo.Float64,
                'L_int'  : xo.Float64,
@@ -230,9 +293,13 @@ class Wire(BeamElement):
 
 
 class SRotation(BeamElement):
-    '''Beam element modeling an rotation of the reference system around the s axis. Parameters:
+    '''Beam element modeling an rotation of the reference system around the s axis.
+
+    Parameters
+    ----------
 
-                - angle [deg]: Rotation angle. Default is ``0``.
+    angle : float
+        Rotation angle in degrees. Default is ``0``.
 
     '''
 
@@ -289,9 +356,13 @@ class SRotation(BeamElement):
 
 
 class XRotation(BeamElement):
-    '''Beam element modeling an rotation of the reference system around the x axis. Parameters:
+    '''Beam element modeling an rotation of the reference system around the x axis.
 
-                - angle [deg]: Rotation angle. Default is ``0``.
+    Parameters
+    ----------
+
+    angle : float
+        Rotation angle in degrees. Default is ``0``.
 
     '''
 
@@ -368,9 +439,13 @@ class XRotation(BeamElement):
                               _context=_context, _buffer=_buffer, _offset=_offset)
 
 class YRotation(BeamElement):
-    '''Beam element modeling an rotation of the reference system around the y axis. Parameters:
+    '''Beam element modeling an rotation of the reference system around the y axis.
+
+    Parameters
+    ----------
 
-                - angle [deg]: Rotation angle. Default is ``0``.
+    angle : float
+        Rotation angle in degrees. Default is ``0``.
 
     '''
 
@@ -451,9 +526,13 @@ class YRotation(BeamElement):
                               _context=_context, _buffer=_buffer, _offset=_offset)
 
 class ZetaShift(BeamElement):
-    '''Beam element modeling a longitudinal translation of the reference system. Parameters:
+    '''Beam element modeling a time delat.
+
+    Parameters
+    ----------
 
-                - dzeta [m]: Translation in the longitudinal plane. Default is ``0``.
+    dzeta : float
+        Time shift dzeta in meters. Default is ``0``.
 
     '''
 
@@ -488,14 +567,23 @@ class SynchrotronRadiationRecord(xo.HybridClass):
 
 
 class Multipole(BeamElement):
-    '''Beam element modeling a thin magnetic multipole. Parameters:
-
-            - order [int]: Horizontal shift. Default is ``0``.
-            - knl [m^-n, array]: Normalized integrated strength of the normal components.
-            - ksl [m^-n, array]: Normalized integrated strength of the skew components.
-            - hxl [rad]: Rotation angle of the reference trajectory in the horizontal plane.
-            - hyl [rad]: Rotation angle of the reference trajectory in the vertical plane.
-            - length [m]: Length of the originating thick multipole.
+    '''Beam element modeling a thin magnetic multipole.
+
+    Parameters
+    ----------
+
+    knl : array
+        Normalized integrated strength of the normal components in units of m^-n.
+    ksl : array
+        Normalized integrated strength of the skew components in units of m^-n.
+    order : int
+        Order of the multipole. Default is ``0``.
+    hxl : float
+        Rotation angle of the reference trajectory in the horizontal plane in radians. Default is ``0``.
+    hyl : float
+        Rotation angle of the reference trajectory in the vertical plane in radians. Default is ``0``.
+    length : float
+        Length of the originating thick multipole. Default is ``0``.
 
     '''
 
@@ -572,10 +660,14 @@ class Multipole(BeamElement):
 
 
 class SimpleThinQuadrupole(BeamElement):
-    """An optimised version of a quadrupole with zero knl[0], ksl, hxl, hyl, and length.
-    Parameters:
+    """An specialized version of Multipole to model a thin quadrupole
+    (knl[0], ksl, hxl, hyl are all zero).
 
-            - knl [m^-n, array]: Normalized integrated strength of the normal components.
+    Parameters
+    ----------
+    knl : array
+        Normalized integrated strength of the normal components in units of m^-n.
+        Must be of length 2.
 
     """
 
@@ -632,13 +724,15 @@ class SimpleThinQuadrupole(BeamElement):
 
 
 class SimpleThinBend(BeamElement):
-    """An optimised version of a dipole with zero ksl and hyl. Parameters:
-
-            - knl [m^-n, array]: Normalized integrated strength of the normal components.
-            - hxl [rad]: Rotation angle of the reference trajectory in the horizontal plane.
-            - length [m]: Length of the originating thick multipole.
-
-    """
+    '''A specialized version of Multipole to model a thin bend (ksl, hyl are all zero).
+    knl : array
+        Normalized integrated strength of the normal components in units of m^-n.
+        Must be of length 1.
+    hxl : float
+        Rotation angle of the reference trajectory in the horizontal plane in radians. Default is ``0``.
+    length : float
+        Length of the originating thick bend. Default is ``0``.
+    '''
 
     _xofields={
         'knl': xo.Float64[1],
@@ -693,20 +787,26 @@ class SimpleThinBend(BeamElement):
 class RFMultipole(BeamElement):
     '''Beam element modeling a thin modulated multipole, with strengths dependent on the z coordinate:
 
-            kn(z) = k_n cos(2pi w tau + pn/180*pi)
-
-            ks[n](z) = k_n cos(2pi w tau + pn/180*pi)
-
-        Its parameters are:
-
-            - order [int]: Horizontal shift. Default is ``0``.
-            - frequency [Hz]: Frequency of the RF cavity. Default is ``0``.
-            - knl [m^-n, array]: Normalized integrated strength of the normal components.
-            - ksl [m^-n, array]: Normalized integrated strength of the skew components.
-            - pn [deg, array]: Phase of the normal components.
-            - ps [deg, array]: Phase of the skew components.
-            - voltage [V]: Longitudinal voltage. Default is ``0``.
-            - lag [deg]: Longitudinal phase seen by the reference particle. Default is ``0``.
+    Parameters
+    ----------
+    order : int
+        Order of the multipole. Default is ``0``.
+    knl : array
+        Normalized integrated strength of the normal components in units of m^-n.
+        Must be of length ``order+1``.
+    ksl : array
+        Normalized integrated strength of the skew components in units of m^-n.
+        Must be of length ``order+1``.
+    pn : array
+        Phase of the normal components in degrees. Must be of length ``order+1``.
+    ps : array
+        Phase of the skew components in degrees. Must be of length ``order+1``.
+    voltage : float
+        Longitudinal voltage. Default is ``0``.
+    lag : float
+        Longitudinal phase seen by the reference particle. Default is ``0``.
+    frequency : float
+        Frequency in Hertz. Default is ``0``.
 
     '''
 
@@ -804,12 +904,18 @@ class RFMultipole(BeamElement):
 
 
 class DipoleEdge(BeamElement):
-    '''Beam element modeling a dipole edge. Parameters:
-
-            - h [1/m]: Curvature.
-            - e1 [rad]: Face angle.
-            - hgap [m]: Equivalent gap.
-            - fint []: Fringe integral.
+    '''Beam element modeling a dipole edge (see MAD-X manual for detaild description).
+
+    Parameters
+    ----------
+    h : float
+        Curvature in 1/m.
+    e1 : float
+        Face angle in rad.
+    hgap : float
+        Equivalent gap in m.
+    fint : float
+        Fringe integral.
 
     '''
 
@@ -1084,9 +1190,24 @@ class LinearTransferMatrix(BeamElement):
     def beta_y_1(self):
         return self.beta_prod_y*self.beta_ratio_y
 
+class FirstOrderTaylorMap(BeamElement):
 
+    '''
+    First order Taylor map.
+
+    Parameters
+    ----------
+    length : float
+        length of the element in meters.
+    m0 : array_like
+        6x1 array of the zero order Taylor map coefficients.
+    m1 : array_like
+        6x6 array of the first order Taylor map coefficients.
+    radiation_flag : int
+        Flag for synchrotron radiation. 0 - no radiation, 1 - radiation on.
+
+    '''
 
-class FirstOrderTaylorMap(BeamElement):
     isthick = True
 
     _xofields={

{xtrack-0.31.0 → xtrack-0.32.1}/xtrack/footprint.py

@@ -1,5 +1,7 @@
 import numpy as np
 
+import xtrack as xt
+
 class LinearRescale():
 
     def __init__(self, knob_name, v0, dv):
@@ -14,7 +16,6 @@ def _footprint_with_linear_rescale(linear_rescale_on_knobs, line, kwargs):
 
         assert len(linear_rescale_on_knobs) == 1, (
             'Only one linear rescale is supported for now')
-        from xtrack.tracker import _temp_knobs
 
         knobs_0 = {}
         for rr in linear_rescale_on_knobs:
@@ -22,7 +23,7 @@ def _footprint_with_linear_rescale(linear_rescale_on_knobs, line, kwargs):
             v0 = rr.v0
             knobs_0[nn] = v0
 
-        with _temp_knobs(line, knobs_0):
+        with xt._temp_knobs(line, knobs_0):
             fp = line.get_footprint(**kwargs)
 
         _fp0_ref = fp.__dict__.copy() # for debugging
@@ -37,7 +38,7 @@ def _footprint_with_linear_rescale(linear_rescale_on_knobs, line, kwargs):
             knobs_1 = knobs_0.copy()
             knobs_1[nn] = v0 + dv
 
-            with _temp_knobs(line, knobs_1):
+            with xt._temp_knobs(line, knobs_1):
                 fp1 = line.get_footprint(**kwargs)
 
             delta_qx = (fp1.qx - qx0) / dv * (line.vars[nn]._value - v0)
@@ -136,7 +137,6 @@ class Footprint():
         line.track(particles, num_turns=self.n_turns, turn_by_turn_monitor=True)
         print('Done tracking.')
 
-
         ctx2np = line._context.nparray_from_context_array
         assert np.all(ctx2np(particles.state == 1)), (
             'Some particles were lost during tracking')