xtrack 0.98.10__tar.gz → 0.98.12__tar.gz

{xtrack-0.98.10/xtrack.egg-info → xtrack-0.98.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtrack
-Version: 0.98.10
+Version: 0.98.12
 Summary: Tracking library for particle accelerators
 Author: G. Iadarola et al.
 License-Expression: Apache-2.0

{xtrack-0.98.10 → xtrack-0.98.12}/tests/test_bucket_with_ref_energy_change.py

@@ -4,6 +4,10 @@ import xobjects as xo
 
 import numpy as np
 from scipy.constants import c as clight
+import pathlib
+
+test_data_folder = pathlib.Path(
+    __file__).parent.joinpath('../test_data').absolute()
 
 def test_bucket_below_transition():
 
@@ -1014,3 +1018,30 @@ def test_bucket_with_reference_ernergy_increase_elem():
     xo.assert_allclose(z_std, np.mean(z_std), atol=0.025*sigma_z)
     xo.assert_allclose(delta_mean, np.mean(delta_mean), atol=0.025*sigma_delta)
     xo.assert_allclose(delta_std, np.mean(delta_std), atol=0.025*sigma_delta)
+
+def test_bucket_with_radiation():
+
+    env = xt.load(test_data_folder / 'fcc_ee/fccee_h.seq')
+    pc_gev = 120.
+
+    line = env.fccee_p_ring
+    line.set_particle_ref('positron', p0c=pc_gev*1e9)
+
+    tw_no_rad = line.twiss6d()
+    rfb_no_rad = line._get_bucket()
+
+    line.configure_radiation(model='mean')
+    line.compensate_radiation_energy_loss()
+
+    tw_rad = line.twiss6d(eneloss_and_damping=True)
+    rfb_rad = line._get_bucket()
+
+    # Check that the effect of the radiation is visible on qs
+    assert tw_no_rad.qs > 0.045
+    assert tw_rad.qs < 0.035
+
+    # Check consistency of qs and bets0 between twiss and rfb
+    xo.assert_allclose(rfb_no_rad.Q_s, tw_no_rad.qs, rtol=0.01)
+    xo.assert_allclose(rfb_rad.Q_s, tw_rad.qs, rtol=0.01)
+    xo.assert_allclose(rfb_no_rad.beta_z, tw_no_rad.bets0, rtol=0.015)
+    xo.assert_allclose(rfb_rad.beta_z, tw_rad.bets0, rtol=0.015)

{xtrack-0.98.10 → xtrack-0.98.12}/tests/test_elements.py

@@ -1349,3 +1349,33 @@ def test_beam_element_shifts_backwards_compatible():
     assert sext.shift_x == legacy_dict['_shift_x']
     assert sext.shift_y == legacy_dict['_shift_y']
     assert sext.shift_s == legacy_dict['_shift_s']
+
+def test_cavity_lag_taper():
+
+    env = xt.Environment()
+
+    line = env.new_line(components=[
+        env.new('cav', xt.Cavity, frequency=400e6, voltage=16e6),
+    ])
+    p0 = xt.Particles(p0c=450e9)
+
+    p1 = p0.copy()
+    line.track(p1)
+    xo.assert_allclose(p1.delta, 0, atol=1e-10)
+
+    env['cav'].lag = 60
+    p2 = p0.copy()
+    line.track(p2)
+    assert p2.delta != 0
+
+    env['cav'].lag_taper = -60
+    p3 = p0.copy()
+    line.track(p3)
+    # lag_taper should be ignored because radiation is off
+    xo.assert_allclose(p3.delta, p2.delta, atol=1e-10)
+
+    line.configure_radiation(model='mean')
+    p4 = p0.copy()
+    line.track(p4)
+    # lag_taper should be applied now
+    xo.assert_allclose(p4.delta, 0, atol=1e-10)

xtrack-0.98.12/xtrack/_version.py

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

{xtrack-0.98.10 → xtrack-0.98.12}/xtrack/beam_elements/elements.py

@@ -840,7 +840,12 @@ class CrabCavity(_HasModelRF, _HasIntegrator, BeamElement):
 
 
 class XYShift(BeamElement):
-    '''Beam element modeling an transverse shift of the reference system.
+    '''
+    Beam element modeling an transverse shift of the reference system, by applying
+    the following transformation to the particle coordinates:
+
+        x_new = x_old - dx
+        y_new = y_old - dy
 
     Parameters
     ----------
@@ -985,9 +990,12 @@ class Wire(BeamElement):
 
 
 class SRotation(BeamElement):
-    """Beam element modeling a rotation of the reference system around the s-axis.
-    Positive angle is defined as x to y, i.e. counter-clockwise when looking
-    from the end of the s-axis towards the origin.
+    """
+    Beam element modeling a rotation of the reference system around the s-axis.
+    The sign convention is such that:
+
+            px_out = px_in * cos(angle) - py_in * sin(angle)
+
 
     Parameters
     ----------
@@ -1053,9 +1061,11 @@ class SRotation(BeamElement):
 
 
 class XRotation(BeamElement):
-    """Beam element modeling a rotation of the reference system around the x-axis.
-    Positive angle is defined as y to s, i.e. counter-clockwise when looking
-    from the end of the x-axis towards the origin.
+    """
+    Beam element modeling a rotation of the reference system around the x-axis.
+    The sign convention is such that:
+
+          py_out = py_in * cos(angle) + pz_in * sin(angle)
 
     Parameters
     ----------
@@ -1142,9 +1152,11 @@ class XRotation(BeamElement):
 
 
 class YRotation(BeamElement):
-    """Beam element modeling a rotation of the reference system around the y-axis.
-    Positive angle is defined as s to x, i.e. counter-clockwise when looking
-    from the end of the y-axis towards the origin.
+    """
+    Beam element modeling a rotation of the reference system around the y-axis.
+    The sign convention is such that:
+
+            px_out = px_in * cos(angle) - pz_in * sin(angle)
 
     Parameters
     ----------
@@ -1182,8 +1194,6 @@ class YRotation(BeamElement):
         calculate the missing values from the others. If more than necessary
         parameters are given, their consistency will be checked.
         """
-        #Note MAD-X node_value('other_bv ') is ignored
-        #     minus sign follows MAD-X convention
 
         if '_xobject' in kwargs and kwargs['_xobject'] is not None:
             self.xoinitialize(**kwargs)
@@ -1591,11 +1601,12 @@ class _BendCommon(_HasKnlKsl, _HasIntegrator, _HasModelCurved):
         self._length = value
         if self.length != 0:
             self._h = self.angle / self.length
-            if self.k0_from_h:
-                self._k0 = self.h
         else:
             self._h = 0.0
 
+        if self.k0_from_h:
+            self._k0 = self.h
+
     @property
     def h(self):
         return self._h

{xtrack-0.98.10 → xtrack-0.98.12}/xtrack/beam_elements/elements_src/track_magnet_kick.h

@@ -87,7 +87,7 @@ void track_magnet_kick_single_particle(
         double const hl = h * length * kick_weight + hxl * kick_weight;
         dpx += hl * (1. + LocalParticle_get_delta(part));
         double const rv0v = 1./LocalParticle_get_rvv(part);
-        dzeta += -rv0v * chi * hl * x;
+        dzeta += -rv0v * hl * x;
     }
 
     double htot = h;

{xtrack-0.98.10 → xtrack-0.98.12}/xtrack/beam_elements/elements_src/track_rf.h

@@ -340,6 +340,10 @@ void track_rf_particles(
     double body_length;
     double factor_knl_ksl_body;
 
+    #ifndef XTRACK_MULTIPOLE_NO_SYNRAD
+        lag += lag_taper;
+    #endif
+
     if (LocalParticle_check_track_flag(part0, XS_FLAG_BACKTRACK)) {
         body_length = -length;
         factor_knl_ksl_body = -factor_knl_ksl;
@@ -405,7 +409,7 @@ void track_rf_particles(
                 body_length * weight,
                 voltage * weight,
                 frequency,
-                lag + lag_taper,
+                lag,
                 harmonic,
                 transverse_voltage * weight,
                 transverse_lag,

{xtrack-0.98.10 → xtrack-0.98.12}/xtrack/beam_elements/elements_src/track_rf.template.h

@@ -259,6 +259,10 @@ void track_rf_particles(
     double body_length;
     double factor_knl_ksl_body;
 
+    #ifndef XTRACK_MULTIPOLE_NO_SYNRAD
+        lag += lag_taper;
+    #endif
+
     if (LocalParticle_check_track_flag(part0, XS_FLAG_BACKTRACK)) {
         body_length = -length;
         factor_knl_ksl_body = -factor_knl_ksl;
@@ -324,7 +328,7 @@ void track_rf_particles(
                 body_length * weight,
                 voltage * weight,
                 frequency,
-                lag + lag_taper,
+                lag,
                 harmonic,
                 transverse_voltage * weight,
                 transverse_lag,

{xtrack-0.98.10 → xtrack-0.98.12}/xtrack/line.py

@@ -1567,6 +1567,8 @@ class Line:
 
         """
         Compute the 4D Twiss parameters. Equivalent to `twiss` with `method='4d'`.
+        See :ref:`Line.twiss method documentation<twiss_method_label>` for all
+        available options.
         """
         assert 'method' not in kwargs, 'method cannot be provided as argument to twiss4d'
         kwargs['method'] = '4d'
@@ -1576,6 +1578,8 @@ class Line:
 
         """
         Compute the 6D Twiss parameters. Equivalent to `twiss` with `method='6d'`.
+        See :ref:`Line.twiss method documentation<twiss_method_label>` for all
+        available options.
         """
         assert 'method' not in kwargs, 'method cannot be provided as argument to twiss6d'
         kwargs['method'] = '6d'
@@ -1744,29 +1748,95 @@ class Line:
                element0=0, reverse=None):
 
         """
-        Returns a survey of the beamline (based on MAD-X survey command).
+        Compute the geometrical layout, i.e. the coordinates of all beam line
+        elements in the global reference system. (for detailed definitions of
+        the involved quantities please refer to the Xsuite Physics Guide
+        (https://xsuite.readthedocs.io/en/latest/physicsguide.html)
 
         Parameters
         ----------
         X0 : float
-            Initial X coordinate in meters.
+            Initial X coordinate in meters. Default is 0.
         Y0 : float
-            Initial Y coordinate in meters.
+            Initial Y coordinate in meters. Default is 0.
         Z0 : float
-            Initial Z coordinate in meters.
+            Initial Z coordinate in meters. Default is 0.
         theta0 : float
-            Initial theta coordinate in radians.
+            Initial theta coordinate in radians. Default is 0.
         phi0 : float
-            Initial phi coordinate in radians.
+            Initial phi coordinate in radians. Default is 0.
         psi0 : float
-            Initial psi coordinate in radians.
+            Initial psi coordinate in radians. Default is 0.
         element0 : int or str
-            Element at which the given coordinates are defined.
+            Element at which the given coordinates are defined. Default is the
+            first element in the beam line.
+        reverse : bool
+            If True, the survey is computed in the reversed reference frame.
 
         Returns
         -------
         survey : SurveyTable
             Survey table.
+
+        Notes
+        -----
+
+        The output survey table contains the following columns:
+
+        - ``name``: element name (with occurrence counts for repeated names).
+        - ``element_type``: type of the element (e.g. Drift, Marker, Bend).
+        - ``s``: longitudinal coordinate at the element entrance [m].
+        - ``X``, ``Y``, ``Z``: position of the element entrance in the global frame [m].
+        - ``theta``, ``phi``, ``psi``: orientation angles of the local frame
+          (azimuth, elevation, roll) unwrapped along the line [rad].
+        - ``ex``, ``ey``, ``ez``: unit vectors of the local frame expressed in
+          the global frame (they are the columns of ``W``).
+        - ``W``: 3x3 rotation matrices describing the local frame at each
+          element entrance.
+        - ``p0``: position vectors stacked as ``[X, Y, Z]``.
+        - ``isthick``: ``True`` for thick elements, ``False`` for markers.
+        - ``drift_length``: length used while advancing the survey (zero for
+          thin elements) [m].
+        - ``length``: physical length of the element [m].
+        - ``angle``: bending angle of the element [rad].
+        - ``rot_s_rad``: rotation around the longitudinal axis applied before
+          the element [rad].
+        - ``ref_shift_x``, ``ref_shift_y``: alignment shifts applied before the
+          element [m].
+        - ``ref_rot_x_rad``, ``ref_rot_y_rad``, ``ref_rot_s_rad``: alignment
+          rotations applied before the element [rad].
+
+        Examples
+        --------
+        .. code-block:: python
+
+            import xtrack as xt
+
+            # Create a simple line
+            env = xt.Environment(particle_ref=xt.Particles(p0c=1e9))
+            line = env.new_line(length=6, components=[
+                env.new('b1', xt.Bend, length=0.2, angle=0.1, at=1),
+                env.new('q1', xt.Quadrupole, length=0.1, k1=0.5, at=2),
+                env.new('b2', xt.Bend, length=0.2, angle=-0.1, at=3),
+                env.new('q2', xt.Quadrupole, length=0.1, k1=-0.5, at=4),
+            ])
+
+            # Compute the survey
+            sv = line.survey()
+            # sv.X, sv.Y, sv.Z contain the coordinates of the reference
+            # trajectory in the global frame
+
+            # Compute the trajectory of a particle entering with x=1 mm and y=2 mm
+            tw = line.twiss4d(betx=1, bety=1, x=1e-3, y=2e-3)
+            # tw.x, tw.y contain the coordinates of the particle in the local frame
+
+            # Compute the trajectory of the particle in the global frame
+            p_global = tw.x[:, None] * sv.ex + tw.y[:, None] * sv.ey + sv.p0
+
+            X_trajectory = p_global[:, 0]
+            Y_trajectory = p_global[:, 1]
+            Z_trajectory = p_global[:, 2]
+
         """
 
         if not self._has_valid_tracker():