10.96 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






Parameter Name UnitsType Default

Description






L M double 0.0

Length to be used for matrix-based operations such as twiss parameter computation.






COMMAND STRINGNULL

SDDS-compliant command to apply to the beam. Use the sequence %i to represent the input filename and %o to represent the output filename.






USE_CSH short 1

Use C-shell for execution (may be slower)?






VERBOSITY short 0

Set the verbosity level.






RPN_PARAMETERS short 0

If nonzero, then parameters from the script output file are loaded into RPN variables.






START_PASS long -1

Start script action on this pass. Before that, behaves like a drift space.






END_PASS long -1

End script action after this pass. Before that, behaves like a drift space.






PASS_INTERVAL long -1

Execute script only every Nth pass following START_PASS, including START_PASS. Otherwise, behaves like a drift space.






ON_PASS long -1

Perform script action only on this pass, overriding other pass controls. Other than that, behaves like a drift space.






DIRECTORY STRINGNULL

Directory in which to place input and output files. If blank, the present working directory is used.






ROOTNAME STRINGNULL

Rootname for use in naming input and output files. %s may be used to represent the run rootname.






SCRIPT continued

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






Parameter Name UnitsType Default

Description






INPUT_EXTENSION STRINGin

Extension for the script input file.






OUTPUT_EXTENSION STRINGout

Extension for the script output file.






KEEP_FILES short 0

If nonzero, then script input and output files are not deleted after use. By default, they are deleted.






DRIFT_MATRIX short 0

If nonzero, then for non-tracking calculations the element is treated as a drift space.






USE_PARTICLE_ID short 1

If nonzero, then the output file will supply particle IDs. Otherwise, particles are renumbered.






NO_NEW_PARTICLES short 1

If nonzero, then no new particles will be added in the script output file.






DETERMINE_LOSSES_FROM_PID short 1

If nonzero and if USE_PARTICLE_ID is nonzero, then particleID data from script output is used to determine which particles were lost.






SOFT_FAILURE short 1

If output file does not exist or can’t be read, consider all particles lost.






NP0 double 0.0

User-defined numerical parameter for command substitution for sequence %np0






NP1 double 0.0

User-defined numerical parameter for command substitution for sequence %np1






NP2 double 0.0

User-defined numerical parameter for command substitution for sequence %np2






SCRIPT continued

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






Parameter NameUnitsType Default

Description






NP3 double 0.0

User-defined numerical parameter for command substitution for sequence %np3






NP4 double 0.0

User-defined numerical parameter for command substitution for sequence %np4






NP5 double 0.0

User-defined numerical parameter for command substitution for sequence %np5






NP6 double 0.0

User-defined numerical parameter for command substitution for sequence %np6






NP7 double 0.0

User-defined numerical parameter for command substitution for sequence %np7






NP8 double 0.0

User-defined numerical parameter for command substitution for sequence %np8






NP9 double 0.0

User-defined numerical parameter for command substitution for sequence %np9






SP0 STRINGNULL

User-defined string parameter for command substitution for sequence %sp0






SP1 STRINGNULL

User-defined string parameter for command substitution for sequence %sp1






SP2 STRINGNULL

User-defined string parameter for command substitution for sequence %sp2






SP3 STRINGNULL

User-defined string parameter for command substitution for sequence %sp3






SP4 STRINGNULL

User-defined string parameter for command substitution for sequence %sp4






SCRIPT continued

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






Parameter NameUnitsType Default

Description






SP5 STRINGNULL

User-defined string parameter for command substitution for sequence %sp5






SP6 STRINGNULL

User-defined string parameter for command substitution for sequence %sp6






SP7 STRINGNULL

User-defined string parameter for command substitution for sequence %sp7






SP8 STRINGNULL

User-defined string parameter for command substitution for sequence %sp8






SP9 STRINGNULL

User-defined string parameter for command substitution for sequence %sp9






GROUP string NULL

Optionally used to assign an element to a group, with a user-defined name. Group names will appear in the parameter output file in the column ElementGroup






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

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:

Here’s an example of a SCRIPT COMMAND:

myScript -input %i -output %o -accuracy %np0 -type %sp0

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

myScript -input tmp391929.1 -output tmp391929.2 -accuracy 1.5e-6 -type scraper

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

S1: script,command=’’crass’’,rootname=’’crass’’,input_extension=’’in’’,&  
output_extension=’’out’’

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).

SEXT