Merge from upstream

zgoubi_metadata/data/elements_yaml/DIPOLES.yaml

@@ -17,7 +17,7 @@ template:
 - - N
   - AT
   - RM
-- - subelement1
+- - {field_region}
 - - KIRD
   - RESOL
 - - XPAS

zgoubi_metadata/data/elements_yaml/OCTUPOLE.yaml

@@ -17,7 +17,7 @@ params:
   LAM_S: {type: E, unit: "cm", default: 0, doc: "Exit face fringe field extent"}
   NCS: {type: I, default: 0, doc: "UNUSED"}
   CS_0: {type: E, default: 0, doc: "Fringe field coefficient C0"}
-  CS_1: {type: E, default: 1 doc: "Fringe field coefficient C1"}
+  CS_1: {type: E, default: 1, doc: "Fringe field coefficient C1"}
   CS_2: {type: E, default: 0, doc: "Fringe field coefficient C2"}
   CS_3: {type: E, default: 0, doc: "Fringe field coefficient C3"}
   CS_4: {type: E, default: 0, doc: "Fringe field coefficient C4"}
@@ -61,13 +61,25 @@ doc: |
 
   .. rubric:: Zgoubi manual description
 
-  The meaning of parameters for OCTUPOLE is the same as for QUADRUPO. In fringe field regions the
-  magnetic field ~B (X, Y,Z) and its derivatives up to fourth order are derived from the scalar potential approximated
-  to the 8-th order in Y and Z
+    The meaning of parameters for ``OCTUPOLE`` is the same as for ``QUADRUPO``.
 
-  The modelling of the fringe field form factor G(X) is described under QUADRUPO, p. 128.
-  Outside fringe field regions, or everywhere in sharp edge dodecapole (λE = λS = 0) , ~B(X, Y,Z) in the
-  magnet is given by
-  BX = 0
-  BY = G0(3Y 2 − Z2)Z
-  BZ = G0(Y 2 − 3Z2) Y
+    In fringe field regions the magnetic field :math:`\vec{B}(X, Y, Z)` and its derivatives up to fourth order are derived
+    from the scalar potential approximated to the 6th order in Y and Z
+
+    .. math::
+
+        V(X,Y,Z) = (G(X) - \frac{G''(X)}{20} (Y^2 + Z^2) + \frac{G'''(X)}{960} (Y^2 + Z^2)^2)(Y^3Z - YZ^3)
+
+    with :math:`G_0 = \frac{B_0}{R_0^3}`
+
+    The modelling of the fringe field form factor G(X) is described under ``QUADRUPO``, p. 128.
+    Outside fringe field regions, or everywhere in sharp edge octupole (:math:`λ_E = λ_S = 0`),
+    :math:`\vec{B}(X, Y, Z)` in the magnet is given by
+
+    .. math::
+
+        \begin{align}
+            B_X &= 0 \\
+            B_Y &= G_0 (3 Y^2 − Z^2) Z \\
+            B_Z &= G_0 (Y^2 − 3 Z^2) Y
+        \end{align}

zgoubi_metadata/data/elements_yaml/QUADRUPO.yaml

@@ -17,7 +17,7 @@ params:
   LAM_S: {type: E, unit: "cm", default: 0, doc: "Exit face fringe field extent"}
   NCS: {type: I, default: 0, doc: "UNUSED"}
   CS_0: {type: E, default: 0, doc: "Fringe field coefficient C0"}
-  CS_1: {type: E, default: 1 doc: "Fringe field coefficient C1"}
+  CS_1: {type: E, default: 1, doc: "Fringe field coefficient C1"}
   CS_2: {type: E, default: 0, doc: "Fringe field coefficient C2"}
   CS_3: {type: E, default: 0, doc: "Fringe field coefficient C3"}
   CS_4: {type: E, default: 0, doc: "Fringe field coefficient C4"}
@@ -55,16 +55,57 @@ template:
   - XCE
   - YCE
   - ALE
-
 doc: |
   Quadrupole magnet
 
   .. rubric:: Zgoubi manual description
 
-  The length of the magnet XL is the distance between the effective field boundaries (EFB), Fig. 35. The field
-  at the pole tip R0 is B0. The extent of the entrance (exit) fringe field is characterized by λE(λS). The distance of ray-tracing on both sides of the EFBs, in the field fall off regions,
+  The length of the magnet XL is the distance between the effective field boundaries (EFB), Fig. 35. The field at the pole tip R0 is B0.
+  The extent of the entrance (exit) fringe field is characterized by :math:`\lambda_E` (:math:`\lambda_S`). The distance of ray-tracing on both sides of the EFBs, in the field fall off regions,
   will be ± XE at the entrance, and ± XS at the exit (Fig. 35), by prior and further automatic change of frame.
-  In the fringe field regions [−XE,XE] and [−XS,XS] on both sides of the EFBs, ~B (X, Y,Z) and its derivatives
-  up to fourth order are calculated at each step of the trajectory from the analytical expressions of the
-  three components BX, BY , BZ obtained by differentiation of the scalar potential (see section 1.3.7) expressed
-  to the 8th order in Y and Z.
+  In the fringe field regions [−XE,XE] and [−XS,XS] on both sides of the EFBs, :math:`\vec{B}(X, Y, Z)` and its derivatives up to fourth
+  order are calculated at each step of the trajectory from the analytical expressions of the three components
+  BX, BY , BZ obtained by differentiation of the scalar potential (see section 1.3.7) expressed to the 8th order in Y and Z.
+
+  .. math::
+
+    \begin{align}
+      V(X,Y,Z) = (G(X) - \frac{G''(X)}{12} (Y^2 + Z^2) + \frac{G''''(X)}{384} (Y^2 + Z^2)^2 - \frac{G''''''(X)}{23040} (Y^2 + Z^2)^3) YZ \\
+      G^{(n)} &= \frac{d^n G(X)}{dX^n} \\
+    \end{align}
+
+  where G(X) is the gradient on axis
+
+  .. math::
+
+    G(X) = \frac{G_0}{1 + exp P(d(X))}
+
+  with :math:`G_0 = \frac{B_0}{R_0}`
+
+  and,
+
+  .. math::
+
+    P(d) = C_0 + C_1 (\frac{d}{\lambda}) + C_2 (\frac{d}{\lambda})^2 + C_3 (\frac{d}{\lambda})^3 + C_4 (\frac{d}{\lambda})^4 + C_5 (\frac{d}{\lambda})^5
+
+    where d(X) is the distance to the field boundary and :math:`\lambda` stands for :math:`\lambda_E` or :math:`\lambda_E` (normally, :math:`\lambda` ≃ 2 * R0).
+    When fringe fields overlap inside the magnet (XL ≤ XE + XS), the gradient G is expressed as
+
+    .. math::
+
+      G = G_E + G_S - 1
+
+
+  where, :math:`G_E` is the entrance gradient and :math:`G_S` is the exit gradient.
+  If :math:`\lambda_E` = 0 (:math:`\lambda_S` = 0), the field at entrance (exit) is considered as sharp edged, and then XE(XS) is forced to zero
+  (for the mere purpose of saving computing time).
+  Outside of the fringe field regions (or everywhere when :math:`\lambda_E` = :math:`\lambda_S` = 0) :math:`\vec{B}(X, Y, Z)` in the magnet is given
+  by
+
+  .. math::
+
+    \begin{align}
+      B_X &= 0 \\
+      B_Y &= G_0 Z \\
+      B_Z &= G_0 Y
+    \end{align}

zgoubi_metadata/data/elements_yaml/SEXTUPOL.yaml

@@ -17,7 +17,7 @@ params:
   LAM_S: {type: E, unit: "cm", default: 0, doc: "Exit face fringe field extent"}
   NCS: {type: I, default: 0, doc: "UNUSED"}
   CS_0: {type: E, default: 0, doc: "Fringe field coefficient C0"}
-  CS_1: {type: E, default: 1 doc: "Fringe field coefficient C1"}
+  CS_1: {type: E, default: 1, doc: "Fringe field coefficient C1"}
   CS_2: {type: E, default: 0, doc: "Fringe field coefficient C2"}
   CS_3: {type: E, default: 0, doc: "Fringe field coefficient C3"}
   CS_4: {type: E, default: 0, doc: "Fringe field coefficient C4"}
@@ -61,6 +61,25 @@ doc: |
 
   .. rubric:: Zgoubi manual description
 
-  The meaning of parameters for SEXTUPOL is the same as for QUADRUPO.
-  In fringe field regions the magnetic field ~B (X, Y,Z) and its derivatives up to fourth order are derived from
-  the scalar potential approximated to 7th order in Y and Z
+  The meaning of parameters for ``SEXTUPOL`` is the same as for ``QUADRUPO``.
+
+  In fringe field regions the magnetic field :math:`\vec{B}(X, Y, Z)` and its derivatives up to fourth order are derived
+  from the scalar potential approximated to the 6th order in Y and Z
+
+    .. math::
+
+      V(X,Y,Z) = (G(X) - \frac{G''(X)}{16} (Y^2 + Z^2) + \frac{G''''(X)}{640} (Y^2 + Z^2)^2)(Y^2Z - \frac{Z^3}{3})
+
+    with :math:`G_0 = \frac{B_0}{R_0^2}`
+
+    The modelling of the fringe field form factor G(X) is described under ``QUADRUPO``, p. 128.
+    Outside fringe field regions, or everywhere in sharp edge sextupole (:math:`λ_E = λ_S = 0`),
+    :math:`\vec{B}(X, Y, Z)` in the magnet is given by
+
+    .. math::
+
+      \begin{align}
+        B_X &= 0 \\
+        B_Y &= 2 G_0 Y Z \\
+        B_Z &= G_0 (Y^2 − Z^2)
+      \end{align}

zgoubi_metadata/data/elements_yaml/SOLENOID.yaml

@@ -29,3 +29,55 @@ doc: |
   Solenoid
 
   .. rubric:: Zgoubi manual description
+
+  The solenoidal magnet has an effective length XL, a mean radius R0 and an asymptotic field :math:`B_0 = \mu_0 N I /XL`
+  (i.e., assuming :math:`R_0` << L, \int_{-\infty}^{\infty} B_X(X,r) dX = \mu_0 N I , \forall r < R_0 ), wherein NI = number of ampere-Turns,
+  :math:`\mu_0 = 4\pi 10-7`. The distance of ray-tracing beyond the effective length XL, is XE at the entrance,
+  and XS at the exit (Fig. 38).
+  Two methods are available for the computation of the field :math:`\vec{B}(X, Y, Z)` and its derivatives.
+
+  **Method 1**
+
+  This is the classical on-axis field model [9]
+
+  .. math::
+
+    B_X(X, r=0) = \frac{B_0}{2} \left[ \frac{XL /2 - X}{\sqrt{(XL /2 - X)^2 + R_0^2}} + \frac{XL /2 + X}{\sqrt{(XL /2 + X)^2 + R_0^2}} \right]
+
+  with X = r = 0 taken at the center of the solenoid. This model assumes that the coil thickness is small
+  compared to its mean radius R0. In this model, the magnetic length is
+
+  .. math::
+
+    L_{mag} \equiv \frac{\int_{-\infty}^{\infty} B_X(X,r < R_0) dX}{B_X(X = r = 0)} = XL \sqrt{ 1 + \frac{4R_0^2}{XL^2}} > XL
+
+  with in addition
+
+  .. math::
+
+    B_X(center) \equiv B_X(X = r = 0) = \frac{\mu_0 N I}{XL \sqrt{ 1 + \frac{4R_0^2}{XL^2}}} \xrightarrow{R_0 << XL} \frac{\mu_0 N I}{ XL}
+
+  From eq. 6.3.27, the field and its derivatives at all (X, Y,Z) are extrapolated (the model validity limit is r < R0),
+  following the method described in section 1.3.1.
+
+  **Method 2**
+
+  The computation of the radial, :math:`B_r(X, r)`, and axial :math:`B_X(X, r)` components of the field vector :math:`\vec{B}(X, r)`
+  (with  :math:`r = (Y^2 + Z^2)^{1/2}`) follows the technique in Ref. [61], namely, constructing :math:`B_r(X, r)`, and :math:`B_X(X, r)` from
+  respectively
+
+  .. math::
+
+  \begin{align}
+    b_X(X, r) &= \frac{\mu_0 N I}{4\pi}\frac{ck}{r} \chi \left[ K + \frac{r_0 - r}{2r_0} (\Pi - K)\right] \\
+    b_r(X, r) &= \mu_0 N I\frac{1}{k} \sqrt{\frac{r_0}{r}} \left[ 2(K - E) -k^2 K)\right] \\
+  \end{align}
+
+  wherein K, E and :math:`\Pi` are the three complete elliptic integrals, :math:`\chi` is an X- and XL-dependent quantity, and
+
+  .. math::
+
+    k = 2 \sqrt{r_0 r} / \sqrt{(r_0 +  r)^2 + \chi ^2}; c = 2 \sqrt{r_0 r} / (r_0 + r)
+
+  K, E and :math:`\Pi` are computed using fast converging algorithms proposed in the same reference. Their derivatives
+  are obtained from recursive relations [62], as needed to derive the field derivatives at all (X, Y,Z) (up to second order installed in the code).