UV-CDAT Files

Climate Data Analysis Tools (CDAT)

VERSION: 4.0.5

UCRL-CODE-2002-0021

Documentation is at http://cdat.sf.net
Support: cdat-discussion@lists.sf.net

Please see file Legal.htm for our open-source release license.



Release specific Notes are in file: ReleaseNotes.txt


ON ALL PLATFORM YOU MUST UNSET THE FOLLOWING ENVIRONEMENT VARIABLES 
unset PYTHONPATH
unset PYTHONHOME

ON MOST PLATFORMS YOU MUST SET ENVIRONMENT VARIABLE CC BEFORE BUILDING

--------------------------------------------------------------------------
-------------------   Platform-specific instructions  --------------------
--------------------------------------------------------------------------

            Required value of                  
Platform    environment variable CC            Notes
========================================================================
AIX          cc_r
Irix 6.5     cc         Use configuration option -c irix to get n32 X11
Linux 2.4.2             Builds as is with gcc. 
HP-UX 11     cc +z
MacOS                   Builds as is with gcc. You need to install ghostscript
			and g77 (via fink for example)
OSF1         cc
Solaris      cc -mt     Be sure you are set up for Sun compiler).
                        Also on solaris (SunOS 5.8 at least)
                        you'll need to make sure the following variable 
			are set correctly when building. You don't need to have 
			them set later on.
			LD_LIBRARY_PATH_BASE and LD_LIBRARY_PATH must point to 
			your cc C compiler and Fortran77 libraries (for contrib)

			On our test build platform we have:
			CC = 'cc -mt'
			LD_LIBRARY_PATH=/usr/ccs/lib:/usr/lib:/opt/SUNWspro/lib
			LD_LIBRARY_PATH_BASE=/usr/ccs/lib:/usr/lib

The way you would set the environment variable CC depends on the shell you
use. Example:

For csh: setenv CC value
For sh: set CC=value; export CC

If the value is more than one word you have to quote it, e.g., "cc -mt".

--------------------------------------------------------------------------
-------------------             DOWNLOADS              -------------------
--------------------------------------------------------------------------
To install an entirely new installation requires 3 parts: pysrc, exsrc,
and the cdat distribution. If you already have a suitable
Python installation you can skip getting pysrc.

------ Where should I install cdat? 
In what follows we use the notation [CDAT_INSTALL_DIRECTORY] to indicate the full path name
of the directory into which cdat is to be installed.

We require that [CDAT_INSTALL_DIRECTORY]'s parent directory must already exist
for safety.  You must have write permission in it. For distributions that 
will be used by others, /usr/local/cdat-3.3 or the like would be appropriate.

/usr/local is a poor choice, as chances of collisions with other installations
and unintended consequences are too high and uninstalling becomes difficult.

[CDAT_INSTALL_DIRECTORY] will be created if necessary.  These subdirectories will be 
created in [CDAT_INSTALL_DIRECTORY]: bin, lib, include, man, man/man1, and man/man3.

--------------------------------------------------------------------------
---------------------------      SUMMARY       ---------------------------
--------------------------------------------------------------------------

------ Express installation from scratch using OUR Python distribution:

Preconditions for use:
a. You have unpacked all three parts in the same directory,
   so that pysrc and exsrc are subdirectories of this one.

b. You want to use our Python distribution.
   (See discussion below in "Install Python")

c. You checked for platform-specific instructions above and set the 
   the environment variable CC if needed. 

ON MOST PLATFORMS YOU MUST SET ENVIRONMENT VARIABLE CC BEFORE BUILDING

./express_install [CDAT_INSTALL_DIRECTORY] [options]
    For options see below under "Install CDAT". The express_install script
    includes --force automatically.

To install a minimal configuration supporting CDMS only:

./express_install [CDAT_INSTALL_DIRECTORY] --cdms-only [options]

You will also need to install gplot if you do not already have it; see 
step 4 below.

------ Or, doing the separate steps:

0. Did you check for platform-specific instructions above? Please do so.
   Set the environment variable CC if needed.

1. To install Python with tcl/tk:
(cd pysrc; ./install_script [CDAT_INSTALL_DIRECTORY])    (skip this step? see below)

2. To install the external software CDAT requires:
(cd exsrc; ./install_script [CDAT_INSTALL_DIRECTORY])    (infrequently changing components)

3. To install CDAT itself:
[CDAT_INSTALL_DIRECTORY]/bin/python install.py [--disable-contrib] (installs CDAT and user-contributed packages (contrib can be turned off)

------- To test:
./test_script [CDAT_INSTALL_DIRECTORY]

------- To use:
Make sure environment variable HOME set.
[CDAT_INSTALL_DIRECTORY]/bin/vcdat   # starts GUI

##############################################################################
##########################       INSTALLATION       ##########################
##############################################################################

-------------  PYSRC: Install Python (if necessary)

The "pysrc" distribution contains everything you need to make a 
tcl/tk/readline-enabled Python that is new enough to run CDAT: zlib, readline,
tcl, tk, and Python. 
The version distributed are:

Python		2.4.2
Tcl/Tk		8.4.9
readline 	4.3
zlib		1.1.4

Reasons you might build a new Python include:
    a. You do not have Python installed in a directory 
       where you have write permission.
    b. You get a message during CDAT installation saying that
       your Python is too old.
    c. You do not want CDAT installed into your existing Python.
    d. You want to avoid issues like having the right Python but the wrong Tcl.

Everything needed for Python, including Tcl and Tk, is included in this package. 
If in doubt, please compare the versions of the tar files in
pysrc/src to be sure your version numbers are as recent as ours.

Obtain the pysrce distribution and unpack it. In subdirectory pysrc:
   ./install_script [--debug] [CDAT_INSTALL_DIRECTORY]

The build takes place in subdirectory build, and you'll find logs there.

You can clean up the build directories with ./clean_script

-------------  EXSRC: Install the "external" software (if necessary)

Our "exsrc" distribution contains additional, required packages
These packages, except for Pyfort, were not written at PCMDI.  
We have separated them into their own distribution to in order to reduce 
the amount users must download and rebuild when new versions 
of CDAT are released and these parts haven't changed.

In subdirectory exsrc:
   ./install_script [--debug] [CDAT_INSTALL_DIRECTORY]

The build takes place in subdirectory build, and you'll find logs there.

You can clean up the build directories with ./clean_script

You only need to do this step once. Minor CDAT updates will not require you 
to download and build this part again. 

If you need to rebuild only some parts of it, you can enable/disable any PACKAGE by adding the 
--with-PACKAGE or --without-PACKAGE, or build a single PACKAGE by using --PACKAGE-only.

The Packages available are:
Package  Version Comments
NetCDF    3.6.0
OpenDAP   3.4.3 (either that or NetCDF, to turn off --disable-opendap)
Pyfort    8.5.3
Numeric   23.1
XGKS      2.6.1
Pmw       1.2
gplot     1989
gifsicle  1.35
pbmplus   1991 # Still distributed but not used for Linux/Mac
netpbm    10.27 # Replaces pbmplus on Linux and Mac system
gifmerge  1999
R         2.1.1  (not installed by default, you'll need to pass --enable-r)
VTK       4.2.3  (not installed by default, you'll need to pass --enable-vtk)
cmake	  1.8.3  (installed by VTK)
ioapi     3.0.2  (not installed by default, turns off openDAP, use --enable-ioapi)
gdal      1.3.0  (installed with ioapi)
proj	  4.4.9  (installed with ioapi)

----------------------------------------------------------------------------------------
-------------------------------- Installing CDAT itself --------------------------------
----------------------------------------------------------------------------------------

~~~~~~~~  Step 0 (if desired): Create a Configuration File

-- SETUP: configuration file --
CDAT installation can be controlled with a configuration file. 
The installation begins by reading the file installation/standard.py.
Details about the options you can set are detailed in that file.

You can use an alternate configuration file (say myconfig.py) by using in step 1:
--configuration=myconfig 
. 
Example of configuration file:
The file installation/pcmdi.py is an example of a configuration file, 
in this case the configuration we use at PCMDI. 
Once a configuration has been made, it will not be redone in 
subsequent installs unless you use the --force option. 

-- RESULT: cdat_info.py --
The result of the configuration process is a module cdat_info.py. This module is
installed into Python and also left for viewing in installation/cdat_info.py.

-- NOTES --
Note that in creating your own configuration file, you can use the full power of 
Python. 

The install process is also governed by a "control file". The standard control
file is installation/control.py; installation/debug.py is used for the debug 
builds. You shouldn't have to change anything in these files. 

~~~~~~~~  Step 1: Run "install" 
[CDAT_INSTALL_DIRECTORY]/bin/python install.py [options] [control-files]

In the following step you must execute the Python into which you intend to
install CDAT. Either use a full path name or make sure that the desired 
python is the one being chosen by your path. To emphasize this we'll show
the command as a full pathname below. Please read Notes below before building.

A full usage description is given in file HELP.txt. It can also be viewed with
[CDAT_INSTALL_DIRECTORY]/bin/python install.py --help. 


Standard install (now includes contrib Packages):
[CDAT_INSTALL_DIRECTORY]/bin/python install.py 

Standard without contributed packages
[CDAT_INSTALL_DIRECTORY]/bin/python install.py --disable-contrib

To install after changing the configuration, downloading a new version,
or changing platforms, use the --force option. For example:
[CDAT_INSTALL_DIRECTORY]/bin/python install.py --force

To install using your own configuration file:
[CDAT_INSTALL_DIRECTORY]/bin/python install.py --configuration=myconfig
where myconfig is your configuration file.

A list of all Packages installed will appear
If a Package fail an error message will be generated
At the end of the install, all failed Packages will be listed.

If the build has failed for some Packages, you should then examine the log 
for the piece it was working on when it failed.
For comparison the subdirectory "logs/samples" contains the log files for 
a build on Linux.  

A certain class of errors, such as a failure to locate the X11 libraries, 
can result in the build halting in an inconsistent state. Typically you will 
fix such a problem by adding a configuration or control file and rebuilding.
Be sure to use the --force option when you rebuild to insure a complete rebuild.

The set of packages to build is determined by the variable "packages."
To modify the list of packages, make a control file that modifies the variable
"packages"; use installation/pcmdi.py as a model. 

Many of the contributed packages in subdirectory contrib require a Fortran 
compiler. If the default compiler chosen by Pyfort is not what you want, you
may need to edit file configuration.py in the Pyfort source and reinstall it.
See http://pyfortran.sf.net.

------------------------------------------------------------------------------------
	Contrib Packages
------------------------------------------------------------------------------------
Bellow is the list of distributed contrib packages, documentation can be found
in the source (or online help)

asciidata
binaryio
ComparisonStatistics		1.2
cssgrid
dsgrid
eof
f2py				2.45.241_1926
grads
IaGraph				0.3.0.1
lmoments
natgrid
ort
pyclimate			1.2.1
pyIoapi				2005/09/21
ioapiTools                      2005/07/29
egenix-mx-base			2.0.6
pygmt				2004/05/03
pyncl				1.4.1
regridpack
Rpy 				0.4.6
shgrid
Scientific Python		2.4.9
SciPy				core-0.3.2
spherepack
Thermo                          1.0
trends

------------------------------------------------------------------------------------
----------------------------  Packages Specific Notes   ----------------------------
------------------------------------------------------------------------------------

...............................................
............... OpenDAP / DODS  ...............
...............................................
CDAT is automatically built with OpenDAP (DODS) support on Linux and Darwin platform,
You can provide your own binaries for the libraries.
(Make sure they've been compiled with the same compiler than you used to build CDAT)
to build with OpenDAP client support and your own libraries use the 
--with-opendap=/my_dods_dir option (we recommend to use --force option as well)

...............................................
.................... GPLOT ....................
...............................................
The GPLOT utility is required to produce postscript files and
is now distributed with the exsrc and should install 
automatically, however if it fails, follow the instructions bellow
Since it virtually never changes you may wish to install it somewhere 
in your path that is not the same as where you put cdat.

Choose an appropriate Makefile in subdirectory gplot.
Modification of the Makefile may be required for finding X11.

cd exsrc/src
gunzip gplot.tar.gz ; tar xvf gplot.tar
cd gplot
make -f Makefile.your_platform gplot

You can then install the executable "gplot" anywhere in your execution path.
For example, cp gplot [CDAT_INSTALL_DIRECTORY]/bin/gplot

...............................................
............ R Statistical Package  ...........
...............................................

The R statistical Package is extremely long to build and build smoothly only
on Linux platfrom, therefore it has been removed from the default build, but
sources are distributed
passing --with-R would try to build it.
If you already have R built on your system, and wish to only build the Rpy contrib package
simply:
make sure your LD_LIBRARY_PATH includes the path to your R distribution
then run the following build line:
[python-path]/python install.py --enable-r

...............................................
................. VTK Package  ................
...............................................

The VTK package is EXTREMELY long to build (about 45mn on some of the fastest Linux/PC)
Therefore it is not built by default, use the --enable-vtk option to build it 
(with express_install or the exsrc install).
VTK has been tested on Linux systems only.
on some system you might need to set your LD_LIBRARY_PATH to point to the CDAT
install of Tcl/Tk.

...............................................
.............. SCRIP Interpolation ............
...............................................

CDAT Version 4 includes support for the SCRIP interpolation package
developed at Los Alamos National Laboratory. SCRIP interpolates gridded
data, and can be used with the nonrectangular grids introduced in CDAT
V4. Because the package is standalone and is written in Fortran 90, it is
not built by default. Note that CDAT has a built-in regridder for
rectangular grids. If you need the richer functionality of SCRIP, the
package is included in exsrc/src. See the SCRIP user guide for installation
instructions.

------------------------------------------------------------------------------------
-------------------------------------- Testing -------------------------------------
------------------------------------------------------------------------------------

    ./test_script [-v] [CDAT_INSTALL_DIRECTORY]

will run a basic set of cdms tests and start up vcdat for testing.
If [CDAT_INSTALL_DIRECTORY] is not given, runs the python in your path. If -v is given,
does not start up vcdat. 

Note: Test 6, the xml test, often prints out differences that
are matters of form rather than substance. These occur, for example, if you 
used a different version of Python than we did. We are working to improve
this test.

------------------------------------------------------------------------------------
------------------------------------- Cleaning -------------------------------------
------------------------------------------------------------------------------------

For building again on a different system, or after downloading a new version,
or just to save disk space, run 
./clean_script all
or use the --force option on your build.


------------------------------------------------------------------------------------
--------------------------------- NOTES and REMARKS --------------------------------
------------------------------------------------------------------------------------


~~~~~~~~~~~~  HOME  ~~~~~~~~~~~
You must have your HOME environment variable set to a directory where you 
have write privleges in order for parts of CDAT to function correctly.
A subdirectory PCMDI_GRAPHICS is created in $HOME to hold some state 
between executions, and to hold certain graphical outputs.

~~~~~~~~~ Generalities ~~~~~~~~~
1. Warning messages differ from machine to machine but there will be some in 
   many of the packages, especially the ones we are including here but which 
   are written and maintained elsewhere. Do not panic. If you get to the 
   message 'Installation complete' at the end, you probably made it ok.

2. If you get missing externals that look like part of the Fortran runtime
   it may be that the the configuration for the Fortran compiler is wrong. 
   Be sure to set a Pyfort compiler id that matches the Fortran compiler 
   used for building DRS or other Fortran libraries. A basic install does not
   use Fortran so be sure you can do that first before trying to solve 
   this problem. See http://pyfortran.sf.net for details on Fortran compiler 
   ids in Pyfort.

3. If test_script fails importing cdtime, this usually indicates that the 
   libcdms build did not succeed. While the build should have exited 
   when that happens, it might not have. Check the log logs/LOG.libcdms.

4. If the CDMS libray build fails in compiling file cdunifql.c, 
   configuration variable CDMS_INCLUDE_QL must be "no". 
   This is the default except for the --PCMDI option.

~~~~~~~~~ Notes for Advanced Users ~~~~~~~~~
After your install, a file rebuild.py will appear in each package. You 
can execute python rebuild.py in a package to rebuild using the same 
installation target (that is, the same python, even if you accidentally
used the 'wrong' one to execute rebuild.py) and the same configuration. 

If you built originally using --debug, using
rebuild.py will ensure that you do so again. Rebuilds are logged into files
LOG.rebuild for stdout; stderr comes to your terminal. 

In the packages, you can 'clean' simply by removing the subdirectory
build with /bin/rm -fr build.  If present, such as in cdms, use ./clean_script.

Each package name placed in the list 'packages' can be one of the following:
   a. The name of a directory, either absolute or relative. In that directory,
      we look for a file setup.py, install_script, makefile, 
      Makefile, or MAKEFILE. The first one we find is used.
   b. The name of the file itself (absolute or relative, must be one of the 
      names listed above).

The action taken depends on the configuration variable, action. This is 
a dictionary mapping installation file names to execution lines.
If you wish to override these we suggest using your own configuration
file to do so; installation/debug.py is an example of this.