Generalized Gradients Overview

Julia based code to calculate and manipulate generalized gradients.

Generalized gradients are functions that can be used to describe static magnetic or electric fields in particle accelerators or storage rings.

The notation follows that of S. Van der Schueren et al. “Magnetic Field Modelling and Symplectic Integration of Magnetic Fields on Curved Reference Frames for Improved Synchrotron Design: First Steps” A copy of this paper is in the papers directory.

Equations for the vector potential are described in papers/vector-potential/vector-potential.tex Here "the gg functions" refer to the functions a(s), b(s), and bs(s) and their derivatives.

Functions

gg_calc_fit (src/gg_fit.jl)

gg_calc_fit(field, params, fit_at) is a function in the GeneralizedGradients package that calculates values for the gg functions that fit a given field table. It takes a FieldGridTable (field, typically from read_field_grid_hdf5) and a GGFitInputParams (params) and returns a GGFit holding the fitted coefficients and per-plane diagnostics. Use gg_show_fit_results to print a summary and write_gg_fit to write the results to an HDF5 file (readable by read_gg_fit). See examples/run_gg_fit.jl for a runnable example. The fit assumes that the field table is defined on an evenly spaced grid and the gg function values are calculated on (x, y) planes coincident with the planes of the grid.

Note: The restriction that the field table must be defined on a grid is not strictly necessary and, in the future, a program that does not make this assumption could be created. Additionally, the calculation of the gg functions at equal spacing longitudinally is not a fundamental requirement. In fact, it may be advantageous to have unequal spacing in cases where the field of a magnet body is fairly uniform, so that a coarse spacing is adequate, but the fringe regions need a fine spacing.

write_bmad_field_grid_element (src/field_grid_utils.jl) and programs/run_write_bmad_field_grid_element.jl

write_bmad_field_grid_element(field; ele_name, output_base, field_scale, hdf5) is a function in the GeneralizedGradients package that writes a 3D field grid out in Bmad grid_field format, producing a Bmad lattice element with the field grid attached. It can be run from the shell with

julia programs/run_write_bmad_field_grid_element.jl <field_grid.h5> [output_base] [--text]

field is either a FieldGridTable or the path to a Bmad openPMD field_grid HDF5 file (read by read_field_grid_hdf5). Two files are written: <output_base>.bmad (the lattice element) and the attached grid, either <output_base>_grid.h5 (openPMD HDF5, the default) or <output_base>_grid.bmad (plain-text block, with --text / hdf5 = false). The reference-curve bending strength is taken from the field grid's g_ref = 1/bend_radius [1/m]; if non-zero the element is an sbend, otherwise an em_field.

write_bmad_gg_fit (src/write_bmad_gg_fit.jl) and programs/run_write_bmad_gg_fit.jl

write_bmad_gg_fit(input; output_base, cutoff) is a function in the GeneralizedGradients package that converts the gg coefficients produced by gg_calc_fit into Bmad gen_grad_map format, producing a Bmad lattice element with the generalized-gradient map attached. It can be run from the shell with

julia programs/run_write_bmad_gg_fit.jl <gg_fit_result.h5> [output_base] [cutoff]

The input is either a gg-fit file (output of gg_calc_fit) or a loaded fit (the fit GGFit struct returned by read_gg_fit, passed as write_bmad_gg_fit(fit; ...)). Two files are written: <output_base>.bmad (the lattice element) and <output_base>_gg.bmad (the attached gen_grad_map). cutoff is a relative magnitude threshold for pruning negligible multipole curves (default 0, keep every non-zero curve). The exact conversion from the project's midplane-derivative gg functions (a_m, b_m, b_s) to Bmad's azimuthal-harmonic gradients C_{m,sin/cos} is documented in the write_bmad_gg_fit docstring.

field_and_potential_evaluate_at(fit, x::Real, y::Real, s::Real) ->

Function in src/gg_eval.jl. Function to evaluate the field, vector potential, and vector potential derivative matrix for a given set of gg function values.

field_coefficients_at_s(fit, s::Real)

Function in src/gg_eval.jl Function to take the gg function values generated by gg_fit.jl and output the field-expansion coefficients C_{c,i,j} (the coefficients of x^i y^j in each field component) at a particular s-position.

gg_coefficients_at_plane(fit, ip::Integer)

Function in src/gg_eval.jl Returns the generalized-gradient coefficients at grid plane index ip as three dicts (a, b, bs) of scalar values: a and b keyed by (m,nd) with a(m,nd)=dⁿᵈaₘ/dsⁿᵈ and b(m,nd)=dⁿᵈbₘ/dsⁿᵈ; bs keyed by nd with bs(nd)=dⁿᵈ⁺¹a₀/dsⁿᵈ⁺¹ = dⁿᵈb_s/dsⁿᵈ.

gg_coefficients_at_s(fit, s::Real)

Function in src/gg_eval.jl Returns the generalized-gradient coefficients (a, b, bs) at an arbitrary s, Hermite-interpolated from the straddling grid planes (the same interpolation used by field_and_potential_evaluate_at). Returns the three dicts of scalar values as in gg_coefficients_at_plane.

Programs

programs/create_field_to_gg_coef_tables.jl

Creates both of the tables in the tables directory:

• tables/gg_coef_table.jl — the functions needed to calculate the coefficients for the taylor map of the magnetic field and the vector potential from the gg functions. This is the table the package includes and gg_calc_fit uses.
• tables/monomial_functions.jl — the same information keyed by monomial instead of by gg function, and written as readable symbolic expressions rather than numeric tuples. Useful for optimization and other calculations, and for checking against the paper. The package does not use it.

Both are the same Taylor expansion, so one program computes it once and writes it out in the two forms. That also keeps the two tables from drifting apart: they are always built from the same expansion at the same parameters.

The tables do not have to be recreated unless you want to extend the derivative range. Currently derivatives up to order 13 are tabulated. To run:

julia programs/create_field_to_gg_coef_tables.jl                    # the tabulated defaults
MAXTOT=16 MMAX=17 julia programs/create_field_to_gg_coef_tables.jl   # larger tables

The two input parameters are read from the environment:

• MAXTOT (default 13) — maximum total degree p+q of the x^p y^q monomials kept.
• MMAX (default 14) — maximum multipole order m of the a_m and b_m functions.

The program records both in the header of each table it writes, and in gg_coef_table.jl also as documented constants MAXTOT and MMAX. The package includes that table, so the parameters of the table actually in use are available from the REPL:

julia> using GeneralizedGradients

julia> MMAX          # and ?MMAX for the full documentation
14

MMAX may not exceed MAXTOT + 1, since the expansion is truncated at x^(MAXTOT+1); the program stops with an error rather than silently dropping the top multipoles. Cost grows steeply with MAXTOT — the default tables take a while to rebuild.