Compatibility with MADX
The DiPAS package ships with a MADX parser which can parse most of the MADX syntax. Hence parsing lattices from
MADX files should work without problems in most cases.
Due to the (dynamically typed) nature of the parser a few noteworthy differences
to the MADX syntax exist however and are explained in the following sub-sections.
An essential add-on to the syntax is described as well.
If desired, the parsing process can be further customized via the madx.parser
module attributes. Please
refer to this module’s documentation for more information.
The MADX parser is fully contained in the madx
subpackage. The main entry functions for parsing MADX scripts are
madx.parse_file
and madx.parse_script
.
Declaring variables used for the optimization process (add-on)
This is an addition to the existing MADX syntax and in order not to interfere with it, this is realized via placement of
special comments. Since the purpose of differentiable simulations is to optimize some set of parameters, a seamless
syntax for indicating the relevant parameters is desirable (we call these to-be-optimized-for parameters
“flow variables”). This can be done directly in the MADX scripts, by placing special comments of the form
// <optional text goes here> [flow] variable
, i.e. a comment that is concluded with the string [flow] variable
.
These can be placed in three different ways to mark a variable (or attribute) as an optimization parameter.
On the same line as the variable definition:
q1_k1 = 0; // [flow] variable
q1: quadrupole, l=1, k1=q1_k1;
On the line preceding the variable definition:
// [flow] variable
q1_k1 = 0;
q1: quadrupole, l=1, k1=q1_k1;
On the same line that sets an attribute value:
q1: quadrupole, l=1, k1=0;
q1->k1 = 0; // [flow] variable
All of the above three cases will create a Quadrupole element with variable (to be optimized) k1
attribute with
initial value set to 0
.
The same syntax also works with error definitions, for example:
SELECT, flag = error, class = quadrupole;
dx = 0.001; // [flow] variable
EALIGN, dx = dx;
This will cause all Quadrupole elements to have an initial alignment error of dx = 0.001
which are however variable
during the optimization process.
Flow variables also work with deferred expressions:
SELECT, flag = "error", class = "quadrupole";
dx := ranf() - 0.5; // [flow] variable
EALIGN, dx = dx;
Here again each Quadrupole’s dx
alignment error will be optimized for and has a random initial value in
[-0.5, 0.5]
.
Variations to the MADX syntax
Beam command - For
BEAM
commands the particle type as well as the beam energy must be unambiguously specified (viaparticle
or{mass, charge}
and one ofenergy, pc, beta, gamma, brho
).String literals - String literals without spaces may be unquoted only for the following set of command attributes:
{'particle', 'range', 'class', 'pattern', 'flag', 'file', 'period', 'sequence', 'refer', 'apertype', 'name', 'from'}
. Which attributes are considered to be string attributes is regulated by themadx.command_str_attributes
variable and users may add their own names if appropriate. All other string attributes must use quotation marks for correct parsing.Variable names - All variable names containing a dot
.
will be renamed by replacing the dot with an underscore. In case a similar name (with an underscore) is already used somewhere else in the script a warning will be issued. The string which will be used to replace dots in variable names can be configure viamadx.replacement_string_for_dots_in_variable_names
. It needs to be part of the set of valid characters for Python names (see the docs, basically this is[A-Za-z0-9_]
).Defaults for unknown variable names - By default, if MADX encounters an unknown (i.e. yet undefined) variable name, it assumes a value of
0
for it. DiPAS has more fine-grained control via the attributesdipas.madx.parser.allow_popup_variables
(defaultTrue
) anddipas.madx.parser.missing_variable_names
(default empty). The former controls whether expressions that consist of a single variable name, e.g.undefined
inquadrupole, k1 = undefined
, default to zero or raise an error. The latter is a mapping from deliberately missing variable names (or patterns describing these names) to desired default values. This dictionary can filled by the user, e.g.dipas.madx.parser.missing_variable_names['k1_*'] = 0
would use a default of0
for every undefined variable that starts withk1_
. For more information please refer to the documentation of thedipas.madx.parser
module.Aperture checks - Aperture checks on Drift spaces will be performed at the entrance of the drift space (as opposed to MADX). In case intermediary aperture checks for long drift spaces are desired, appropriate markers can be placed in-between. The
maxaper
attribute of theRUN
command is ignored. Only explicitly defined apertures of the elements are considered.Random number generation - All the random functions from MADX are supported however the underlying random number generator (RNG) is (potentially) different. For that reason, even if the same seed for the RNG is used, the values generated by MADX and by DiPAS will likely differ. For that reason is it important, when comparing results obtained with DiPAS and MADX, to always generate a new MADX script from the particular DiPAS lattice to ensure the same numerical values from random functions. If the original MADX script (from which the DiPAS lattice was parsed) is used, then these values might differ and hence the results are not comparable. For error definitions the user can load and assign the specific errors which were generated by MADX (see build.assign_errors).
Single-argument commands - Commands that have a single argument without specifying an argument name, such as
SHOW
orEXEC
, are interpreted to indicate a (single) flag, analogue toOPTION
. For example usingOPTION
MADX considers the following usages equivalent:OPTION, warn;
andOPTION, warn = true;
(i.e.warn
being a positive flag). The DiPAS parser treats other commands in a similar manner, for exampleSHOW, q1;
will be converted toSHOW, q1 = true;
. The same holds also forVALUE
but expressions here need to be unquoted, otherwise this will result in a parsing error. That means when inspecting the resulting command list these are still useful with the subtlety that the single-arguments are stored as argument names together with the argument value"true"
.
Unsupported statement types
Program flow constructs such as
if / else
orwhile
.Macro definitions.
Commands that take a single quoted string as argument without specifying an argument name such as
TITLE
orSYSTEM
.Template beamlines defined via
label(arg): LINE = (arg);
(“normal” beamline definitions (withoutarg
) can be used though).