10.6 BMXYZ—A map of (Bx, By, Bz) vs (x, y, z), for straight elements only

A map of (Bx, By, Bz) vs (x, y, z), for straight elements only
Parallel capable? : yes
GPU capable? : no
Back-tracking capable? : no






Parameter NameUnits Type Default

Description






L M double 0.0

insertion length






DX M double 0.0

misalignment






DY M double 0.0

misalignment






DZ M double 0.0

misalignment






TILT RAD double 0.0

rotation about longitudinal axis






LFIELD M double -1

expected length of the field map. If negative, determined from field data.






STRENGTH NULLdouble 1

factor by which to multiply field






FSE NULLdouble 0.0

Fractional Strength Error.






BXFACTOR NULLdouble 1

factor by which to multiply x component of field.






BYFACTOR NULLdouble 1

factor by which to multiply y component of field.






BZFACTOR NULLdouble 1

factor by which to multiply z component of field.






BXINSIDE NULLdouble 0.0

Constant Bx field to add inside the hard-edge boundaries.






BYINSIDE NULLdouble 0.0

Constant By field to add inside the hard-edge boundaries.






BZINSIDE NULLdouble 0.0

Constant Bz field to add inside the hard-edge boundaries.






BINSIDE_XMIN NULLdouble 0.0

Minimum x value at which BInside is applied.






BINSIDE_XMAXNULLdouble 0.0

Maximum x value at which BInside is applied.






ACCURACY NULLdouble 0.0

integration accuracy






METHOD NULLSTRINGNULL

integration method (runge-kutta, bulirsch-stoer, modified-midpoint, two-pass modified-midpoint, leap-frog, non-adaptive runge-kutta






BMXYZ continued

A map of (Bx, By, Bz) vs (x, y, z), for straight elements only






Parameter Name Units Type Default

Description






FILENAME NULLSTRINGNULL

name of file containing columns (x, y, z) and either (Bx, By, Bz) or (Fx, Fy, Fz)






SYNCH_RAD short 0

include classical, single-particle synchrotron radiation?






CHECK_FIELDS short 0

check fields by computing divB and curlB errors?






INJECT_AT_Z0 short 0

By default, particles are placed at the entrance to the field map regardless of the z coordinate values. If nonzero, particles start at z=0.






DRIFT_MATRIX short 0

If non-zero, instead of tracking to determine the matrix, just assume a drift-space matrix.






XY_INTERPOLATION_ORDER short 1

Order of interpolation in x and y.






XY_GRID_EXCESS short 0

Number of rows or columns to add in each dimension to the minimum.






SINGLE_PRECISION short 0

If nonzero, store field data in single precision to reduce memory requirements.






DISCARD_MAP short 0

If nonzero, field data is discarded after use. Reduces memory use but may result in additional delays for reading data again if needed.






VERBOSITY short 0

Larger values result in more informational printouts. Will reduce performance.






PARTICLE_OUTPUT_FILE NULLSTRINGNULL

name of file for phase-space output inside element. Use for debugging only in serial version.






BMXYZ continued

A map of (Bx, By, Bz) vs (x, y, z), for straight elements only






Parameter Name Units Type Default

Description






APCONTOUR NULLSTRINGNULL

name of element defining aperture contour inside the field map region.






ZMIN_APCONTOUR NULLdouble -8.98846567431158e+307

Minimum z value at which APCONTOUR apertures are applied.






ZMAX_APCONTOURNULLdouble 8.98846567431158e+307

Maximum z value at which APCONTOUR apertures are applied.






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 as a field map. It does this by simply integrating the Lorentz force equation in cartesian coordinates. It does not incorporate changes in the design trajectory resulting from the fields. I.e., if you input a dipole field, it is interpreted as a steering element.

The field map file is an SDDS file with the following columns:

The field map file must contain a rectangular grid of points, equispaced (separately) in x, y, and z. There should be no missing values in the grid (this is not checked by elegant). In addition, the x values must vary fastest as the values are accessed in row order, then the y values. To ensure that this is the case, use the following command on the field file:

sddssort fieldFile -column=z,incr -column=y,incr -column=x,incr

This element is an alternative to FTABLE using a more conventional integration method.

The BXFACTOR, BYFACTOR, and BZFACTOR allow multiplying the indicated field components by the given factors. These scaling parameters may result in unphysical fields.

By default, the BMXYZ element should be supplied with the full 3D field map of the magnet. To allow saving memory and reducing the file to load data, partial magnetic field maps can be loaded as well, but the user must specify the symmetry of the magnet to ensure that the fields are modeled correctly in the full volume. This is done using three optional parameters in the input file, xSymmetry, ySymmetry, and zSymmetry. If present, these must have one of three none (default), even, and odd.

For example, a normal quadrupole magnet would have xSymmetry=odd, ySymmetry=odd, and zSymmetry=even. A left/right symmetric dipole or sextupole would have xSymmetry=even, ySymmetry=odd, zSymmetry=even. A normal octupole would have the same symmetry codes as a normal quadrupole. Note that when using these symmetries, the user is not required to limit the field map to, say, x 0, y 0, and z 0, though doing so saves the most memory. If possible, it is recommended to provide the fields over x ≥-x, y ≥-y, and z 0, so that the transverse interpolation as a few points on both sides of the origin. This will ensure better results near the origin.

Internally, elegant stores only the partial field map. When field values are required outside this region, the declared symmetries are used to map the coordinates to the covered region and change signs of the various field components if required.

Internal apertures may be specified using four methods, as used in elements like KQUAD and CSBEND. The methods include upstrea MAXAMP elements, upstream APCONTOUR elements with STICKY=1, s-dependent apertures defined via the aperture_data command, and global-coordinate system apertures defined via the obstruction_data command.

For APCONTOUR-defined apertures, this can be invoked using the STICKY=1 parameter, which is used to impose the aperture contour on downstream elements. One fine point is that the field map is typically significantly longer than the magnet itself. We don’t want to apply the apertures except in some region in the interior of the field map This can be specified using the ZMIN_APCONTOUR and ZMAX_APCONTOUR parameters, which give the range of application in the coordinate system of the field map. In this case, to prevent application of the APCONTOUR apertures at the point of definition, the APCONTOUR element should have HOLDOFF=1 and be inserted in the lattice just before the BMXYZ element.

BOFFAXE