==================================== Modeling s-dependent magnetic fields ==================================== .. contents:: Table of Contents :depth: 2 Overview -------- The :class:`xtrack.SplineBoris` element models a thick magnetic element whose field varies along the longitudinal coordinate. It is suited to devices such as undulators, wigglers, fringe field and solenoids, for which a constant multipolar description is not sufficient. Internally, particles are tracked using a spatial Boris-like integrator. The method has second-order convergence in the number of integration steps (the global discretization error scales as ``n_steps**-2``). Although it is not strictly symplectic, it preserves phase-space volume and its symplectic deviation decreases quadratically with the number of integration steps. See the ``Spatial Boris Integrator`` chapter of the :doc:`Physics Guide ` for a description of the algorithm and its main properties. Within each element, the longitudinal dependence of the field is represented by fourth-order polynomials and the Lorentz force is integrated with a Boris stepper. The field data are provided through :class:`xtrack.Spline4` objects. Each object stores the field value and longitudinal derivative at both ends of an interval, together with its mean value. The ``bx`` and ``by`` arguments can also contain tuples of ``Spline4`` objects describing successive transverse derivatives of the field. The reconstruction of the three-dimensional field from these on-axis data is described in the ``Field expansion for s-dependent magnetic field`` chapter of the :doc:`Physics Guide `. An extended field map is typically represented by a line containing several ``SplineBoris`` elements, with one element for each longitudinal region over which a polynomial representation is used. The ``n_steps`` parameter controls the number of Boris integration steps within each element. Building an undulator from a field map -------------------------------------- The following example loads a three-dimensional field map of an SLS undulator and fits the on-axis field and its transverse derivatives in consecutive longitudinal regions. Each fitted region is converted to a ``SplineBoris`` element. Thin correctors are then inserted near the ends of the resulting line and matched to close the trajectory through the device. The ``FieldFitter`` used here is an example-specific helper. Users can apply their own fitting procedure to produce the corresponding ``Spline4`` data for each longitudinal region. .. literalinclude:: generated_code_snippets/splineboris_build_undulator.py :language: python .. figure:: figures/splineboris_undulator_trajectory.png :width: 90% :align: center Horizontal and vertical trajectories through the corrected undulator. Installing the undulator in a ring ---------------------------------- A line made of ``SplineBoris`` elements can be serialized and imported into another :class:`xtrack.Environment`. In the following example, the undulator built above is loaded, installed at several straight sections of the SLS ring, and included in a four-dimensional Twiss calculation. .. literalinclude:: generated_code_snippets/splineboris_undulators_in_sls_ring.py :language: python .. figure:: figures/splineboris_sls_closed_orbit.png :width: 90% :align: center Horizontal and vertical closed orbit in the SLS ring with the undulators installed.