10.3 BGGEXP—A magnetic field element using generalized gradient expansion.

A magnetic field element using generalized gradient expansion.
Parallel capable? : yes
GPU capable? : no
Back-tracking capable? : no






Parameter Name Units Type Default

Description






L M double 0.0

insertion length






LFIELD M double -1

expected length of the field map. If negative, use L.






FILENAME NULLSTRINGNULL

name of file containing generalized gradient data for normal terms, original convention






NORMAL_FILENAMENULLSTRINGNULL

name of file containing generalized gradient data for normal terms, new convention






SKEW_FILENAME NULLSTRINGNULL

name of file containing generalized gradient data for skew terms, new convention






STRENGTH NULLdouble 1

factor by which to multiply field






TILT RAD double 0.0

rotation about longitudinal axis






DX M double 0.0

misalignment






DY M double 0.0

misalignment






DZ M double 0.0

misalignment






BX T double 0.0

add BX*STRENGTH to Bx field






BY T double 0.0

add BY*STRENGTH to By field






MAXIMUM_M short -1

data with m greater than this is ignored






MAXIMUM_2N short -1

data with 2*n greater than this is ignored






Z_INTERVAL short 1

input z data is sampled at this interval






SYMPLECTIC short 0

if nonzero, use implicit symplectic integrator. At minimum, should always be used to validate the sufficiency of the non-symplectic integrator.






SYNCH_RAD short 0

if nonzero, include classical, single-particle synchrotron radiation






BGGEXP continued

A magnetic field element using generalized gradient expansion.






Parameter Name UnitsType Default

Description






ISR short 0

if nonzero, include incoherent synchrotron radiation (quantum excitation)






PARTICLE_OUTPUT_FILE STRINGNULL

name of file for phase-space and field output. Use for debugging only!






IS_BEND short 0

if nonzero, magnet is a bending magnet; vertex, entry, and exit points should be defined.






XVERTEX M double 0.0

For dipoles: x position of vertex in coordinate system of the fields.






ZVERTEX M double 0.0

For dipoles: z position of vertex in coordinate system of the fields.






XENTRY M double 0.0

For dipoles: x position of reference entry point in coordinate system of the fields.






ZENTRY M double 0.0

For dipoles: z position of reference entry point in coordinate system of the fields.






XEXIT M double 0.0

For dipoles: x position of reference exit point in coordinate system of the fields.






ZEXIT M double 0.0

For dipoles: z position of reference exit point in coordinate system of the fields.






DXEXPANSION M double 0.0

x position of the generalized gradient expansion relative to the reference trajectory.






GROUP string NULL

Optionally used to assign an element to a group, with a user-defined name. Group names will appear in the parameter output file in the column ElementGroup






This element simulates transport through a 3D magnetic field specified in terms of a generalized gradient expansion [50]. After reconstructing the field, it simply integrates the equations of motion based on the Lorentz force equation in cartesian coordinates.

The generalized gradients are provided in SDDS files. In addition to several columns describing the gradients, the file must contain a parameter:

The files may also include optional parameters xCenter and yCenter giving the center of the expansion in meters.

In the original implementation, which is still supported, only normal field components were included In that case, the user should use the FILENAME field to provide a file with the following floating-point columns:

The field expansion in this case is

                                   {              }
B   =   ∑∞  ∞∑  (-1)nm!(2n+m)r2n+m -1  C[2n](z)sinm ϕ
 r      m=1 n=0  4nn!(n+m)!            m
        ∑∞  ∞∑  (-1)nm!m) 2n+m- 1{  [2n]         }
Bϕ  =   m=1 n=04nn!(n+m )!r        C m  (z)cosm ϕ
        ∑∞  ∞∑   (-1)nm!  2n+m {  [2n+1]         }
Bz  =          4nn!(n+m-)!r      C m    (z)sin m ϕ
        m=0 n=0
(28)

where it is understood that the expansion is about the xCenter and yCenter values, if given.

Note that there is potential confusion between the xCenter parameter in the input files and the DXEXPANSION parameter in the element definition. These provide similar functionality and only one is needed. Both give the position of the horizontal center of the expansion relative to the magnetic field coordinate system.

In version 2020.5 and later, both normal and skew expansions are supported. In this case, the user may provide filenames via the NORMAL_FILENAME and SKEW_FILENAME fields. In this, case, the files must contain the following floating-point columns:

The field expansion in this case is

         ∞∑  ∞∑  (-1)nm!(2n+m )       {   [2n]            [2n]         }   ∞∑  (-1)n2n       [2n]
Br  =          --4nn!(n+m-)!-r2n+m -1  Cm,s(z)sinm ϕ + Cm,c(z)cosm ϕ  +     -4nn!n! r2n-1C 0,c (z)
        m=∞∑1 n∞∑=0    n            {                              }      n=1
Bϕ  =          4(-n1n)!(nm+!mm))!r2n+m -1  C[m2n,]s(z)cosm ϕ - C[m2,nc](z)sinm ϕ
        m=∞1 n∞=0               {                                  }
Bz  =    ∑  ∑  -n(-1)nm!-r2n+m  C [m2n,+s1](z)sin m ϕ+  C[m2n,+c1](z)cosm ϕ
        m=0 n=04 n!(n+m )!
(29)

where it is understood that the expansion is about the xCenter and yCenter values, if given. Users should note that the skew field sign convention used by [50] and BGGEXP differs from that used in elegant. In particular, to convert a normal field to a skew field while conforming to elegant’s conventions, one must use Cm,sp →-Cm,cp.

A normal-field generalized gradient file (for use with FILENAME) can be prepared using the script computeGeneralizedGradients, which is provided with elegant. The input file for that script must be organized into many pages, with each page giving Br(ϕ) on radius r = R for a single z location. The file must contain two floating-point columns:

In addition, the file must contain two floating-point parameters:

Synchrotron radiation can be included by setting SYNCH_RAD=1 for classical radiation only and also ISR=1 for incoherent (quantum) effects. This will impact the results of moments_output calculation as well as tracking.

Important notes and limitations:

  1. The calculations of twiss_output, including radiation integrals, are at this point not affected, nor is the setup of rf cavities for storage rings via the rf_setup command.
  2. The symplectic integrator, in addition to being symplectic, is typically more accurate than the non-symplectic integrator. It is also considerably slower. However, at minimum, users should use the symplectic integrator to verify that the accuracy of the non-symplectic integrator is adequate.
  3. The BX and BY parameters allow imposing uniform horizontal and vertical magnetic fields on the device. This can be helpful if the terminal trajectory deviates from the expected value, e.g., an on-axis particle ends up off-axis. This may happen if the device has a dipolar field that is truncated at the ends before it has decayed sufficiently. Note that these values are multiplied by the STRENGTH factor before being applied to the beam.

If IS_BEND is non-zero, the magnet is assumed to be a bending magnet, in which case additional parameters are required.

BMAPXY