MAD to Bmad Lattice File Conversion ----------------------------------- This README file documents how to convert MAD8 or MAD-X formatted files to Bmad lattice format. The MAD8 to Bmad conversion will also handle XSIF format to Bmad conversion. Note: For converting from Bmad format to MAD8 or MADX format, use the program bmad_to_mad_or_sad. For details, see the Bmad manual in the chapter on "MAD/SAD/PTC Lattice Conversion". --------------------------------------------------------------------------------------------------- Orientation: ------------ This README file is contained in the directory: /util_programs/mad_to_bmad/ Where is the directory of the Distribution or Release that you are using (See the online Bmad documentation or your local Bmad Guru for more details on Distributions and Releases). There are two python scrips in this directory to convert lattice files: mad8_to_bmad.py -- Converts from MAD8 to Bmad format. madx_to_bmad.py -- Converts from MADX to Bmad format. There is also a third script to convert a MAD error data file: errors_mad_to_bmad.py -- Converts from MAD error data file format to Bmad format --------------------------------------------------------------------------------------------------- Limitations: ------------ Bmad, unlike MAD, does not have any ``action'' commands. An action command is a command that makes a calculation. Examples include MAD's \vn{SURVEY} and \vn{TWISS} commands. Action commands are ignored by the conversion scripts. If an action command modifies lattice parameters, the Bmad lattice will not reflect this. For this reason, If the MAD lattice depends upon execution of any action commands, or if there is any difficulty in translation, create a sequence file as discussed below and translate the sequence file. In Bmad, all variables must be defined before being used (\sref{s:arith}) while MAD will simply take a variable's value to be zero if it is not defined. Problems of this sort will be caught when a Bmad based program reads in a lattice file. Warnings will be issued and can be resolved by modifying the Bmad lattice file to include definitions for the missing variables. Bmad, unlike MAD, does not allow variable values to be redefined. The conversion scripts will catch this error. Both definitions of a variable will be put in the output file and it is up to the User to modify the output file appropriately. If not resolved, the error will be caught when a Bmad based program reads in a lattice file. --------------------------------------------------------------------------------------------------- MAD "Sequence" File: -------------------- As an alternative to translating the MAD file directly, a simplified MAD lattice file (a "sequence" file) can be constructed by inserting a save statement at the end of the MAD file and then running MAD to create the new sequence file. Use this file if you have any problems translating your original MAD file. MAD8 example save statement: save, file = "my_lattice.mad8, beam" MADX example save statement: save, file = "my_lattice.madx", sequence = "some_sequence", beam; Note: The sequence file does not have any "use" statements so a "use" statement must be inserted in the bmad lattice file. --------------------------------------------------------------------------------------------------- How to Convert a Lattice: ------------------------- Minimum python version needed is 3.6. The scripts run independently of whether the standard Bmad environmental variables have been setup. To convert MAD8 files, use the command: python /mad8_to_bmad.py {options} To convert MADX files, use the command: python /madx_to_bmad.py {options} where is the path to the directory where the script is. Example conversion command: python $ACC_ROOT_DIR/util_programs/mad_to_bmad/madx_to_bmad -f lhc.madx This example converts a MADX file called "lhc.madx". [Note: If you are setup to run Bmad based programs, the ACC_ROOT_DIR environmental variable will be set to the directory.] The Bmad output file name is the input file name with the ".mad", ".mad8", ".madx", or ".seq" suffix removed (if it exists) and with a ".bmad" suffix appended. The optional arguments are: -h, --help Show a help message and exit -d, --debug Print debug info while running (not of general interest). -f, --many_files Create a Bmad file for each MAD8 input file. -s, --superimpose Superimpose elements in a sequence (madx only). -v, --no_prepend_vars Do not move variables to the beginning of the Bmad file. If the --debug (or -d) option is present, the script will print information on the parsing process to the terminal. This option is only of interest for someone debugging the code. By default, only one Bmad output file is produced even when the MAD input is split among multiple files that call each other. If The --many_files (or -f) option is present, the script will produce multiple Bmad output files, one for each MAD input file. For the MADX conversion, the original scheme for converting sequences was to create a drift whose length was the length of the sequence and then to superimpose the individual lattice elements on top of this. The parsing of the generated Bmad lattice file turned out to be slow for very large lattices due to the amount of shuffling of lattice elements superposition entailed (essentially, the parsing scaled as N^2 where N is the number of lattice elements). To avoid this, the current translation scheme converts sequences into lines without any superposition. If the --superimpose (or -s) option is present. The original superposition algorithm is used. In a MAD lattice file, it is permissible to define a variable after it has been used in an expression. For example: q: quadrupole, k1 = 4*a_var a_var = 0.03 Bmad does not allow this. To get around this, the conversion scripts move variable definitions to the top of the output file. If, for some reason, you do not want this (say you know that the variable ordering is OK and you want the layout of the output file to reflect the layout of the input file), the --no_prepend_vars (or -v) option will prevent variable definitions from being moved. Note: The definition of a variable whose value involves an expression that references an element parameter will not be moved. Note: If variable definitions are moved to the top of the output file, the conversion scripts will arrange the relative order of the variable definitions so that variables whose values depend upon other variables will appear after the other variables have been defined as required by Bmad. Additionally, if there are multiple definitions of the same variable, all but the last one will be commented out. Note: If a line in the MAD8 or MADX file begins with the string "!!verbatim", everything after "!!verbatim" on the line will be put in the Bmad file. This is useful for transferring extra information to the Bmad file without affecting the reading of the MAD file by MAD. Example: !!verbatim parameter[geometry] = open will appear in the Bmad file as: parameter[geometry] = open --------------------------------------------------------------------------------------------------- Converting a MAD Error Data File: --------------------------------- If a MAD lattice has been defined with errors, a corresponding Bmad lattice file with these errors can be created with the following procedure: 1) Create a Bmad lattice file without errors. 2) Create a MAD error data file by putting the following in the MAD lattice file and then running MAD: select, flag=error, full; esave, file = "err"; This will create an error file called "err" 2) Create the corresponding Bmad lattice file by running errors_mad_to_bmad: errors_mad_to_bmad err where is the name of the bmad lattice file. This will create a file named err.bmad. 3) To use this file with the main lattice file, create a third file that calls the main lattice file and the error file. Example: call, file = ags.bmad ! Main lattice file use, ring ! May not be needed if main lattice file has a use statement expand_lattice ! Will be needed if err.bmad uses "##" construct. call, file = err.bmad ! Error file Note: The Bmad file uses the "##" construct so that differing errors can be assigned to elements with the same name. As a consequence, an expand_lattice command is needed if there are multiple misaligned elements with the same name. This means that any "use" statements must come before calling the error file. --------------------------------------------------------------------------------------------------- Notes: ------ By default, Bmad will treat a lattice without \vn{lcavity} elements as having a closed geometry and a lattice with an \vn{lcavity} as having an open geometry. To override the default, put the following in the Bmad file (or use the "!!verbatim" construct discussed above): parameter[geometry] = open ! or closed For a lattice with an open geometry, the initial Twiss parameters (and optionally the initial orbit) needs to be specified. The syntax for this are statements like: beginning[beta_a] = 12.34 ... etc... See the Bmad manual for more details. Help: ----- If you find a problem with the conversion, please send a message along with the original MAD files to a Bmad maintainer. Contact info can be obtained on the Bmad site by clicking on the "Help & Mailing Lists" button. Tips: ----- * If you have a lattice with a closed geometry, and the Bmad computed orbit or Twiss parameters are different enough from the MAD ones where you suspect a conversion problem, one way to try to diagnose things is to track in MAD and Bmad as if the lattice had an open geometry to see if there are any particular spots in the lattice where differences suddenly become much larger. If you can spot such places, you can examine the lattice element at that location. * To track using an open geometry in Bmad, see the Notes section above. To track using an open geometry in MAD, define starting orbit and Twiss parameters in the appropriate twiss statement. * If there are no spots where there is a jump in the differences, that is, the differences grow somewhat uniformly, it is probable that the differences are due to differing tracking algorithms between Bmad and MAD. For example, Bmad scales the strength of a magnet by a particle's energy. So tracking a particle in Bmad whose energy is very different from the reference energy is not a problem. When tracking in MAD using second order maps, however, the accuracy of the maps will be degraded for particles whose energy is far from the reference energy. * Another diagnosis tool is to back translate the Bmad lattice to MAD. The resulting lattice can then be compared to the original lattice.