From 0ac6c91f94a451d45ad84f3c73ff53466e487b2a Mon Sep 17 00:00:00 2001 From: Axel Huebl Date: Thu, 21 Dec 2023 13:26:29 +0100 Subject: [PATCH] Docs: Alignment Input --- docs/source/index.rst | 2 +- docs/source/usage/parameters.rst | 133 +++++++++++++++---------------- docs/source/usage/python.rst | 118 +++++++++++++++++++++------ 3 files changed, 159 insertions(+), 94 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 8f02e884d..cada50593 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -65,9 +65,9 @@ Usage :hidden: usage/how_to_run + usage/examples usage/python usage/parameters - usage/examples usage/workflows Data Analysis diff --git a/docs/source/usage/parameters.rst b/docs/source/usage/parameters.rst index e5eb977e0..8d3cfdc91 100644 --- a/docs/source/usage/parameters.rst +++ b/docs/source/usage/parameters.rst @@ -261,22 +261,24 @@ Lattice Elements * ``cfbend`` for a combined function bending magnet. This requires these additional parameters: * ``.ds`` (``float``, in meters) the segment length - * ``.rc`` (``float``, in meters) the bend radius - * ``.k`` (``float``, in inverse meters squared) the quadrupole strength - = (magnetic field gradient in T/m) / (magnetic rigidity in T-m) * k > 0 horizontal focusing * k < 0 horizontal defocusing + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) * ``drift`` for a free drift. This requires these additional parameters: * ``.ds`` (``float``, in meters) the segment length - + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) * ``drift_chromatic`` for a free drift, with chromatic effects included. @@ -284,26 +286,31 @@ Lattice Elements This requires these additional parameters: * ``.ds`` (``float``, in meters) the segment length - + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) * ``drift_exact`` for a free drift, using the exact nonlinear map. This requires these additional parameters: * ``.ds`` (``float``, in meters) the segment length - + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) * ``quad`` for a quadrupole. This requires these additional parameters: * ``.ds`` (``float``, in meters) the segment length - * ``.k`` (``float``, in inverse meters squared) the quadrupole strength - = (magnetic field gradient in T/m) / (magnetic rigidity in T-m) * k > 0 horizontal focusing * k < 0 horizontal defocusing + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) * ``quad_chromatic`` for A Quadrupole magnet, with chromatic effects included. @@ -311,9 +318,7 @@ Lattice Elements This requires these additional parameters: * ``.ds`` (``float``, in meters) the segment length - * ``.k`` (``float``, in inverse meters squared OR in T/m) the quadrupole strength - = (magnetic field gradient in T/m) / (magnetic rigidity in T-m) - if units = 0 OR = magnetic field gradient in T/m - if units = 1 @@ -322,32 +327,33 @@ Lattice Elements * k < 0 horizontal defocusing * ``.units`` (``integer``) specification of units (default: ``0``) - + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) * ``quadrupole_softedge`` for a soft-edge quadrupole. This requires these additional parameters: * ``.ds`` (``float``, in meters) the segment length - * ``.gscale`` (``float``, in inverse meters) Scaling factor for on-axis magnetic field gradient - * ``.cos_coefficients`` (array of ``float``) cos coefficients in Fourier expansion of the on-axis field gradient (optional); default is a tanh fringe field model from `MaryLie 3.0 `__ - * ``.sin_coefficients`` (array of ``float``) sin coefficients in Fourier expansion of the on-axis field gradient (optional); default is a tanh fringe field model from `MaryLie 3.0 `__ - + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``.mapsteps`` (``integer``) number of integration steps per slice used for map and reference particle push in applied fields (default: ``1``) - * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) * ``sbend`` for a bending magnet. This requires these additional parameters: * ``.ds`` (``float``, in meters) the segment length - * ``.rc`` (``float``, in meters) the bend radius - + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) * ``sbend_exact`` for a bending magnet using the exact nonlinear map for the bend body. The map corresponds to the map described in: @@ -356,102 +362,91 @@ Lattice Elements particle. This requires these additional parameters: * ``.ds`` (``float``, in meters) the segment length - * ``.phi`` (``float``, in degrees) the bend angle - * ``.B`` (``float``, in Tesla) the bend magnetic field; when B = 0 (default), the reference bending radius is defined by r0 = length / (angle in rad), corresponding to a magnetic field of B = rigidity / r0; otherwise the reference bending radius is defined by r0 = rigidity / B - + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) * ``solenoid`` for an ideal hard-edge solenoid magnet. This requires these additional parameters: * ``.ds`` (``float``, in meters) the segment length - * ``.ks`` (``float``, in meters) Solenoid strength in m^(-1) (MADX convention) - = (magnetic field Bz in T) / (rigidity in T-m) - + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) * ``solenoid_softedge`` for a soft-edge solenoid. This requires these additional parameters: * ``.ds`` (``float``, in meters) the segment length - * ``.bscale`` (``float``, in inverse meters) Scaling factor for on-axis magnetic field Bz - * ``.cos_coefficients`` (array of ``float``) cos coefficients in Fourier expansion of the on-axis magnetic field Bz (optional); default is a thin-shell model from `DOI:10.1016/J.NIMA.2022.166706 `__ - * ``.sin_coefficients`` (array of ``float``) sin coefficients in Fourier expansion of the on-axis magnetic field Bz (optional); default is a thin-shell model from `DOI:10.1016/J.NIMA.2022.166706 `__ - + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``.mapsteps`` (``integer``) number of integration steps per slice used for map and reference particle push in applied fields (default: ``1``) - * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) * ``dipedge`` for dipole edge focusing. This requires these additional parameters: * ``.psi`` (``float``, in radians) the pole face rotation angle - * ``.rc`` (``float``, in meters) the bend radius - * ``.g`` (``float``, in meters) the gap size - * ``.K2`` (``float``, dimensionless) normalized field integral for fringe field + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``constf`` for a constant focusing element. This requires these additional parameters: * ``.ds`` (``float``, in meters) the segment length - * ``.kx`` (``float``, in 1/meters) the horizontal focusing strength - * ``.ky`` (``float``, in 1/meters) the vertical focusing strength - * ``.kt`` (``float``, in 1/meters) the longitudinal focusing strength - + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) * ``rfcavity`` a radiofrequency cavity. This requires these additional parameters: * ``.ds`` (``float``, in meters) the segment length - * ``.escale`` (``float``, in 1/m) scaling factor for on-axis RF electric field - = (peak on-axis electric field Ez in MV/m) / (particle rest energy in MeV) - * ``.freq`` (``float``, in Hz) RF frequency - * ``.phase`` (``float``, in degrees) RF driven phase - * ``.cos_coefficients`` (array of ``float``) cosine coefficients in Fourier expansion of on-axis electric field Ez (optional); default is a 9-cell TESLA superconducting cavity model from `DOI:10.1103/PhysRevSTAB.3.092001 `__ - * ``.cos_coefficients`` (array of ``float``) sine coefficients in Fourier expansion of on-axis electric field Ez (optional); default is a 9-cell TESLA superconducting cavity model from `DOI:10.1103/PhysRevSTAB.3.092001 `__ - + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``.mapsteps`` (``integer``) number of integration steps per slice used for map and reference particle push in applied fields (default: ``1``) - * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) * ``buncher`` for a short RF cavity (linear) bunching element. This requires these additional parameters: * ``.V`` (``float``, dimensionless) normalized voltage drop across the cavity - = (maximum voltage drop in Volts) / (speed of light in m/s * magnetic rigidity in T-m) - * ``.k`` (``float``, in 1/meters) the RF wavenumber - = 2*pi/(RF wavelength in m) + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``shortrf`` for a short RF cavity element. This requires these additional parameters: * ``.V`` (``float``, dimensionless) normalized voltage drop across the cavity - = (maximum energy gain in MeV) / (particle rest energy in MeV) - * ``.freq`` (``float``, in Hz) the RF frequency - * ``.phase`` (``float``, in degrees) the synchronous RF phase phase = 0: maximum energy gain (on-crest) @@ -459,76 +454,80 @@ Lattice Elements phase = -90 deg: zero energy gain for bunching phase = 90 deg: zero energy gain for debunching + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``uniform_acc_chromatic`` for a region of uniform acceleration, with chromatic effects included. The Hamiltonian is expanded through second order in the transverse variables (x,px,y,py), with the exact pt dependence retained. This requires these additional parameters: * ``.ds`` (``float``, in meters) the segment length - * ``.ez`` (``float``, in inverse meters) the electric field strength - = (particle charge in C * electric field Ez in V/m) / (particle mass in kg * (speed of light in m/s)^2) - * ``.bz`` (``float``, in inverse meters) the magnetic field strength - = (particle charge in C * magnetic field Bz in T) / (particle mass in kg * speed of light in m/s) - + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``.nslice`` (``integer``) number of slices used for the application of space charge (default: ``1``) * ``multipole`` for a thin multipole element. This requires these additional parameters: * ``.multipole`` (``integer``, dimensionless) order of multipole - (m = 1) dipole, (m = 2) quadrupole, (m = 3) sextupole, etc. * ``.k_normal`` (``float``, in 1/meters^m) integrated normal multipole coefficient (MAD-X convention) - = 1/(magnetic rigidity in T-m) * (derivative of order m-1 of By with respect to x) - * ``.k_skew`` (``float``, in 1/meters^m) integrated skew multipole strength (MAD-X convention) + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``nonlinear_lens`` for a thin IOTA nonlinear lens element. This requires these additional parameters: * ``.knll`` (``float``, in meters) integrated strength of the lens segment (MAD-X convention) - = dimensionless lens strength * c parameter**2 * length / Twiss beta - * ``.cnll`` (``float``, in meters) distance of the singularities from the origin (MAD-X convention) - = c parameter * sqrt(Twiss beta) + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``prot`` for an exact pole-face rotation in the x-z plane. This requires these additional parameters: * ``.phi_in`` (``float``, in degrees) angle of the reference particle with respect to the longitudinal (z) axis in the original frame - * ``.phi_out`` (``float``, in degrees) angle of the reference particle with respect to the longitudinal (z) axis in the rotated frame * ``kicker`` for a thin transverse kicker. This requires these additional parameters: * ``.xkick`` (``float``, dimensionless OR in T-m) the horizontal kick strength - * ``.ykick`` (``float``, dimensionless OR in T-m) the vertical kick strength - * ``.units`` (``string``) specification of units: ``dimensionless`` (default, in units of the magnetic rigidity of the reference particle) or ``T-m`` + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``thin_dipole`` for a thin dipole element. This requires these additional parameters: * ``.theta`` (``float``, in degrees) dipole bend angle - * ``.rc`` (``float``, in meters) effective radius of curvature + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``aperture`` for a thin collimator element applying a transverse aperture boundary. This requires these additional parameters: * ``.xmax`` (``float``, in meters) maximum value of the horizontal coordinate - * ``.ymax`` (``float``, in meters) maximum value of the vertical coordinate - * ``.shape`` (``string``) shape of the aperture boundary: ``rectangular`` (default) or ``elliptical`` + * ``.dx`` (``float``, in meters) horizontal translation error + * ``.dy`` (``float``, in meters) vertical translation error + * ``.rotation`` (``float``, in degrees) transversal rotation error around the z axis (in the x-y plane) * ``beam_monitor`` a beam monitor, writing all beam particles at fixed ``s`` to openPMD files. If the same element name is used multiple times, then an output series is created with multiple outputs. diff --git a/docs/source/usage/python.rst b/docs/source/usage/python.rst index 334c2c198..a2e58c6d6 100644 --- a/docs/source/usage/python.rst +++ b/docs/source/usage/python.rst @@ -459,7 +459,7 @@ This module provides elements for the accelerator lattice. :param madx_file: file name to MAD-X file with beamline elements :param nslice: number of slices used for the application of space charge -.. py:class:: impactx.elements.CFbend(ds, rc, k, nslice=1) +.. py:class:: impactx.elements.CFbend(ds, rc, k, dx=0, dy=0, rotation=0, nslice=1) A combined function bending magnet. This is an ideal Sbend with a normal quadrupole field component. @@ -469,9 +469,12 @@ This module provides elements for the accelerator lattice. = (gradient in T/m) / (rigidity in T-m) k > 0 horizontal focusing k < 0 horizontal defocusing + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] :param nslice: number of slices used for the application of space charge -.. py:class:: impactx.elements.ConstF(ds, kx, ky, kt, nslice=1) +.. py:class:: impactx.elements.ConstF(ds, kx, ky, kt, dx=0, dy=0, rotation=0, nslice=1) A linear Constant Focusing element. @@ -479,6 +482,9 @@ This module provides elements for the accelerator lattice. :param kx: Focusing strength for x in 1/m. :param ky: Focusing strength for y in 1/m. :param kt: Focusing strength for t in 1/m. + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] :param nslice: number of slices used for the application of space charge .. py:property:: kx @@ -493,7 +499,7 @@ This module provides elements for the accelerator lattice. focusing t strength in 1/m -.. py:class:: impactx.elements.DipEdge(psi, rc, g, K2) +.. py:class:: impactx.elements.DipEdge(psi, rc, g, K2, dx=0, dy=0, rotation=0) Edge focusing associated with bend entry or exit @@ -501,6 +507,7 @@ This module provides elements for the accelerator lattice. Here we use the linear fringe field map, given to first order in g/rc (gap / radius of curvature). References: + * K. L. Brown, SLAC Report No. 75 (1982). * K. Hwang and S. Y. Lee, PRAB 18, 122401 (2015). @@ -508,31 +515,40 @@ This module provides elements for the accelerator lattice. :param rc: Radius of curvature in m :param g: Gap parameter in m :param K2: Fringe field integral (unitless) + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] -.. py:class:: impactx.elements.Drift(ds, nslice=1) +.. py:class:: impactx.elements.Drift(ds, dx=0, dy=0, rotation=0, nslice=1) A drift. :param ds: Segment length in m :param nslice: number of slices used for the application of space charge -.. py:class:: impactx.elements.ChrDrift(ds, nslice=1) +.. py:class:: impactx.elements.ChrDrift(ds, dx=0, dy=0, rotation=0, nslice=1) A drift with chromatic effects included. The Hamiltonian is expanded through second order in the transverse variables (x,px,y,py), with the exact pt dependence retained. :param ds: Segment length in m + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] :param nslice: number of slices used for the application of space charge -.. py:class:: impactx.elements.ExactDrift(ds, nslice=1) +.. py:class:: impactx.elements.ExactDrift(ds, dx=0, dy=0, rotation=0, nslice=1) A drift using the exact nonlinear transfer map. :param ds: Segment length in m + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] :param nslice: number of slices used for the application of space charge -.. py:class:: impactx.elements.Kicker(xkick, ykick, units) +.. py:class:: impactx.elements.Kicker(xkick, ykick, units, dx=0, dy=0, rotation=0) A thin transverse kicker. @@ -540,29 +556,35 @@ This module provides elements for the accelerator lattice. :param ykick: vertical kick strength (dimensionless OR T-m) :param units: specification of units (``"dimensionless"`` in units of the magnetic rigidity of the reference particle or ``"T-m"``) -.. py:class:: impactx.elements.Multipole(multipole, K_normal, K_skew) +.. py:class:: impactx.elements.Multipole(multipole, K_normal, K_skew, dx=0, dy=0, rotation=0) A general thin multipole element. :param multipole: index m (m=1 dipole, m=2 quadrupole, m=3 sextupole etc.) :param K_normal: Integrated normal multipole coefficient (1/meter^m) :param K_skew: Integrated skew multipole coefficient (1/meter^m) + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] .. py::class:: impactx.elements.None This element does nothing. -.. py:class:: impactx.elements.NonlinearLens(knll, cnll) +.. py:class:: impactx.elements.NonlinearLens(knll, cnll, dx=0, dy=0, rotation=0) Single short segment of the nonlinear magnetic insert element. A thin lens associated with a single short segment of the nonlinear magnetic insert described by V. Danilov and S. Nagaitsev, PRSTAB 13, 084002 (2010), Sect. V.A. This - element appears in MAD-X as type NLLENS. + element appears in MAD-X as type ``NLLENS``. :param knll: integrated strength of the nonlinear lens (m) :param cnll: distance of singularities from the origin (m) + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] .. py:class:: impactx.elements.BeamMonitor(name, backend="default", encoding="g") @@ -608,7 +630,7 @@ This module provides elements for the accelerator lattice. This function is called for the reference particle as it passes through the element. The reference particle is updated *before* the beam particles are pushed. -.. py:class:: impactx.elements.Quad(ds, k, nslice=1) +.. py:class:: impactx.elements.Quad(ds, k, dx=0, dy=0, rotation=0, nslice=1) A Quadrupole magnet. @@ -617,9 +639,12 @@ This module provides elements for the accelerator lattice. = (gradient in T/m) / (rigidity in T-m) k > 0 horizontal focusing k < 0 horizontal defocusing + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] :param nslice: number of slices used for the application of space charge -.. py:class:: impactx.elements.ChrQuad(ds, k, units, nslice=1) +.. py:class:: impactx.elements.ChrQuad(ds, k, units, dx=0, dy=0, rotation=0, nslice=1) A Quadrupole magnet, with chromatic effects included. The Hamiltonian is expanded through second order in the transverse variables (x,px,y,py), with the exact pt @@ -632,9 +657,12 @@ This module provides elements for the accelerator lattice. k > 0 horizontal focusing k < 0 horizontal defocusing :param units: specification of units for quadrupole field strength + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] :param nslice: number of slices used for the application of space charge -.. py:class:: impactx.elements.RFCavity(ds, escale, freq, phase, mapsteps, nslice) +.. py:class:: impactx.elements.RFCavity(ds, escale, freq, phase, dx=0, dy=0, rotation=0, mapsteps=1, nslice=1) A radiofrequency cavity. @@ -646,47 +674,63 @@ This module provides elements for the accelerator lattice. :param cos_coefficients: array of ``float`` cosine coefficients in Fourier expansion of on-axis electric field Ez (optional); default is a 9-cell TESLA superconducting cavity model from `DOI:10.1103/PhysRevSTAB.3.092001 `__ :param cos_coefficients: array of ``float`` sine coefficients in Fourier expansion of on-axis electric field Ez (optional); default is a 9-cell TESLA superconducting cavity model from `DOI:10.1103/PhysRevSTAB.3.092001 `__ + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] :param mapsteps: number of integration steps per slice used for map and reference particle push in applied fields :param nslice: number of slices used for the application of space charge -.. py:class:: impactx.elements.Sbend(ds, rc, nslice=1) +.. py:class:: impactx.elements.Sbend(ds, rc, dx=0, dy=0, rotation=0, nslice=1) An ideal sector bend. :param ds: Segment length in m. :param rc: Radius of curvature in m. + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] :param nslice: number of slices used for the application of space charge -.. py:class:: impactx.elements.ExactSbend(ds, phi, B, nslice=1) +.. py:class:: impactx.elements.ExactSbend(ds, phi, B, dx=0, dy=0, rotation=0, nslice=1) An ideal sector bend using the exact nonlinear map. The model consists of a uniform bending field B_y with a hard edge. Pole faces are normal to the entry and exit velocity of the reference particle. -References: + References: + * D. L. Bruhwiler et al, in Proc. of EPAC 98, pp. 1171-1173 (1998). * E. Forest et al, Part. Accel. 45, pp. 65-94 (1994). :param ds: Segment length in m. :param phi: Bend angle in degrees. :param B: Magnetic field in Tesla; when B = 0 (default), the reference bending radius is defined by r0 = length / (angle in rad), corresponding to a magnetic field of B = rigidity / r0; otherwise the reference bending radius is defined by r0 = rigidity / B. + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] :param nslice: number of slices used for the application of space charge -.. py:class:: impactx.elements.Buncher(V, k) +.. py:class:: impactx.elements.Buncher(V, k, dx=0, dy=0, rotation=0) A short RF cavity element at zero crossing for bunching (MaryLie model). :param V: Normalized RF voltage drop V = Emax*L/(c*Brho) :param k: Wavenumber of RF in 1/m + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] -.. py:class:: impactx.elements.ShortRF(V, freq, phase) +.. py:class:: impactx.elements.ShortRF(V, freq, phase, dx=0, dy=0, rotation=0) A short RF cavity element (MAD-X model). :param V: Normalized RF voltage V = maximum energy gain/(m*c^2) :param freq: RF frequency in Hz :param phase: RF synchronous phase in degrees (phase = 0 corresponds to maximum energy gain, phase = -90 corresponds go zero energy gain for bunching) + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] -.. py:class:: impactx.elements.ChrUniformAcc(ds, k, nslice=1) +.. py:class:: impactx.elements.ChrUniformAcc(ds, k, dx=0, dy=0, rotation=0, nslice=1) A region of constant Ez and Bz for uniform acceleration, with chromatic effects included. The Hamiltonian is expanded through second order in the transverse variables (x,px,y,py), @@ -697,10 +741,12 @@ References: = (particle charge in C * field Ez in V/m) / (particle mass in kg * (speed of light in m/s)^2) :param bz: Magnetic field strength in m^(-1) = (particle charge in C * field Bz in T) / (particle mass in kg * speed of light in m/s) - + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] :param nslice: number of slices used for the application of space charge -.. py:class:: impactx.elements.SoftSolenoid(ds, bscale, cos_coefficients, sin_coefficients, nslice=1) +.. py:class:: impactx.elements.SoftSolenoid(ds, bscale, cos_coefficients, sin_coefficients, dx=0, dy=0, rotation=0, mapsteps=1, nslice=1) A soft-edge solenoid. @@ -710,15 +756,21 @@ References: (optional); default is a thin-shell model from `DOI:10.1016/J.NIMA.2022.166706 `__ :param sin_coefficients: array of ``float`` sine coefficients in Fourier expansion of on-axis magnetic field Bz (optional); default is a thin-shell model from `DOI:10.1016/J.NIMA.2022.166706 `__ + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] :param mapsteps: number of integration steps per slice used for map and reference particle push in applied fields :param nslice: number of slices used for the application of space charge -.. py:class:: impactx.elements.Sol(ds, ks, nslice=1) +.. py:class:: impactx.elements.Sol(ds, ks, dx=0, dy=0, rotation=0, nslice=1) An ideal hard-edge Solenoid magnet. :param ds: Segment length in m. :param ks: Solenoid strength in m^(-1) (MADX convention) in (magnetic field Bz in T) / (rigidity in T-m) + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] :param nslice: number of slices used for the application of space charge .. py:class:: impactx.elements.PRot(phi_in, phi_out) @@ -727,16 +779,22 @@ References: :param phi_in: angle of the reference particle with respect to the longitudinal (z) axis in the original frame in degrees :param phi_out: angle of the reference particle with respect to the longitudinal (z) axis in the rotated frame in degrees + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] -.. py:class:: impactx.elements.Aperture(xmax, ymax, shape="rectangular") +.. py:class:: impactx.elements.Aperture(xmax, ymax, shape="rectangular", dx=0, dy=0, rotation=0) A thin collimator element, applying a transverse aperture boundary. :param xmax: maximum allowed value of the horizontal coordinate (meter) :param ymax: maximum allowed value of the vertical coordinate (meter) :param shape: aperture boundary shape: ``"rectangular"`` (default) or ``"elliptical"`` + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] -.. py:class:: impactx.elements.SoftQuadrupole(ds, gscale, cos_coefficients, sin_coefficients, nslice=1) +.. py:class:: impactx.elements.SoftQuadrupole(ds, gscale, cos_coefficients, sin_coefficients, dx=0, dy=0, rotation=0, mapsteps=1, nslice=1) A soft-edge quadrupole. @@ -746,19 +804,27 @@ References: (optional); default is a tanh fringe field model based on ``__ :param sin_coefficients: array of ``float`` sine coefficients in Fourier expansion of on-axis field gradient (optional); default is a tanh fringe field model based on ``__ + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] :param mapsteps: number of integration steps per slice used for map and reference particle push in applied fields :param nslice: number of slices used for the application of space charge -.. py:class:: impactx.elements.ThinDipole(theta, rc) +.. py:class:: impactx.elements.ThinDipole(theta, rc, dx=0, dy=0, rotation=0) A general thin dipole element. :param theta: Bend angle (degrees) :param rc: Effective curvature radius (meters) + :param dx: horizontal translation error in m + :param dy: vertical translation error in m + :param rotation: transversal rotation error around the z axis (in the x-y plane) [degrees] + + Reference: -Reference: * G. Ripken and F. Schmidt, Thin-Lens Formalism for Tracking, CERN/SL/95-12 (AP), 1995. + Coordinate Transformation -------------------------