Part A - User Manual

GENIE is the name of a programs used for the display and analysis of data from the neutron scattering instruments at the ISIS facility. For several years now, a stable VAX/VMS version of the software (GENIE-V2) has been in use at ISIS (Rutherford Appleton Laboratory, Oxfordshire, UK), and at several scientific and commercial establishments world-wide. Constant improvements in the capabilities of the neutron scattering instruments at ISIS, and in the hardware and software available for data analysis, has necessitated a re-write of GENIE. The new GENIE is known as Open GENIE to reflect the intention that the software be used on a wide variety of different computers and operating systems. It is aimed at supplying scientists with an inexpensive computer package which provides them with access to their experimental data, so that they may analyse the data as required and display the results in a useful format, usually in a graphical form.

Getting Started

If you are new to Open GENIE, we recommend that you work through "The Three Wishes" section of the User manual. This should give you a clear idea of what facilities Open GENIE provides and how to use them. After this working through one or two of the examples programs should provide sufficient knowledge to enable you to work with Open GENIE. For the more experienced GENIE user, a brief read of the User manual is recommended to determine the differences between older versions of GENIE, and the new revised Open GENIE.

Starting Open GENIE

Remote operation of Open GENIE at ISIS

Via Telnet
Firstly telnet into one of the main VMS server machines ptath, horus, or thoth using

>telnet ptath.nd.rl.ac.uk

If you want to use the graphics you will need to set the X display back to your local machine

$set display/create/tran=tcpip/node=your.own.machines.ip.address

and start Open GENIE by typing

$opengenie
Via a terminal emulator
If you start remote sessions on a UNIX workstation via a terminal emulator such as eXceed or eXcursion, you can start Open GENIE directly by telling "rexec" to run the "rgenie" command. Note the full pathname may be required, for example

>/usr/local/bin/rgenie

The "rgenie" command can take several parameters, for further details type

>man rgenie

A typical use may be to start Open GENIE with your own "genieinit.gcl" file, for example

>rgenie "myinit.gcl"

An alternative is to use the terminal emulator to set up an xterm or a decterm on one of the UNIX or VMS workstations from which Open GENIE can then be run.

A few useful facts about Open GENIE

Commands

Commands in Open GENIE are entered via the command line. The command line is based on the GNU readline library and you will find that you can recall and edit previous commands by using the arrow/cursor keys. Commands are saved between sessions in a ".genie_history" file in your home directory, and this can be searched for previous commands. For features of the command line see the appendix A.

Commands in Open GENIE consist of either assignments or keyword commands. Assignments are made using the "=" sign, for example

<destination-location>=<expression>

The destination-location is a variable or an element of a compound variable such as an array or workspace, and the expression can be:

a literal value e.g. 5.6 or "hello"

a variable or part of a variable e.g. Two_theta, or w1.npts

function expression e.g. Sin($Pi)

unary or binary expression e.g. -1, or 1+2

Any Open GENIE procedure can be implemented by a keyword command, and if the procedure returns a value it can also be invoked in an expression, where the value is assigned to a variable. A keyword command starts with a keyword followed by a list of qualifiers and parameters. The keyword specifies the basic command, while the qualifiers modify the action of the command and the parameters supply the values which the command operates on. For example, a keyword command is

>> display/Line w1

This command plots the workspace w1 as a line. By itself the display command plots a histogram, the /line qualifier modifies the command to perform the plot as a line rather than a histogram, and w1 is the parameter. When the Open GENIE procedure is implemented in an expression, in the functional style, qualifiers are specified by placing a colon separated list after the function name and before the parentheses containing the parameter list. For example, in the case of the Asciifile() command to open a file:

>> file=Asciifile:Open("mydata.dat") # functional style
>> Asciifile/Close "mydata.dat" # keyword command style

Note: comments can be included by using the ‘#’ symbol before the comment, everything following this is ignored.

Data types

In Open GENIE you can create new data easily, and these can be independent from each other or grouped together into arrays or workspaces. The data can be either an integer number, a real number, or a character string.

Integers are used mainly for counting or specifying quantities, for example array indices.

Real numbers are always stored as floating point double precision values. They can be specified as a number with a decimal point or in scientific notation. Examples are

+0.5 -.01 33. 1.6e-19

Note: the type of Open GENIE data can change with the way it is assigned, for example

> R=1.0 # R is a real value of 1.0
> R=2 # R is now an integer

Strings may be of variable length and combined and assigned just like the other types of Open GENIE variables. Literal strings are always specified within double quotes e.g. "my_quote" to avoid any conflict with variable names. When the character "\" is used in a string it introduces control sequences, for example, "\n", puts in a newline. For more see the section on storage in the Open GENIE reference manual.

Data types may be either constants or variables. Constants are prefixed by a ‘$’, and can only have a value assigned to them once, usually when they are first created. All available constants can be viewed by typing:

>>Show/Const

System constants are prefixed by $_ and can be viewed with

>>Show/Const/Sys

Variables are created by assigning a value to an unused variable name. A variable name may consist of alphanumeric characters, the "_" character, or numbers, but must start with a letter. Examples are

>>A=2.0 ; B=6

To see all the defined variables type:

>>Show/Var

All variables are preceded by an underscore "_" are reserved for internal use by Open GENIE and these may change or be removed at any time, and therefore you should avoid using any variable starting with "_". The command

>>Show/Var/Sys

will show all system variables.

Arrays are structures that contain more than one variable. There are three array types one for each of the basic variable types. An array is created by first generating an empty array of the appropriate size and dimensionality using the Dimensions() function and then by assigning values to its elements. For example

# Create a RealArray
>> two_d_data = Dimensions(100,200) # created in 2-dimensions
>> two_d_data[1,1] = 5.0 # type is set here to real
>> Printn two_d_data
[5.0 _ _ _ _ ...] Array(100 200 )

Arrays may be manipulated as a whole or, alternatively, individual elements may be accessed and modified separately. Note: all elements which have not had a value assigned to them are marked as a "_". You can specify a value for undefined elements using the FIX() command.

Workspaces are compound variables, where individual elements of the variable maybe of different types (contrast with arrays, which are all of one type). Examples of similar structures in other languages are a record in Pascal or a struct in C. The following example shows the construction of a simple workspace interactively.

# create a brand new workspace
>> mywork = fields() # creates an empty workspace
>> Printn mywork # look at it now
Workspace []
(
)
>>
# Now put some fields in it
>> mywork.description = "My test workspace"
>> mywork.some_value = 3.14159
>> mywork.anarray = dimensions(2,3)
>> mywork.anarray[1,1] = 25
>> Printn mywork # now look again
Workspace []
(
some_value = 3.14159
anarray = [25 _ _ _ ...] Array(2 3 )
description = "My test workspace"
)
>>

Note: structure() may be used instead of fields().

Operations

The normal operations on integers and real numbers are

x^y. If x is an integer then the result will be an integer no matter whether y is fractional or not.

+, -, *, /, and the remainder or modulo function |. For the quotient and remainder operations on integers the convention is to truncate towards zero.

<, >, =, <=, >=, !=. The comparisons of: less than and greater than, equal to, less than or equal to, greater than or equal to and, not equal to respectively.

Sin(x), Cos(x), Tan(x), Arcsin(x), Arccos(x), Arctan(x). The trigonometric functions, where x is quoted in radians. The constant $PI is available for conversion to degrees.

Log(x), Ln(x), Exp(x) the Transcendental functions.

Note: the results of the trig. and transcendental operations on integers are given as real numbers, and when an expression contains integers and real numbers the result is given as real after implicitly converting any integer values to corresponding real values.

The normal operations on strings are:

+ or & concatenates two strings. For example,
>>A= "Hello" + " there" & "!"
<, >, =, <=, >=, !=. For strings of the same length, the comparisons act as a test based on the collating order of the text in the strings. For strings of different lengths, comparisons are between the string lengths.

Substring(), Locate(), Length() for more information see String Handling Functions in the Reference Manual.

The basic operations on arrays are those of the corresponding data type plus:

Array[i,j,k,...]. This indexing allows individual array elements to be accessed using integer indices. Note: all indices start at one. For example

>>printn my_array[12,34,5,3,2]
32

Array[l1:l2,l3:l4,...]. This slicing of an array produces a smaller array with limits of l1 to l2, l3 to l4. If variables are used as limits extra brackets must be included. For example

>>a=my_array[2:4,4:100]
>>b=another_array[(i):(k)]

& Appends the RHS array to the end of the LHS array, for this operation both arrays must be of the same variable type.

Note: the unary, trig. and transcendental functions are applied individually to each element of the array. The binary operations are applied to the elements of the two arrays, if the arrays differ in dimensionality, the corresponding elements are selected using storage order. The result of the operation is to create a new array of identical structure to the array on the left hand side of the operator. If the LHS array is longer, the extra elements are set to the undefined value nil in the result array, while if the LHS array is shorter the result array is truncated to the length of the LHS array. The comparisons test whether the elements and/or length differ.

The basic operations on workspaces are those of the corresponding data type plus:

<workspace>.<field-name>. This field accessing allows its value to be read or set. A field is automatically created in a workspace when a value is assigned to it.

The comparisons when operated on workspaces assume that the workspace is an Open GENIE spectrum, but these operations can be modified by the user, see the Open GENIE reference manual.

File names

Open GENIE takes file names in either the VMS style or UNIX style depending on the system being used. For VMS

USER$DISK:[FAA.GENIE]TEST.DAT

or on UNIX

/usr/users/cmm/genie/test.dat

System commands from inside Open GENIE

The cd command changes the default working directory while in Open GENIE. For example:

# Change to the examples directory on UNIX
>> cd "/usr/local/genie/examples"
>> dir

Note: the directory path is as specified on the native operating system, e.g. VMS or UNIX.

The dir command lists the files in the current directory or the directory specified on the host operating system. For example:

# List the examples directory on VMS
>> dir "[.examples]"

The pwd prints the current working directory. For example

# Change to the examples directory
>> cd "/usr/local/genie/examples"
>> pwd
/usr/local/genie/examples

The Os command prints the operating system Open GENIE is currently running. For example:

# Print the current operating system
>> printn Os()
OSF

The system command allows you to execute a single command or a command session of the native operating system from within Open GENIE. For example:

# find some user details on VMS
>> system "SEARCH journal.txt \"flux\" "
IRS14142ZAB/NJR Flux tests 18-FEB-1997 12:00:01 163.2
IRS14143ZAB/NJR Flux tests 18-FEB-1997 13:43:40 6.1
>>

If no command is given as a parameter, the System() command starts a sub-shell process which is terminated by an exit on UNIX, or a LOGOUT on VMS systems. Note that on VMS some normal logical name definitions may be missing in the sub process.

Getting help

Online Help in Open GENIE is available in a number of ways:

to see a list of all Open GENIE commands, press <Ctrl>H on a blank command line; if it pressed after a letter a list of all commands that start with that letter will be printed;

pressing <tab> twice will list all commands that match with what has already been typed so far. Therefore pressing <tab> twice on an empty command line lists all the commands;

if the command name is not known use <Ctrl>K to perform a keyword search of the command descriptions;

if the command name is known, run it with the /HELP qualifier to get a description and list of parameters. For example

>> display/help