11.4 computeLBGGE

• description: Compute generalized gradients [37] from a three-dimensional field map using the local least-squares (“Bmad”) method of D. Sagan et al. [3], for use with elegant’s BGGEXP element. Unlike computeRBGGE, which reconstructs the generalized gradients from field data on four rectangular boundary planes, computeLBGGE performs an independent weighted least-squares fit at each z plane using field samples drawn from the surrounding volume within a short z window. It is slower than computeRBGGE but typically provides considerably more accurate fits, and is recommended instead when a full three-dimensional field map is available. The output files are in the same format as those from computeRBGGE and computeCBGGE.
• synopsis:

  computeLBGGE -fieldMap=<filename> -normal=<output> [-skew=<output>] [-derivatives=<integer>] [-multipoles=<integer>] [-fundamental=<integer>] [-varyDerivatives] [-deltaZ=<meters>] [-coreWeight=<value>] [-xMax=<meters>] [-yMax=<meters>] [-xCenter=<meters>] [-yCenter=<meters>] [-threads=<integer>] [-verbose] [-autotune[,significance=<fieldValue>][,minimize={rms|mav|maximum}] [,radiusLimit=<meters>][,xLimit=<meters>][,yLimit=<meters>] [,increaseOnly][,evaluate][,verbose][,log=<filename>] [,minDerivatives=<integer>][,minMultipoles=<integer>]] [-evaluate=<filename>]

• switches:
  • fieldMap — SDDS file containing the three-dimensional field map, with columns x, y, z (in meters) and Bx, By, Bz (in Tesla). The distinct z values in the map define the output z planes and must be uniformly spaced.
  • normal — Output file for normal-component generalized gradients. Supply to NORMAL_FILENAME parameter of BGGEXP.
  • skew — Output file for skew-component generalized gradients. Supply to SKEW_FILENAME parameter of BGGEXP. NB: if B_z is non-zero on axis, this option is essential in getting valid results.
  • derivatives — Number of derivatives vs z desired in output. Default: 7. With -autotune, this is the maximum number of derivatives.
  • multipoles — Number of multipoles desired in output. Default: 8. With -autotune, this is the maximum number of multipoles.
  • fundamental — Fundamental multipole of sequence. 0=none (default), 1=dipole, 2=quadrupole, etc.
  • varyDerivatives — If given, the number of derivatives used varies with multipole order so as to maintain an approximately consistent maximum transverse order.
  • deltaZ — Half-width (in meters) of the z window used for each local fit. By default, twice the z-plane spacing, giving a five-plane window in the interior.
  • coreWeight — Core weighting factor w_c ≥ 1; larger values up-weight near-axis samples in the fit. Default: 1 (uniform weighting).
  • xMax, yMax — Half-aperture of the expansion, in meters. Default: the transverse extent of the field map.
  • xCenter, yCenter — Center of the expansion, in meters. Default: the midpoint of the field map’s transverse extent.
  • threads — Number of threads to use for the per-plane fits. Default: 1.
  • verbose — Print progress information.
  • evaluate — Asks to evaluate the GGE and write the reconstructed field, together with the residual relative to the field map, at each in-aperture sample point.
  • autotune — Optimizes the number of derivatives and multipoles up to the values given with the -derivatives and -multipoles options, in order to minimize the deviation of the GGE-derived fields from the values given in the field map. Because this is a least-squares method, the fit is repeated for each candidate model. The three-dimensional map used for the goodness-of-fit test is simply the -fieldMap already supplied, so no map filename is given here. By default, minimizes the maximum deviation, but the user can ask to minimize the rms or mean-absolute-value deviation. Differences below the significance value are ignored. The xLimit, yLimit, and radiusLimit qualifiers restrict the goodness-of-fit test to samples near the axis, measured from the expansion center. The user may request verbose output to see results printed to the terminal, and also a log file for a detailed record. The increaseOnly qualifier specifies that the scan over multipoles m and derivatives d is restricted to never be less than the previous optimal values; for example, if the best value so far was obtained with m = 4 and d = 3, the remainder of the scan would be restricted to m ≥ 4 and d ≥ 3; this can save considerable run time. The evaluate qualifier disables tuning and simply reports the residual at the maximum model. The minDerivatives and minMultipoles parameters allow requiring the auto-tuner to use a minimum number of derivatives and multipoles, respectively; by default, as few as 1 of each might be used.
• authors: Claude Code, M. Borland, R. Soliday, R. Lindberg (ANL/APS); local least-squares method by D. Sagan et al.