Installation
The tar file will create a unique directory name for this version of CNSsolve (cns_solve_'version-name''patch-name', eg. cns_solve_1.0a). It is then possible to have several different versions of CNSsolve installed simultaneously, any of which can be accessed by the user.
The following will compile the CNSsolve program and utilities
The machine architecture is automatically determined at installation time. For example on a Silicon Graphics R10000 O2 running Irix 6.3 the architecture will be automatically determined to be: sgi-r8k10k-irix-6.3. A directory will be made with this name and the appropriate files automatically installed and compiled in this directory.
Once installed the machine architecture directory should not be moved.
NB. you require working fortran 77 and C compilers in order to install CNSsolve
Installation on multiple machine types
Each machine type is installed in a unique directory therefore it is easy to install CNSsolve on several different types of machines simultaneously on a shared filesystem. Access to the correct executable is automatic.
Available installations
The following computing platforms are supported:
SGI (R4000 and later) running IRIX 4.0.5 or later
HP (PA Risc) running HP-UX 9.05 or later
Compaq Alpha running OSF1/Digital Unix/Tru64 Unix
PCs (i386, i486, i586, i686) running Linux
PC running Windows-98/Windows-NT
Installations are provided for the following unsupported computing platforms:
Convex running ConvexOS
Cray (J90, YMP, C90, T90) running Unicos
Cray T3E (single CPU) running Unicosmk
IBM RS/6000 running AIX
Sun running SunOS
Unix systems with g77/gcc (EGCS-1.1)
Windows-98/Windows-NT systems with g77/gcc (EGCS-1.1)
Different versions of operating systems
If several machines of the same type are available with different versions of the operating system it is sufficient to install CNSsolve on only one of the machines - the one with the earliest version of the operating system. Subsequent user access to CNSsolve via the cns_solve_env script will use the closest compatible executable compiled for an earlier version of the operating system. For example, assuming the following Silicon Graphics machines are available:
It would be sufficient to compile CNSsolve on the first machine (running Irix 6.2) to obtain a binary that will run on all the machines above. In this particular case there is no significant loss in performance. However, it is possible that an older compiler may produce a less efficient executable, in this case multiple installations are recommended.
NB. It is assumed that a later version of an operating system is backward compatible with an earlier one, if this is not the case then CNSsolve must be installed on both machines.
Silicon Graphics and CNSsolve
All CNSsolve executables compiled on SGI machines are 32-bit (compiled with -n32 where applicable). Machines are divided into 2 categories:
Thus, in general, it is sufficient to compile CNSsolve only twice (once for each category above) to run on all available SGI machines.
32-bit and 64-bit compilation: Contrary to
popular belief, there is no significant performance gain compiling in
64-bit mode (-64) on SGI machines. However, 64-bit compilation does offer
increased memory address-space (more than the 2Gbyte limit imposed by
32-bit compilation). Therefore, if a structure is so large that an
address space larger than 2GB is required, CNS can be recompiled with
64-bit addressing by the following:
make clean
setenv CNS_ABI '-64'
source cns_solve_env
make cns_solve
Automatic parallelization of CNSsolve at compile time using the SGI PFA compiler is not implemented. The parallel version of the SGI FFT libraries (complib.sgimath_mp) will be used only if the PFA compiler is installed. After compilation, parallel FFT operation can be achieved on multiprocessor machines by setting (with setenv) the following environmental variables to some number larger than 1:
Versions of the operating system prior to 4.0.5 are not supported.
Stand alone Windows-NT version
A self-extracting ZIP archive is provided for stand alone installation on a Windows-NT machine. The archive contains a compiled CNSsolve executable. Once installed, the program can be run from the command line as on Unix platforms. The file windows-nt/cns_solve_env.bat must be modified to point to the correct location for the CNSsolve directory. This batch file must be executed prior to running CNSsolve. The HTML based documentation and WWW interface can be accessed through Netscape (version 3 or higher) or Internet Explorer (version 4 or higher).
CNSsolve development on Windows-NT
A Unix installation script is provided for setting up CNSsolve for development (compilation and testing) under Windows-NT:
This script must be run on a Unix platform where CNSsolve is already installed. After running this script, if not already present, a directory is created called windows-nt. The code can be compiled on the Windows platform with:
The DEC Fortran compiler (5.0 or later) must be installed for compilation of CNSsolve.
Compilation using g77/gcc
CNSsolve can be compiled using the GNU FSF g77/gcc compilers on both Unix and Windows platforms (this has only been tested using EGCS version 1.1b). To install using g77/gcc on Unix platforms use:
CNSsolve will be installed in a directory with the postfix _g77. If CNSsolve is installed with both native and g77 versions on the same machine, sourcing the cns_solve_env file will by default access the non-g77 version. To switch to g77 executables (for running and compilation):
After patching CNSsolve, to update a g77 installation use:
A Unix installation script is provided for setting up CNSsolve for development (compilation and testing) under Windows-NT using g77/gcc:
This script must be run on a Unix platform where CNSsolve is already installed. After running this script, if not already present, a directory is created called windows-nt_g77. The code can be compiled on the Windows platform with:
Warning: the g77 compiler produces code which is slower than the native compilers on all machines we have tested (this includes fort77/f2c on Linux platforms). Therefore, g77 should only be used if no other compiler is available. Average timings are as follows:
System | time taken (Native compiler) | time taken (g77) |
SGI-R10000/Irix6.2 | 1.0 (f77) | 2.1 |
PC/Windows | 1.0 (DEC Fortran) | 1.35 |
PC/Linux | 1.0 (fort77/f2c) | 1.2 |
General installation problems
Known problems on supported achitectures
SGI
With newer compilers an error may be reported at runtime saying the BLAS library is missing, and the program will not start. The BLAS library is not installed by default with these newer compilers. This must be installed in order to run CNSsolve:
There are problems with Irix 6.3 on O2 systems. The following patch must be installed for correct execution:
If the following error message occurs when running CNSsolve under Irix 6.2 or 6.3:
FFT3C: Using complib.sgimath Fatal Error: Test of FFT3C failed. Program will stop immediately.
Recompile CNSsolve using the generic FFT libraries:
source cns_solve_env make fftfile-generic setenv CNS_FFTLIB "" make cns_solve
This will use generic FFT code rather than the SGI complib.sgimath libraries.
If the following error message occurs when running CNSsolve under Irix 6.5:
Fatal Error: Fatal Error: test of numerical function failed
First try recompiling with the static version of the fastmath library:
make static-fastm
If this still produces the fatal error message then you should compile without the fast math library:
make no-fastm
This problem is present in both Irix 6.5.9 and 6.5.10
DEC Alpha
There is a bug present in the DEC fast math library under DEC Unix 4.0 which effects the exponent function (EXP). Certain small arguments will produce a floating point exception. Patches are available from Digital:
The bug effects the DEC compiler. Therefore, CNSsolve must be recompiled once the patch has been installed. Only machines where CNSsolve is compiled need to be patched. The program should run correctly on unpatched machines if the executable has been compiled on a patched machine.
HP
No known problems
Linux
testing Fortran and C compilers compiling: cc -O -ffast-math -DCNS_ARCH_TYPE_LINUX C compiler passes test compiling: fort77 -w -Nn2000 -O3 -malign-double -funroll-loops -ffast-math MAIN hello: linking: fort77 ***** ERROR: problem with Fortran compiler ***** make[3]: *** [fortran-test] Error 2 make[2]: *** [compiler-test] Error 2 make[1]: *** [compiler-test] Error 2 compiler problems - stopping installation please check compilers before retrying installation make: *** [install] Error 1The f2c libraries need to be recompiled (otherwise any code linked with them will produce a segmentation fault when run). We suggest obtaining the latest version of f2c from NETLIB and compiling the libraries from scratch.
source cns_solve_env ./bin/install -nocompile cd intel-i686-linux mv Makefile.header Makefile.header.f2c mv Makefile.header.pgf77 Makefile.header cd .. source cns_solve_env make makefiles make utils make cns_solve
source cns_solve_env ./bin/install -nocompile cd dec-alpha-linux mv Makefile.header Makefile.header.f2c mv Makefile.header.compaq Makefile.header cd .. source cns_solve_env make makefiles make utils make cns_solve
Windows-NT
Modified task files cannot be directly saved to disk from the WWW interface using Internet Explorer v4 (IE4). This is due to a known bug in IE4 which ignores the Content-disposition: attachment directive in an HTML document returned from a CGI script. Instead of prompting the user for a location to save the file, the contents will be displayed in the brower. The file can be saved by using the save as option from the main menu or cutting and pasting to a text editor. This problem is fixed with Internet Explorer v5. Another alternative is to use Netscape instead of Internet Explorer.
Installing a CNSsolve update (patch)
Instead of having to download the whole distribution, updates to the current version are available as patch files. These patch files will update from the current version at a certain patch level to a new patch level. Users are not usually required to update their input files after a patch is applied - files for a particular version should work at any patch level. Updating to a new version will require downloading of a complete distribution, and users to update their input files.
Patch files:
Patch files are compressed tar files.
They have a consistent naming convention: patch_0.5e_0.5f.tar.Z (this patch updates CNSsolve version 0.5 at patch level e to patch level f). Versions are always numbers, patch levels are always single letters of the alphabet.
In general, patches will be available to update from one patch level to the next (eg. 0.5a to 0.5b, 0.5b to 0.5c). In rare cases patch files may be released which update the base level (unpatched) CNSsolve version to the latest patch level (eg. 0.5 to 0.5g).
Applying a patch:
Possible problems:
Installing the CNSsolve HTML interface locally
In order to provide users with efficient access to the CNSsolve HTML interface it is possible to install a local version on a WWW server. This requires:
Installation of the interface is performed in two stages. First, changes must be made to the CNSsolve installation to customize certain files for your local CNSsolve HTML interface setup. Second, changes must be made on the WWW server to integrate the CNSsolve HTML interface into the WWW server. Both of these tasks are performed by scripts supplied with CNSsolve.
CNSsolve stage of HTML installation:
WWW server stage of HTML installation:
It is important that the correct information is given in both cases. Prior to installation please find out:
Once the CNSsolve HTML interface has been installed, users accessing the local CNSsolve documentation (eg. via cns_web) will automatically be using the local HTML interface.
Each version of CNSsolve will install its HTML interface into unique space on the WWW server. It is possible therefore to have several versions of CNSsolve installed, all of which are fully functional. By accessing the appropriate CNSsolve documentation page the user will arrive at the CNSsolve HTML interface for that version.
The CNSsolve HTML installation stage will create some new versions of files in the doc/html directory which are customized to your local WWW setup (the information you determined above).
The WWW server installation stage will create some
new directories on the server and add links from these directories to
files in the CNSsolve installation. Links are used so that updating of
the WWW server is generally not required if changes are made to the
CNSsolve installation (eg. after a patch). However, the CNSsolve PERL
scripts are copied to the CGI directory on the local WWW server - this
is because links are not usually permitted for executable scripts in a
CGI directory. Therefore, if these scripts change significantly it
may be neccessary to rerun the WWW server installation.
After application of a CNSsolve patch the CNSsolve
administrator may be required to rerun bin/www_cns_setup
to update the customized CNSsolve files. The CGI scripts used by the CNSsolve HTML interface
require temporary space to write files. The scripts will
automatically create directories in /usr/tmp on your WWW server. Each
time the scripts are run they will remove any out-of-date files in the
temporary space. If you wish to use a different location for these
temporary files please contact the CNS developers at Yale. The HTML interface for a particular version of CNSsolve
can be removed by using the commands:
Known Problems There is a bug in the NCSA HTTP daemon version 1.5.2a
running under DEC Unix. This results in corruption of large (greater
than 32 Kbytes) files returned by CGI scripts. There is a patch file
available by ftp from CNS development
(other-patches/ncsa_httpd_1.5.2a.patch). To apply this patch on your
WWW server:
Running the distributed task files
CNSsolve is distributed with task files for many crystallographic and NMR procedures. In general these files will be accessed by local users - either through the CNSsolve HTML interface or a standard text editor. However, it is possible to run these task files in order to check the CNSsolve installation on a particular machine. Please note that this will take a long time, anything from a day to several days depending on the hardware. To run all the task files:
To run task files in a subdirectory:
Changing array dimensions
The array dimensions for several arrays which may
need to be changed (e.g. the maximum number of atoms) are defined at
compile time in the include file
$CNS_SOLVE/source/cns.inc. Modify this file then recompile
CNSsolve using make cns_solve.
Debugging source code
If changes to the code are made, a debugger may be used to track possible possible programming errors. In order to recompile a specific source file for debugging use the following:
The touch is only required if the program has been recompiled since the source file was last modified. The debug flag(s) will be passed on to the compiler.
Once debugging is completed the code should be recompiled without any debugging flags after touching the appropriate source files (make cns_solve).