Notes on aspects of Sunsort
===========================

This file contains notes on various bits of Sunsort that don't fit into
any of the manuals.

Contents
--------

1. On the fly projection of 2d spectra
2. In depth syntax checking of sort codes

1. On the fly projection of 2d spectra
--------------------------------------

The 2d spectrum viewer program can project spectra at arbitrary angles.  This
is done on the fly in the graphical user interface allowing the user to easily
check lots of angles.

To enable the feature select Slicing->Arbitrary angle. A new window will
appear with the projection controls in. Lines will appear in the main spectrum
window showing the direction of projection. A series of parallel lines are
drawn parallel to the projection direction, and a single line is drawn showing
the line the projection is performed on to.

The projection window has the following controls:

Project Area:	  This controls whether the full spectrum is projected, or just
		  the area inside the slicing window (this window is set with
		  Slicing->Set Slice Window).

Axis:		  This controls whether the projection is performed on to the
		  X axis, the Y axis, or the perpendicular to the projection
		  axis. Since the choice of axis only affects the dispersion
		  of the projected spectrum, and the window here automatically
		  scales, no change will be seen as the axis is changed.
		  However, when the data is finally passed do sort_xvgr, the X
		  axis values will reflect the chosen axis.

Projection angle: This slider controls the projection angle. The displays
		  react in real time as the slider is moved. The angle set here
		  is the real angle in the coordinate space of the spectrum,
		  not the on screen angle (see below for more details).

X and Y:	  These set the scalings on the X and Y axes. Set these as
		  written, so that if to convert an X channel number into an
		  angle in degrees you muse multiply by 2 and add 5 you
		  would set the X line to read:
		          X: Degrees = channels * 2 + 5

Project onto ...: This sets the coordinate the projection axis is drawn
		  through. The only affect of this is to translate the
		  projection.  Since the window here automatically tracks the
		  projection, no change will be seen. However, when the data
		  is finally passed do sort_xvgr, the X axis values will
		  reflect the chosen coordinate.

|P|2 order:	  This overlays a squared Legendre polynomial of the specified
		  order over the data. The up and down arrow buttons alter the
		  order, and the + and - buttons alter the height of the
		  polynomial.

Do Projection:	  This button passes the data to sort_xvgr from where it can
		  be printed, and other transformations can be performed.

Note about coordinates:

In the projection window, coordinates and angles refer to the a coordinates
and angles in real space. This is the same as the displayed space if, and
only if, the X and Y scalings are both set to *1+0. To get spectra to display
on screen with reasonable scales, it is sometimes necessary to disperse the
spectra, for example, if theta and psi are variables holding the angles theta*
and psi in your FORTRAN code, and have the values in degrees, and you used the
code.

	call inc2d(5, nint(psi), nint(theta))

Then the on-screen coordinates would match the real coordinates, however, it
is rare that this is the case. More likely is something like:

	call inc2d(5, nint(psi*2-116), nint(theta*3+64))

If there were ridges in theta-psi space with an angle (atan(dtheta/dpsi)) of
30 degrees, then on screen, this would be an angle of 41 degrees. Provided
you set the scalings correctly to :

	X: Degrees = channels * 0.5     + 84
	Y: Degrees = channels * 0.33333 - 21.33333

Then, when the lines drawn on screen lined up with the ridges (a screen
angle of 41 degrees), the projection angle displayed in the window would
read 30 degrees.

Note on integer rounding:

In line with the current practice of using nint() to round values in FORTRAN,
the projection code assumes that each histogram bin is centred round its
channel value. For example, the bin (36,25) takes all values in the range
35.5<=x<36.5, 24.5<=y<25.5. This matches the behaviour of the 1D routines.

In C, this rounding is performed by:

	(int) (x + 0.5)

Note that just saying (int) x will round down.

The f and d prefixed spectra functions (see below) perform the correct
rounding.

2. In depth syntax checking of sort codes
-----------------------------------------

The FORTRAN syntax checker program ftnchek is now bundled with sunsort.
Makesort knows how to invoke it to check function calls into standard sunsort
functions. Makesort also knows how to call lint for C sort codes.  To use
makesort to do this, add the keyword check to the command line, for example,

	makesort sortcode.srt check			FORTRAN code
	makesort sortcode.srt check -xC			C code

Alternatively, if you are using sort_tool, press the button marked "Check"

Ftnchek complains if, in variable declarations, the save command comes after
the implicit none command. Technically it is correct, the Sun FORTRAN compiler
is flexible enough to allow the command either way round.

Ftnchek also complains if you have variable declarations after data
statements, for example,

	integer xxx(2)
	data xxx/3,5/
	integer i

Again, it is technically correct as, according to the FORTRAN specification
data statements must come after all declarations. The Sun FORTRAN compiler is
flexible enough to allow misordered statements (and although ftnchek warns you
about such statements, it can cope with them).

Ftnchek also complains if you use " to delimit strings, strict fortran
specifies that the ' character must be used, so,

	call eginit("egmap.dat",ierror)

is strictly illegal in FORTRAN, you should say,

	call eginit('egmap.dat',ierror)

The Sun compiler allows both, ftnchek only allows '.

What ftnchek is really good at is picking up when you've passed the wrong
types, or wrong number of parameters to a function.

You can use ftnchek on your own FORTRAN programs (that is, other programs than
sort codes). You should read the manual first by typing:

	nroff -man /the/directory/containing/sunsort/man/ftnchek.1 | more

If you have a complex sort code involving multiple files, then you should
learn how to invoke ftnchek or lint yourself.
