Julia based code to calculate and manipulate generalized gradients.
Generalized gradients are functions that can be used to describe magnetic or electric fields in particle accelerators or storage rings. Currently, this repository is geared towards magnetic fields.
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.
gg_fit(field, params) 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 GGCoefs holding the fitted coefficients and
per-plane diagnostics. Use gg_fit_show_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(input; output_base, cutoff) is a function in the
GeneralizedGradients package that converts the gg coefficients produced by
gg_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_fit) or a loaded fit
(the fit GGCoefs 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_n, b_n, b_s) to Bmad's azimuthal-harmonic gradients C_{m,sin/cos} is
documented in the write_bmad_gg_fit docstring.
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.
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.
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 (n,m) with a(n,m)=dᵐaₙ/dsᵐ and
b(n,m)=dᵐbₙ/dsᵐ; bs keyed by m with bs(m)=dᵐ⁺¹a₀/dsᵐ⁺¹ = dᵐb_s/dsᵐ.
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.
Creates the table/gg_coef_table.jl table.
The created table contains the functions needed to calculate the coefficients for the taylor map of the magnetic field and the vector potential from the gg functions.
This table do not have to be recreated unless you want to extend the derivative range. Currently derivatives up to order 12 are tabulated. To run:
julia src/create_gg_coef_table.jl <deriv-cut>
where <deriv-cut> is the derivative cutoff number.
Creates the table/monomial_functions.jl table.
This table contains the coefficients needed to calculate the coefficients for the taylor map of the magnetic field and vector potential from the gg functions.
The information in this file is the same as the gg_coef_table.jl table except in a form that is useful for optimization and other calculations.
This table do not have to be recreated unless you want to extend the derivative range. Currently derivatives up to order 12 are tabulated. To run:
julia src/create_monomial_functions.jl <deriv-cut>
where <deriv-cut> is the derivative cutoff number.