SCRIPT

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

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

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

Parameter Name	Units	Type	Default	Description
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		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

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

Parameter Name	Units	Type	Default	Description
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

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 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''