10.7 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

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

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:

• x, y, x — Transverse coordinates in meters (units should be “m”).
• Fx, Fy, Fx — Normalized field values (no units). The field is multiplied by the value of the STRENGTH parameter to convert it to a local bending radius. For example, an ideal quadrupole could be simulated by setting (Fx=y, Fy=x, Fz=0), in which case STRENGTH is the K1 quadrupole parameter.
• Bx, By, Bz — Field values in Tesla (units should be “T”). The field is still multiplied by the value of the STRENGTH parameter, which is dimensionless.

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:

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 ≥-2Δx, y ≥-2Δ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.