NAME

slaw - convert SPHERES raw data to scattering laws S(q,w) or I(q)

SYNOPSIS

slaw [-s] [-v|-d level] [-b] [-i | -f file | -e "commands"]

DESCRIPTION

Slaw converts raw data from the neutron backscattering spectrometer SPHERES of JCNS at MLZ Garching into a scattering laws S(q,w) or I(q).

Output can be written to a variety of formats. Besides conventional spectra S(q,w), Slaw also supports elastic scan data I(q,T) or I(q,t) and four-dimensional data sets S(q,w,T) or S(q,w,t) obtained in inelastic temperature scans or kinetic measurements.

Slaw processes data through the following steps:

OPTIONS

Slaw can be invoked in four different ways:

In the above commands, options may include any of the following:

COMMAND SCRIPT

Syntax.

Commands are separated by line breaks, except in -e mode where ";" serves as command separator.

Comments start with "#" and extend to the end of line.

There are three types of commands: control command, global parameter setting, production.

At present, the only control command is

A global parameter setting sets the default value of a parameter. Examples:

A production reads a raw data set, performs conversions, corrections and calibrations, and almost always writes the so obtained scattering law to an output file. Optionally instrument parameters can be determined and stored in registers for use in the following productions.

A production command consists of a raw data list, which must always come first, optionally followed by embedded parameter commands and register commands in arbitrary order, separated by blanks. Embedded parameter commands overwrite global settings for the duration of the current production. Register commands are intrinsically global or local.

Example for a production:

Raw Data Specification.

Raw data file names have the form path/subscan. The path is controlled by the parameters 'ip' and 'ie'. The susbscan identifier is assumed to start with a digit; it must not contain ",", "-", or "!".

Every production command starts with a subscan list. A subscan list is a comma-separated list of subscan ranges subscan[-subscan].

At SPHERES, the local file organization allows for more expressive raw data specifications. For instance, raw data files 12u0-12u7 make up scan 12. Within this scan, subscan ranges are specified as follows:

To avoid mistakes, single-subscan ranges must be followed by an exclamation mark.

Parameters.

Parameters may have boolean, integer, floating-point or string values. In the following, boolean parameters are marked by the suffix "+-".

Boolean parameters are switched on or off by the commands

parameter+, parameter-.

All other parameters are set by the command

parameter value.

Input specification parameters:

ii | initialize_instrument

Obligatory parameter value: SPHERES. Can be omitted in slaw>=1.2.

ip | input_path

Common part of the raw data file name. This maybe just a directory path (in this case, it should terminate with a slash), but it may also include the common part of a run number. Default: ./ (current working directory).

iT | input_temperature

If input files contain several temperature readings, this parameter indicates which one shall be used. Allowed values at SPHERES: Tsam, Tset, none; for legacy data (up to S85) T0 and T1. Default: Tsam.

T | temperature

Sample temperature (in K). Overwrites the temperature record in the raw data file. Used when that record is missing or incorrect.

Output specification parameters:

o+- | output+-

Save processed scattering law in an output file ? Default = yes.

oo+- | output_overwrite+-

Overwrite existing output files ? Default = yes.

op | output_path

Absolute or relative path to the output directory. Default: current working directory.

of | output_file

Name of the output file, relative to the path set by op. If missing, a file name is generated automatically, based on raw data file names [IMPLEMENTED ?]. Special value "STDOUT": write to stdout.

ot | output_format

Allowed values: see section "supported output formats" below. Using a comma-separated list, it is possible to specify more than one format.

ou | output_unit

Set the energy/frequency scale to <unit>, and the scattering law scale to <unit>^-1. Allowed values: ueV.

oe+- | output_errors+-

Output standard errors along with S(q,w) ? Default = yes.

oq0+- | output_q0+-

Output elastic scattering wave number q0 instead of scattering angle 2th. Default = no.

t+- | time_scan+-

Treat data set as a time scan ? Default = no.

In time-scan mode, the output file will contain a sequence of scattering laws. Otherwise, in regular-scan mode, all input scans will be summed to yield just one output scattering law.

tp | time_parameter[,time_parameter]

Requested in time-scan mode to characterize the single scans within a time scan. Allowed values: T (temperature), t (time), Mon (monitor flux).

e+- | elastic_scan+-

These data are from an elastic scan. Default = no.

Data processing parametes:

dd | delete_detectors

Parameter value must be a comma-separated list of detectors that shall be deleted. This deletion is carried out before the one governed by register D. Immediately after the deletion, the remaining detectors are renumbered starting with 0.

bc | bin_channels

Bin energy channels. Parameter value must be an integer, indicating how many input channels will be binned into one output channel. Default: switched off (bc-, equivalent to bc 1).

bd | bin_detectors

Parameter value must be a comma-separated list of the detectors that start a bin. Example: "0,3,8" forms groups 0-2, 3-7, 8-end. Immediately after execution, the binned detectors are renumbered starting with 0. Default: switched off (bd-).

bt | bin_times

For elastic scans, or spectral time-scans. Parameter value must be an integer, indicating how many raw time intervals will be binned into one. Default: switched off (bt-, equivalent to bt 1).

mon+-

Normalize to monitor ? Default: yes.

wnor

Half width of the normalization interval: The "vanadium" normalization is done by integration from w0-wnor to w0+wnor, where w0 is the frequency/energy of elastically scattered neutrons. Units as set by ou. Required when register N is in use.

wmin
wmax

These two parameters can be used to restrict the frequency/energy range of the output spectra. Units as set by ou.

noise

Constant noise in cnts/sec. Default: 0. To be subtracted prior to any energy-dependent normalisation. MAY BE MODIFIED OR REMOVED IN THE NEAR FUTURE. Should be replaced by a background register, since noise is detector dependent.

Registers.

Register commands control background subtraction and intensity normalization:

Commands (where R may be one or several of C, N):

>>R

For use in a production. Use current data to set R. Starting with the present production, use R for data processing.

R-

Do not apply R in the current production (automatically for C).

SUPPORTED OUTPUT FORMATS

y08

YAML-based format for Frida2.

i96

Verbous format for Frida1.

inx

Traditional ILL format. For use with LAMP.

recttab

A simple rectangular table. One line per energy channel. First column contains the energy. Columns 2n, 2n+1 contain S(q,w) and standard error for detector n.

spectab

A sequence of tables. One table per detector. For each table, a header line contains the detector angle (or q). The remainder of the table is rectangular; one line per energy channel; the three columns contain energy, S(q,w), standard error.

datreat

For Michael Monkenbusch's data analysis program datreat.

FILES

Executables:

dest/

Installation destination. Typically /usr/local/.

dest/bin/slaw

Ruby script, containing the command compiler (the high-level part of slaw).

dest/share/slaw/ruby/

Directory containing submodules needed by slaw.

dest/bin/sqw-<instr>

Low-level data processing program for individual instruments.

dest/bin/spheres_check_incremental

Needed by slaw.rb to check whether SPHERES data have been saved in incremental mode or not.

Input and output files (all in present working directory):

Slawfile

Default input command script.

ERRORS

On error, slaw prints a message to stderr and terminates. If an internal consistency check failed, the error message starts with the word "BUG". Please send a report to the program's author. In all other cases the error is likely due to invalid input.

RESOURCES

Persistent web link: http://apps.jcns.fz-juelich.de/slaw

Download location: http://apps.jcns.fz-juelich.de/src/slaw

Development snapshot: git://apps.jcns.fz-juelich.de/slaw.git/

Note that slaw requires the script language Ruby (http://www.ruby.org) to be installed.

AUTHOR

Program and documentation written by Joachim Wuttke <j.wuttke@fz-juelich.de>.

HISTORY

Development of Slaw started in 2008 while the author was instrument responsible of SPHERES. The aims were:

The current version of Slaw has been implemented in 2010. It is now maintained as part of the mission of the Scientific Computing Group of JCNS-MLZ.

COPYING

Copyright 2008-18 by Joachim Wuttke, Forschungszentrum Juelich GmbH.

Free use of this software is granted under the terms of the GNU General Public License (GPL).