SYSTERPLOT manual

************************************************************************
*                                                                      *
*    Program    S Y S T E R P L O T    version  0.9      Aug 24, 2000  *
*                                                                      *
************************************************************************
*                                                                      *
*    J.M.M. Smits  and  R. de Gelder                                   *
*    Department of Inorganic Chemistry                                 *
*    University of Nijmegen                                            *
*    Toernooiveld 1                                                    *
*    6525 ED  Nijmegen                                                 *
*    The Netherlands                                                   *
*    smits@sci.kun.nl   and   rdg@sci.kun.nl                           *
*                                                                      *
*    This program is the property of the abovementioned authors.       *
*    However, herewith permission is granted to users to adapt the     *
*    program to their local platform as far as necessary.              *
*    Proper credits are due, though.                                   *
*                                                                      *
*    The program uses OpenGL and GLUT with its FORTRAN bindings for    *
*    which the authors cannot claim ownership in any way.              *
*    The same holds for the way the program is structured to handle    *
*    window events, which can be found in the example program sources  *
*    which are part of the GLUT distribution.                          *
*                                                                      *
************************************************************************


Contents
========

Program Description
Function selection options
Display options
Input file used
Subroutine callcode
Compiling and installing SYSTERPLOT
Executing SYSTERPLOT
Current limitations


Program Description
===================

SYSTERPLOT is used to plot various function of Fobs, Fcalc, sig(Fobs)
and a number of other variables on the y-axis vs. variables pertaining
to experimental conditions on the x-axis.
The user is free to choose almost any combination, resulting in a
very large number of possible plots.
The program uses an output window with standard functions, i.e. it can
be moved, minimized, openend again, be (partially) hidden and brought
to the foreground again. However, its size is fixed: when the size is
changed, the area used will stay the same.
The window is divided in five areas:
1. The title bar, with the compound code, which can be used to move the
   window.
2. The message area at the bottom, in black, used to show the status of
   several settings that the user can change.
3. The plot area, in blue.
4. The function selection options area in grey, below the display area,
   offering 14 selections for the y-coordinate and 10 selections for
   the x-coordinate. Only a few combinations are excluded, namely any
   parameters against itself.
5. The display options area in grey, to the right of the display area,
   offering a large number of options that influence the display.

As it is, the program reads 13 different variables from the input file,
written by SYSTER. For a definition of these variables, please refer
to the SYSTER manual.


Function selection options
==========================

In the function selection area 10 buttons, marked as 'vs.' on the bottom
row, offer possible choices for the x-coordinate. These choices seem to
be self-explanatory enough, just read 'chi' for 'kappa' if you use
Eulerian angles.

The remaining 14 buttons offer possible choices for the y-coordinate,
resulting in a total of 135 combinations (5 combinations, line 'drift
vs. drift', are excluded). Most choices seem self-explanatory enough.

BckgRat is the ratio of the background counts in the original scan,
and is defined as the largest divided by the smallest.

The four 'average' buttons to the right (including the two on the
bottom row) are used to diminish the influence of strong fluctiations
caused by extreme function values resulting from (very) weak reflections
with large standard deviations.


Display options
===============

>  >>  >>>   Shift the viewframe to the right. By pressing the left,
             the middle or the right part of the button, the viewframe
             is shifted by one third, one half or one whole viewframe.

|<--  -->|   Shift the viewframe to the extreme left (left part of the
             button) or the the extreme right (right part of the button).

<  <<  <<<   Shift the viewframe to the left. By pressing the left,
             the middle or the right part of the button, the viewframe
             is shifted by one third, one half or one whole viewframe.

<< step >>   Increase the step size (number of pixels per step) in the
             x-direction. Default is 2 pixels per step. By pressing the
             left part of the button the step size is decreased, by
             pressing the right half of the button the size size is
             increased. The change in step size is a function of the
             current step size: small steps for small sizes and vica
             versa.
             If the step size is decreased to 0, the plot is compressed
             so that the whole plot fits into one viewframe.

sc frame     This is an on/off switch: if off (the default), one
             scale factor is used to fit the extreme function values
             within the vertical dimension of the viewframe. If on,
             each viewframe is scaled separately.

<< +clip >>  Change the maximum clip value. Default value is 100.
             By pressing the left part of the button the clip value is
             decreased, by pressing the right half of the button the
             clip value is increased. The change in clip value is a
             function of the current clip value: small steps for small
             values and vica versa.

<< -clip >>  Change the minimum clip value. Default value is -100.
             By pressing the left part of the button the clip value is
             decreased, by pressing the right half of the button the
             clip value is increased. The change in clip value is a
             function of the current clip value: small steps for small
             values and vica versa.

reverse x    This is a switch button. Normally x-values increase from
             left to right. When switched on, x-values decrease from
             left to right.

sqrt(y)      This is a switch button. When switched on, square root
             values are used on the y-axis.

smooth       This is a switch button. When switched on, a smoothed
             curve is added to the plot. Smoothing is done using a
             5-point function.

<< slim >>   Change the sigma limit for data to be included in the plot.
             The default value is 2.0, meaning that reflections for
             which Fobs / sig(Fobs)  < 2.0 are excluded.
             By pressing the left part of the button the sigma limit is
             decreasedby 1.0, by pressing the right half of the button
             the sigma limit is increased by 1.0.

<<  >>   Change the number of intervals used in calculating averaged
             values of Fo and/or sig(Fobs). The default value is 20.
             By pressing the left part of the button the number of
             intervals is decreased by 2, by pressing the right half of
             the button the number of intervals is increased by 2.

reset view   Reset all user changeable parameters to their default
             values.

EXIT         Exit the program.


Subroutine callcode
===================

Subroutine callcode gets the first argument given in the program
calling sequence; if no argument is given it is asked for.
It is assumed that this argument is the compound code, which is
subsequently used to construct several file names.

This subroutine uses two special statements which are / may be
platform dependent:
iargc()      integer function, returns the number of arguments
             given in the calling sequence, excluding the program
             name itself; returns 0 if no arguments are given.
getarg(i,s)  this subroutine gets the i-th argument from the
             calling sequence, excluding the program name, and
             stores the argument value in character string s.

If you cannot adapt these calls to your local platform, it is quite
easy to remove these calls from the program. In that case any
calling sequence parameters will be ignored and the compound code
will always be asked for.


Input file used
===============

There is only 1 input file, the *.syster file produced by SYSTER.
There is no output file.


Compiling and installing SYSTERPLOT
===================================

The 'makesyster' file as supplied with the source code has nothing
to do with a Unix-like make procedure. It just contains the necessary
Silicon Graphics IRIX compile statement, and can be executed after the
necessary mode has been set, e.g. 'chmod 7** makesyster'. It only shows
how it is done on our platform. Special attention should be paid to
the libraries needed and the order in which they are declared.

To install SYSTERPLOT, just copy the executable to a suitable place
pointed to in your path, and probably do a rehash.


Executing SYSTERPLOT
====================

SYSTERPLOT should be executed from the directory containing the
*.syster file.

To run the program just enter 'syster compound-code' (mind the lower
case). If you leave out the compound code, it will be asked for.

The program reflects our measuring device: we use a Nonius CAD4
diffractometer. The setting angles are defined in the so-called
kappa-geometry. If you use an Eulerian diffractometer, just read 'chi'
for 'kappa'.


Current limitations
===================

There are a few limitations to the program. The number of reflections
is limited to the size of various arrays, i.e. 20,000. To prevent
problems with defining dynamic memory allocations on various platforms,
predefined arrays are used. By changing the size of the arrays in
'systerplot.inc' and block data, this number can be changed. This, of
course, should be done in concord with SYSTER, which uses the same array
sizes.

At present 13 different variables are recognized from the input file,
although the number to be read is specified in the first record. The
program SYSTERPLOT has a limit of 15 different variables. But also this
limit can be adapted.

The plots using averaged values for Fobs or sig(Fobs) are not
available, as yet.

There is no horizontal marking of the x-axis as yet.

There is no real relation between the value of the x-coordinate and the
position on the x-axis. The data are sorted according to the values of
the x-coordinates, and the data points are then plotted using equally
spaced steps on the x-axis.

Back to the SYSTER page