next up previous
Next: SEXT Up: Element Dictionary Previous: SCRAPER

SCRIPT

An element that allows transforming the beam using an external script.
Parallel capable? : yes
Parameter Name Units Type Default Description
L $M$ double 0.0 Length to be used for matrix-based operations such as twiss parameter computation.
COMMAND   STRING NULL 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   long 1 Use C-shell for execution (may be slower)?
VERBOSITY   long 0 Set the verbosity level.
START_PASS   long -1 Start script action on this pass. Before that, behaves like a drift space.
ON_PASS   long -1 Perform script action only on this pass. Other than that, behaveslike a drift space.
DIRECTORY   STRING NULL Directory in which to place input and output files. If blank, the present working directory is used.
ROOTNAME   STRING NULL Rootname for use in naming input and output files. %s may be used to represent the run rootname.
INPUT_EXTENSION   STRING in Extension for the script input file.
OUTPUT_EXTENSION   STRING out Extension for the script output file.
KEEP_FILES   long 0 If nonzero, then script input and output files are not deleted after use. By default, they are deleted.
DRIFT_MATRIX   long 0 If nonzero, then for matrix calculations the element is treated as a drift space.

An element that allows transforming the beam using an external script.
Parameter Name Units Type Default Description
USE_PARTICLE_ID   long 1 If nonzero, then the output file should use the original particle ID.
NO_NEW_PARTICLES   long 1 If nonzero, then no new particles will be added in the script output file.
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
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

An element that allows transforming the beam using an external script.
Parameter Name Units Type Default Description
SP0   STRING NULL User-defined string parameter for command substitution for sequence %sp0
SP1   STRING NULL User-defined string parameter for command substitution for sequence %sp1
SP2   STRING NULL User-defined string parameter for command substitution for sequence %sp2
SP3   STRING NULL User-defined string parameter for command substitution for sequence %sp3
SP4   STRING NULL User-defined string parameter for command substitution for sequence %sp4
SP5   STRING NULL User-defined string parameter for command substitution for sequence %sp5
SP6   STRING NULL User-defined string parameter for command substitution for sequence %sp6
SP7   STRING NULL User-defined string parameter for command substitution for sequence %sp7
SP8   STRING NULL User-defined string parameter for command substitution for sequence %sp8
SP9   STRING NULL 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. %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.
  4. %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.

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


next up previous
Next: SEXT Up: Element Dictionary Previous: SCRAPER
Robert Soliday 2014-03-21