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:

Installations are provided for the following unsupported computing platforms:


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:

Systemtime taken (Native compiler)time taken (g77)
SGI-R10000/Irix6.21.0 (f77)2.1
PC/Windows1.0 (DEC Fortran)1.35
PC/Linux1.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

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:

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:

  • touch 'source-file'.f
  • make cns_solve debug='-g'
  • dbx $CNS_INST/bin/cns_solve

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).