10.101 SCRIPT—An element that allows transforming the beam using an external script.

An element that allows transforming the beam using an external script.
Parallel capable? : yes
GPU capable? : no
Back-tracking capable? : yes

An element that allows transforming the beam using an external script.

An element that allows transforming the beam using an external script.

An element that allows transforming the beam using an external script.

This element allows expanding elegant by using external scripts (or programs) as elements in a beamline. Here are requirements for the script:

• It must be executable from the commandline.
• It must read the initial particle distribution from an SDDS file. This file will have the usual columns that an elegant phase-space output file has, along with the parameter Charge giving the beam charge in Coulombs. The file will contain a single data page.
• It must write the final particle distribution to an SDDS file. This file should have all of the columns and parameters that appear in the initial distribution file. Additional columns and parameters will be ignored, as will all pages but the first.
• The Charge parameter in the file is used to determine the total beam charge; the script must ensure that this parameter is set correctly; when particles are lost or created, simply copying or retaining the value from the input file will not be correct. Normally, the charge per particle is constant in simulations. Hence, if elegant sees a change in charge per particle after the SCRIPT element, it issues a warning.

The SCRIPT element works best if the script accepts commandline arguments. In this case, the COMMAND parameter is used to provide a template for creating a command to run the script. The COMMAND string may contain the following substitutable fields:

1. %i — Will be replaced by the name of the input file to the script. (elegant writes the initial particle distribution to this file.)
2. %o — Will be replaced by the name of the output file from the script. (elegant expects the script to write the final particle distribution to this file.)
3. %p — Will be replaced by the pass number, which starts from 0.
4. %c — Will be replaced by the occurrence number of the element, which starts from 1.
5. %b — Will be replaced by 0 (1) for forward (backward) tracking.
6. %np0, %np1, ..., %np9 — Will be replaced by the value of Numerical Parameter 0, 1, ..., 9. This can be used to pass to the script values that are parameters of the element definition. For example, if one wanted to vary parameters or add errors to the parameter, one would use this facility.
7. %sp0, %sp1, ..., %sp9 — Will be replaced by the value of String Parameter 0, 1, ..., 9. This can be used to pass to the script values that are parameters of the element definition.

In some cases, one may wish to keep the input file delivered to the SCRIPT as well as the output file returned by it. This is facilitated by using the ROOTNAME parameter, which allows specifying the rootname for these files, as well as the INPUT_EXTENSION and OUTPUT_EXTENSION parameters. The ROOTNAME parameter may contain a simple string, but may also contain several substitutible fields:

• %s — The global rootname, which may be given by the rootname parameter in the run_setup command.
• %p — The pass index.
• %ld — The occurence number of the element.

Here’s an example of a SCRIPT COMMAND:

In this example, the script myScript takes four commandline arguments, giving the names of the input and output files, an accuracy requirement, and a type specifier. By default, elegant will choose unique, temporary filenames to use in communicating with the script. The actual command when executed might be something like

where for this example I’ve assumed NP0=1.5e-6 and SP0=’’scraper’’.

If you have a program (e.g., a FORTRAN program) that does not accept commandline arguments, you can easily wrap it in a Tcl/Tk simple script to handle this. Alternatively, you can force elegant to use specified files for communicating with such a script. This is done using the ROOTNAME, INPUT_EXTENSION, and OUTPUT_EXTENSION parameters. So if your program was crass and it expected its input (output) in files crass.in (crass.out), then you’d use

For purposes of computing concatenated transport matrices, Twiss parameters, response matrices, etc., elegant will perform initial tracking through the SCRIPT element using an ensemble of 25 particles. If this is not desirable, then set the parameter DRIFT_MATRIX to a non-zero value. This will force elegant to treat the element as a drift space for any calculations that involve transport matrices. Examples of where one might want to use this feature would be a SCRIPT that involves randomization (e.g., scattering), particle loss, or particle creation.

If non-zero, the RPN_PARAMETERS parameter directs elegant to load all numerical SDDS parameter values from the script output file into rpn variables, where they may be used for optimization. This provides the user the ability to perform script-based analysis of particle distributions and then optimize the results of that analysis. (Typically in this case the script does not actually transform the particle coordinates, but simply copies them from the input file to the output file.) The names of the variables are of the form ElementName#N.ParameterName, where N is the occurrence number of the script element (usually 1 if there is only one instance).