Appendix E - Distribution and Installation of SHELXL-93

shelxl.for

SHELXL source for VAX/VMS 'front end'; this should be compiled without vectorization or optimization.

shelxl.f

SHELXL front end for UNIX (and some other) systems.

shelxlv.f (or shelxlv.for)

sources for routines which should be fully optimized and/or vectorized. The VAX/VMS and UNIX versions are identical.

tyme.c

C routines for the date and time for those UNIX systems which do not provide them (i.e. IBM RS/6000 series). If these are used, all calls from shelxl.f to 'TIME' must be changed to 'TYME' to avoid a clash of names. A special version of 'shelxl.f' (called 'shelxl.ibm') is available in which this has been done.

shelxl1.f, shelxl2.f, shelxl3.f and shelxl4.f (or shelxl1.for etc. for VMS)

the remaining sources for the main body of the program which should be compiled without vectorization or optimization. The VAX/VMS and UNIX versions are identical.

shelxl.hlp

this documentation. This MUST be read before attempting to install or use the programs!

sigi.ins, sigi.hkl, ags4.ins, ags4.hkl

test input files for SHELXL-93 (discussed in detail earlier in this documentation).

pdbins.f

essentially computer-independent source of PDBINS (see Appendix B).

shelxl.dic

restraints dictionary (currently only for proteins) which is read by PDBINS. This may be used as a model for local 'restraints dictionaries'.

ciftab.f

essentially computer-independent source of CIFTAB (see Appendix C).

ciftab.def

standard format file for input to CIFTAB. This may be used as a model for users to produce modified tables, formats for specific journals etc.

ciftab.ang, ciftab.met and ciftab.ger

special format files for tables production using the XTEXT program in the Siemens SHELXTL system.

Compilation on VAX/VMS systems

(a) VaxStation, MicroVAX etc.

$ FOR SHELXL,SHELXLV,SHELXL1,SHELXL2,SHELXL3,SHELXL4
$ LINK SHELXL,SHELXLV,SHELXL1,SHELXL2,SHELXL3,SHELXL4
$ SET PROT=(W:E) SHELXL.EXE

(b) VAX 9000 (vector processor) etc.

$ FORT SHELXL,SHELXL1,SHELXL2,SHELXL3,SHELXL4
$ FORT/VECTOR/ASSUME=(NOACCU,NODUMM)/MATH=FAST/SHOW=ALL SHELXLV
$ LINK SHELXL,SHELXLV,SHELXL1,SHELXL2,SHELXL3,SHELXL4
$ SET PROT=(W:E) SHELXL.EXE

In both cases the following symbol should also be defined for each session in which the program is used:

$ SHELXL :== $ DISK:[USER]SHELXL

where DISK and USER define where the file SHELXL.EXE is located, and will need to be replaced by the appropriate names for your system. This line may be included in the LOGIN.COM file for individual users, or - better - a global symbol SHELXL can be defined in the file which is executed when the system is started.

For UNIX systems all filenames associated with SHELX should be lower case. The name of the compiler and the optimization switches etc. differ for different systems. There is no need - and it will probably prove counter- productive - to optimize 'shelxl.f', 'shelxl1.f' etc., but it is important to compile 'shelxlv.f' with the highest available optimization level. Typical instructions to compile and link would be:

# f77 shelxlv.f -c -O2
# f77 shelxl.f shelxl1.f shelxl2.f shelxl3.f shelxl4.f shelxlv.o -o shelxl

The executable program shelxl may then be copied into a directory such as /usr/bin/ for general use (which will require superuser privileges). The UNIX version of SHELXL-93 is able to read the '.ins' and '.hkl' files in either UNIX or DOS format, and may be set up to write the '.res', '.cif' and '.fcf' files in DOS format, so that PC's can access such files via a shared disk without the need for conversion programs such as DOS2UNIX etc. To compile the program with this option the first executable statement in shelxl.f should be KD=CHAR(13) (see the comments in the source). For reasons of efficiency the '.lst' file is always in the local format (it can still be printed directly from a PC using SPRINT - see below).

Since IBM do not (yet) provide FORTRAN-callable DATE and TIME routines, it is necessary to include FORTRAN-callable C routines DATE and TYME provided in the file tyme.c. They may be compiled as follows:

# xlc tyme.c -c

The rest of the program is then compiled and linked as follows:

# xlf shelxlv.f -c -O
# xlf shelxl1.f -c -NT50000 -NQ50000
# xlf shelxl2.f -c -NT50000 -NQ50000
# xlf shelxl3.f -c -NT50000 -NQ50000
# xlf shelxl4.f -c -NT50000 -NQ50000
# xlf shelxl.f shelxlv.o shelxl1.o shelxl2.o shelxl3.o shelxl4.o tyme.o
  -o shelxl

Where shelxl.f is a special version in which all the calls to TIME have been changed to TYME; the file 'shelxl.ibm' in which this change has been made may be copied to 'shelxl.f'. Note that the file 'shelxl.ibm' also specifically closes all files before terminating to work around a known system problem.

'shelxl.f' must be modified by replacing the statement T=... in subroutine SXTI (in 'shelxl.f') to:

      T=ETIME(TX)

where TX has been declared as a REAL array of dimension 2, i.e. the statement REAL TX(2) is included after the first statement of the subroutine.

The same alteration must be made as for Convex, and the -lV77 switch used on the f77 compile/link instruction (n.b. lower case 'L', not digit '1').

The line: T=.01*REAL(MCLOCK()) should be changed to:

      T=SECOND()

It is simpler (and safe) to vectorize all routines:

# cf77 -l nag -Zp -o shelxl shelxl.f shelxlv.f shelxl1.f shelxl2.f shelxl3.f
  shelxl4.f

Although the UNIX and VAX/VMS versions are almost identical, it will probably prove easier to adapt the UNIX version. The program is standard FORTRAN-77 except for the following routines. Sometimes compiler and linker switches should be set for VAX/VMS-compatibility. Usually it is best to compile and link without optimization first to see if there are unresolved subroutine references. These should only refer to the following non-standard FORTRAN-77 routines, and will have to be replaced by calls to local alternatives. There are a very small number of such calls, and all are to be found in the 'front-end' routines in shelxl.f (or shelxl.for for VMS). A pitfall for the unwary is the possibility that the same names are used for local routines but with different specifications, which can cause the program to appear to compile and link correctly but to abort when started; the most likely culprit is 'TIME'.

TIME and DATE - these subroutines should return the current time and date as strings 'HH:MM:SS' and 'DD-MON-YY' (where HH is the hours part of the time as two digits, and MON is a three character abbreviation for the month, etc.). It does not matter which characters are used as separators.

MCLOCK - this function should return the current time as a INTEGER number of 1/100 seconds from an arbitrary starting time. The function ETIME (see above) (which returns the number of seconds as a REAL) is a common alternative.

IARGC and GETARG - the INTEGER function IARGC should return the number of command line parameters, and the subroutine call GETARG(IARGC(),string) is then used by SHELXL-93 to extract the last of these (it is used to set up all the file names by adding the appropriate extensions). This avoids the confusion over where to start counting parameters!

Two precompiled PC versions are provided. 'SHELXL.EXE' is a 32-bit version which runs in 'protected mode' on 80386SX, 80486SX, 80386DX, 80486DX and Pentium processors. For the first three a numeric coprocessor must also be present. The program contains a built-in (Phar Lap) protected mode loader and so runs as a stand-alone program. It runs as a virtual memory program if the available extended memory is less than about 5MB, which means that about 10MB disk space should be free for scratch files. Since the program is particularly efficient as regards disk input/ouput, it is usually better to leave extended memory free for the program rather than to install a disk cache. On systems with limited physical memory it may be necessary to remove other resident programs and protected mode drivers (in 'AUTOEXEC.BAT' and 'CONFIG.SYS', then reboot). If the program fails to load properly it usually means that either not enough memory is available, or that a memory manager or other resident user of extended memory conflicts and has to be removed first. The Lahey / Phar Lap banner which appears when the program is started gives the amount of extended memory available to the program; it may be suppressed by the statement:

SET DOS=-NOSIGNON

For older personal computers and systems with too little extended memory the 16-bit 'real mode' version 'PCSHELXL.EXE' is also provided. It contains all facilities of 'SHELXL.EXE' but is somewhat slower and has limited memory, so for example is restricted to 300 full-matrix parameters. BLOC or CGLS may be used to refine larger structures, provided that there is room for all atoms, restraints etc.; since the memory allocation is dynamic, there are no individual limits except on the number of least-squares parameters. This version should run on ANY personal computer with an 8088 or compatible CPU and the corresponding coprocessor (not required for 80486DX etc.) and 640 kB of memory. The scratch disk space required depends on the size of the structure; at least 2MB is recommended (a RAM-disk may be used - the scratch files are set up in the current directory). If there is not enough memory to run the program it may be necessary to remove resident drivers (network software is particularly greedy). Although this program should be compatible with MSDOS 2.10 and all subsequent versions, version 5.0 or later is recommended.

Although both PC versions are tolerated by MS-WINDOWS and other multitasking interfaces, there is usually a considerable price to pay in terms of performance degradation. If PC's and RISC machines are linked by a NFS network, they may be run using the same files provided that these are in DOS format, because the UNIX version of SHELXL-93 can read DOS format .ins and .hkl files and can be set up to write DOS format .res, .cif and .fcf files (by setting KD=CHAR(13) as the first executable statement in shelxl.f - see comments in the source). If this has been done, all editing may be performed on the PC's; any text editor may be used.

For PC's which are connected to a HP Laserjet or compatible printer, a special program SPRINT is provided for printing the documentation and listing files. SPRINT can print both DOS and UNIX format text files (the latter facility is useful for NFS networks). If no filename extension is specified, .lst is assumed. If .lst is given or assumed, the output is compressed; otherwise a margin is left on the left hand side. SPRINT should be able to handle read-only files and printers running out of paper. Examples:

SPRINT SHELXL.HLP (to print this manual; similarly READ.ME and REFEREE.MSG)

SPRINT AGS4 (to print AGS4.LST in compressed mode after running the test job)

Memory requirements, paging etc.

The program uses two large arrays A and B dynamically, so the limits on the size of structure which can be handled are determined by the dimensions of these two arrays and also of the array C; A, B and C are defined as separate COMMON blocks. The standard version of the program is dimensioned for up to 1500 parameters in each full-matrix block and roughly 5000 atoms (assuming a generous number of restraints etc.), and is suitable for a typical (UNIX) workstation (or mainframe) with 8MB or more physical memory; the precompiled (protected mode) PC version 'SHELXL.EXE' is similarly dimensioned.

It may be necessary to redimension A, B and C and recompile the program for specific installations, e.g. to fit within a given job category on a mainframe. The highest elements of A and B actually used for the various calculations are printed out by the program (after 'Memory required ='). The program will try to use all available physical (and virtual) memory rather than performing its own disk I/O, thereby achieving longer vector 'runs', which enhances performance on vector and pipelined systems. In some cases, e.g. when a large structure is refined on a MicroVAX or PC with limited physical memory (or allocation of physical memory to a given process in the case of the VAX) this strategy may cause excessive 'paging' and disk I/O. If this happens, the maximum vector run length can be reduced by setting the 4th parameter on the L.S. instruction or by reducing the value of the variable IV in the main program and recompiling; it may also be more efficient to 'block' the refinement or use CGLS (except in the final refinement).

Back to D - Example of an Acta Cryst. Paper in '.cif' Format

Back to Appendices

Back to Table of Contents