A magnetic field element using generalized gradient expansion.
Parallel capable? : yes
GPU capable? : no
Backtracking 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  NULL  STRING  NULL  name of file containing generalized gradient data for normal terms, original convention 
NORMAL_FILENAME  NULL  STRING  NULL  name of file containing generalized gradient data for normal terms, new convention 
SKEW_FILENAME  NULL  STRING  NULL  name of file containing generalized gradient data for skew terms, new convention 
STRENGTH  NULL  double  1  factor by which to multiply field 
FACTOR0  NULL  double  1  factor by which to multiply field from m=0 (solenoid) terms 
FACTOR1  NULL  double  1  factor by which to multiply field from m=1 (dipole) terms 
FACTOR2  NULL  double  1  factor by which to multiply field from m=2 (quadrupole) terms 
FACTOR3  NULL  double  1  factor by which to multiply field from m=3 (sextupole) terms 
FACTOR4  NULL  double  1  factor by which to multiply field from m=4 (octupole) terms 
BXFACTOR  NULL  double  1  factor by which to multiply x component of field. Requires SYMPLECTIC=0. 
BYFACTOR  NULL  double  1  factor by which to multiply y component of field. Requires SYMPLECTIC=0. 
BGGEXP continued
A magnetic field element using generalized gradient expansion.
Parameter Name  Units  Type  Default  Description 
BZFACTOR  NULL  double  1  factor by which to multiply z component of field. Requires SYMPLECTIC=0. 
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 nonsymplectic integrator. 

SYNCH_RAD  short  0  if nonzero, include classical, singleparticle synchrotron radiation 

ISR  short  0  if nonzero, include incoherent synchrotron radiation (quantum excitation) 

PARTICLE_OUTPUT_FILE  STRING  NULL  name of file for phasespace 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. 
BGGEXP continued
A magnetic field element using generalized gradient expansion.
Parameter Name  Units  Type  Default  Description 
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 userdefined 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 floatingpoint columns:
The field expansion in this case is
 (30) 
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 floatingpoint columns:
The field expansion in this case is
 (31) 
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 C_{m,s}^{p} →C_{m,c}^{p} and dC_{m,s}^{p}∕dz →dC_{m,c}^{p}∕dz.
Data for use with BGGEXP can be prepared with the programs computeCBGGE (section 8.3) and computeRBGGE (section 8.4), which are distributed with elegant.
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:
In addition to the STRENGTH factor, there are five parameters that can be used to scale multipoles of different orders: FACTOR0, FACTOR1, FACTOR2, FACTOR3, and FACTOR4 scale the solenoidal, dipolar, quadrupolar, sextupolar, and octupolar fields, respectively. The BXFACTOR, BYFACTOR, and BZFACTOR allow multiplying the indicated field components by the given factors. The the exception of the STRENGTH factor, these scaling parameters may result in unphysical fields.
If IS_BEND is nonzero, the magnet is assumed to be a bending magnet, in which case additional parameters are required.
BMAPXY