The purpose of the instrument definition file is to specify a sequence of components, along with their position and parameters, which together make up a beamline. Each component is given its own local coordinate system, the position and orientation of which may be specified by its translation and rotation relative to another component. Examples of instrument definitions can be found in the example directory of your McXtrace installation. Further examples may be found as they are built on the McXtrace web-page [Mcx].
As a summary, the usual grammar for instrument descriptions is
DEFINE INSTRUMENT name(parameters)
DECLARE C_code
INITIALIZE C_code {NEXUS}
TRACE components
{FINALLY C_code}
END
DEFINE INSTRUMENT name \((a_1, a_2, \ldots )\)
This marks the beginning of the definition. It also gives the name of the instrument and the list of instrument parameters. Instrument parameters describe the configuration of the instrument, and usually correspond to setting parameters of the components, see section 6.5. A motor position is a typical example of an instrument parameter. The input parameters of the instrument constitute the input that the user (or possibly a front-end program) must supply when the generated simulation is started.
By default, the parameters will be floating point numbers, and will have the C type double (double precision floating point). The type of each parameter may optionally be declared to be int for the C integer type or char * for the C string type. The name string may be used as a synonym for char *, and floating point parameters may be explicitly declared using the name double. The following example illustrates all possibilities:
DEFINE INSTRUMENT test(d1, double d2, int i, char *s1, string s2)
Here d1 and d2 will be floating point parameters of C type double, i will be an integer parameter of C type int, and s1 and s2 will be string parameters of C type char *. The parameters of an instrument may be given default values. Parameters with default values are called optional parameters, and need not be given an explicit value when the instrument simulation is executed. When executed without any parameter value in the command line (see section 5.3), the instrument asks for all parameter values, but pressing the Return key selects the default value (if any). When used with at least one parameter value in the command line, all non specified parameters will have their value set to the default one (if any). A parameter is given a default value using the syntax “param= value”. For example
DEFINE INSTRUMENT test(d1= 1, string s2="hello")
Here d1 and d2 are optional parameters and if no value are given explicitly, “1” and “hello” will be used.
Optional parameters can greatly increase the convenience for users of instruments for which some parameters are seldom changed or of unclear significance to the user. Also, if all instrument parameters have default values, then the simple command mxdisplay test.instr will show the instrument view without requesting any other input, which is usually a good starting point to study the instrument design.
DECLARE
%{
…C declarations of global variables etc. …
%}
This gives C declarations that may be referred to in the rest of the instrument definition. A typical use is to declare global variables or small functions that are used elsewhere in the instrument. The %include ’’file’’ keyword may be used to import a specific component definition or a part of an instrument. Variables defined here are global, and may conflict with internal McXtrace variables, particularly symbols like x,y,z,Ex,Ey,Ez,kx,ky,kz,t,phi and generally all names starting with mc nad mx should be avoided. If you can not compile the instrument, this may be the reason. The DECLARE section is optional.
INITIALIZE
%{
…C initializations. …
%}
This section contains code that is executed once when the simulation starts. This section is optional. Instrument setting parameters may be modified in this section (e.g. doing tests or automatic settings).
To use the NeXus format [Nex] the simulation must be linked with additional libraries (HDF and NeXus) which must have been pre-installed. Preferrably, McXtrace should have been installed with the ./configure --with-nexus on Unix/Linux systems. To activate the NeXus output, the instrument must be compiled with the flags -DUSE_NEXUS -lNeXus.
The default NeXus format is NeXus 5 with compression. However, that format may be changed with the optional keyword NEXUS to follow the INITIALIZE section, namely:
INITIALIZE
%{
…C initializations. …
%} NEXUS {"4"|"5"|"XML"|"compress"|"zip"}
It is possible to set the type of NeXus file with a string argument, containing words ”4”, ”5” or ”XML”. Optionally, if the string also contains the compress or zip word, the NeXus file will use compression for Data Sets. We recommend the syntax NEXUS "5 compress" which is the default.
You may choose the name of the output file with the -f filename option from the instrument executable or mxrun (see Sections 5.3, 5.4.2 and Table ??).
Then, the output format is chosen as usual with the --format=NeXus option when launching the simulation. All output files are stored in the output filename, as well as the instrument description itself. Other formats are still available. When run on a distributed system (e.g. MPI), detectors are gathered, but list of events (see e.g. component Virtual_output) are stored as one data set per node.
As a summary, the usual grammar for component instances within the instrument TRACE section is
COMPONENT name = comp(parameters)
AT (...) [RELATIVE [reference|PREVIOUS] | ABSOLUTE]
{ROTATED {RELATIVE [reference|PREVIOUS] | ABSOLUTE} }
The TRACE keyword starts a section giving the list of components that constitute the instrument. Components are declared like this:
COMPONENT \(\textit {name} = \textit {comp}(p_1 = e_1, p_2 = e_2, \ldots )\)
This declares a component named name that is an instance of the component definition named comp. The parameter list gives the setting and definition parameters for the component. The expressions \(e_1, e_2, \ldots \) define the values of the parameters. For setting parameters arbitrary ANSI-C expressions may be used, while for definition parameters only constant numbers, strings, names of instrument parameters, or names of C identifiers are allowed (see section 6.5.1 for details of the difference between definition and setting parameters). To assign the value of a general expression to a definition parameter, it is necessary to declare a variable in the DECLARE section, assign the value to the variable in the INITIALIZE section, and use the variable as the value for the parameter.
The McXtrace program takes care to rename parameters appropriately in the output so that no conflicts occur between different component definitions or between component and instrument definitions. It is thus possible (and common) to use a component definition multiple times in an instrument description.
Be aware of the C variable type conversions when setting numerical parameter values, as in p1=12/1000. In this example, the parameter p1 will be set to 0 as the division of the two integers is indeed 0. To avoid that, use explicitely floating type numbers as in p1=12.0/1000.
The McXtrace compiler will automatically search for a file containing a definition of the component if it has not been declared previously. The definition is searched for in a file called “name.comp”. See section 5.2.2 for details on which directories are searched. This facility is often used to refer to existing component definitions in standard component libraries. It is also possible to write component definitions in the main file before the instrument definitions, or to explicitly read definitions from other files using %include (not within embedded C blocks).
The physical position of a component is specified using an AT modifier following the component declaration:
AT \((x,y,z)\) RELATIVE name
This places the component at position \((x,y,z)\) in the coordinate system of the previously declared component name. Placement may also be absolute (not relative to any component) by writing
AT \((x,y,z)\) ABSOLUTE
Any C expression may be used for \(x\), \(y\), and \(z\). The AT modifier is required. Rotation is achieved similarly by writing
ROTATED \((\phi _x,\phi _y,\phi _z)\) RELATIVE name
This will result in a coordinate system that is rotated first the angle \(\phi _x\) (in degrees) around the \(x\) axis, then \(\phi _y\) around the \(y\) axis, and finally \(\phi _z\) around the \(z\) axis. Rotation may also be specified using ABSOLUTE rather than RELATIVE. If no rotation is specified, the default is \((0,0,0)\) using the same relative or absolute specification used in the AT modifier. We recommend to apply all rotations of an instrument description on Arm class components only, acting as goniometers, and position the optics on top of these. This usually makes it much easier to orient pieces of the beamline, and avoid positioning errors.
The position of a component is actually the origin of its local coordinate system. Usually, this is used as the input window position (e.g. for guide-like components), or the center position for cylindrical/spherical components.
The PREVIOUS keyword is a generic name to refer to the previous component in the simulation. Moreover, the PREVIOUS(n) keyword will refer to the \(n\)-th previous component, starting from the current component, so that PREVIOUS is equivalent to PREVIOUS(1). This keyword should be used after the RELATIVE keyword, but not for the first component instance of the instrument description.
AT \((x,y,z)\) RELATIVE PREVIOUS ROTATED \((\phi _x,\phi _y,\phi _z)\) RELATIVE PREVIOUS(2)
Invalid PREVIOUS references will be assumed to be absolute placement.
The order and position of components in the TRACE section does not allow components to overlap, except for particular cases (see the GROUP keyword below). Indeed, many components of the McXtrace library start by propagating the x-ray event to the begining of the component itself. If the corresponding propagation length is found to be negative (i.e. the x-ray is already after or aside the component, and has thus passed the ’active’ position), the x-ray event is ABSORBed, resulting in a zero intensity and event counts after a given position. The number of such removed x-rays is indicated at the end of the simulation. Getting such warning messages may be an indication that either some components overlap, or some x-rays are getting outside of the simulation, for instance this usually happens after a monochromator, as the non-reflected beam is indeed lost. A special warning appears when no x-ray has reached some part of the simulation. This is usually the sign of either overlapping components or a very low intensity.
For experienced users, we recommend as well the usage of the WHEN and EXTEND keywords, as well as other syntax extensions presented in section 6.4.2 below.
SAVE
%{
…C code to execute each time a temporary save is required …
%}
This gives code that will be executed when the simulation is requested to save data, for instance when receiving a USR2 signal (on Unix systems), or using the Progress_bar component with intermediate savings. It is also executed when the simulation ends. This section is optional.
FINALLY
%{
…C code to execute at end of simulation …
%}
This gives code that will be executed when the simulation has ended. When existing, the SAVE section is first executed. The FINALLY section is optional. A simulation may be requested to end before all x-rays have been traced when recieving a TERM or INT signal (on Unix systems), or with Control-C, causing code in FINALLY to be evaluated.
The end of the instrument definition must be explicitly marked using the keyword
END