==============================================================================
README file for H5Part configure
==============================================================================

+ 0. HDF5 library
-----------------

Make sure you have a working version of the HDF5 library in your computer. If you plan
to use parallel I/O you need to use a parallel HDF5 version. If you don't have the
library download the sources from http://hdf.ncsa.uiuc.edu/HDF5/

+ 1. Quick start (If you feel lucky...)
----------------------------------------

For many platforms, where compilers are installed in the "default" location
and all the environment variables are set correctly, it should be sufficient 
to type: 

./configure [OPTIONS] && make [install]

to have the libraries and test program compiled.


==============================================================================


+ 2. configure line options
----------------------------

(1) Enable options
--enable-fortran
--enable-parallel
--enable-tools
--enable-python
--enable-64 (only for AIX and Irix)

(2) Setting compilers related variables manually
To assign environment variables (e.g., CC, CFLAGS...), specify them as
VAR=VALUE.  See below for descriptions of some of the useful variables.

Compiler environment variables:
  CC          C compiler command
  CXX         C++ compiler command
  FC          Fortran compiler command

(3) Setting prefix for installation manually
--prefix=PREFIX         install files in PREFIX


For more information, type:

./configure --help


==============================================================================


+ 3. Platform specific settings for compiling libraries & test programs
------------------------------------------------------------------------

Building
        make  : builds the libraries and test programs
	make install: builds and installs
        make clean : removes extraneous object files
        make distclean : returns configuration to unconfigured state

As tested on hosts:

(1) Davinci <davinci.nersc.gov> (Linux"SUSE"-ia64)
---------------------------------------------------
FIRST THING FIRST!! Type:

module load intel
to have the proper compilers set up for use.

module load hdf5_par

[NOTE: module load hdf5 does not work at this moment. 
Possible installation error of HDF5 on Davinci.]


Brief profile:
CC = icc
CXX = icc
FC = ifort
MPICC = icc
MPICXX = icc
MPIFC = ifort

If default doesn't work, try:

For C shell: 
env CC=icc CXX=icc FC=ifort MPICC=icc MPICXX=icc MPIFC=ifort ./configure && make install

For Korn or Bourne shell:
CC=icc CXX=icc FC=ifort MPICC=icc MPICXX=icc MPIFC=ifort ./configure && make install

And, of course, you should add configure options, such as --enable-fortran --enable-parallel.


On this host, executing:

For C shell: 
env CC=icc CXX=icc FC=ifort MPICC=icc MPICXX=icc MPIFC=ifort ./configure --enable-fortran --enable-parallel && make install

For Korn or Bourne shell:
CC=icc CXX=icc FC=ifort MPICC=icc MPICXX=icc MPIFC=ifort ./configure --enable-fortran --enable-parallel && make install

has functioned correctly.


To run test program, go to test directory:

(i) Serial test
run:
./H5testF
./H5PartTest

(ii) Parallel test
run:
mpirun 2 H5testFpar
mpirun 2 H5PartTestP

NOTE: Number 2 above is a arbitrary number that indicates the number of processes.





(2) Jacquard <jacquard.nersc.gov> (Linux"SUSE"-x86_64)
-------------------------------------------------------
Brief profile:
CC = pathcc
CXX = pathCC
FC = pathf90
MPICC = mpicc
MPICXX = mpicxx
MPIFC = mpif90



If default doesn't work, try:

For C shell: 
env CC=pathcc CXX=pathCC FC=pathf90 MPICC=mpicc MPICXX=mpicxx MPIFC=mpif90 ./configure && make install

For Korn or Bourne shell:
CC=pathcc CXX=pathCC FC=pathf90 MPICC=mpicc MPICXX=mpicxx MPIFC=mpif90 ./configure && make install

And, of course, you should add configure options, such as --enable-fortran --enable-parallel.



On this host, executing:

For C shell: 
env CC=pathcc CXX=pathCC FC=pathf90 MPICC=mpicc MPICXX=mpicxx MPIFC=mpif90 ./configure --enable-fortran --enable-parallel && make install

For Korn or Bourne shell:
CC=pathcc CXX=pathCC FC=pathf90 MPICC=mpicc MPICXX=mpicxx MPIFC=mpif90 ./configure --enable-fortran --enable-parallel && make install

has functioned correctly.



To run test program, go to test directory:

(i) Serial test
run:
./H5testF
./H5PartTest

(ii) Parallel test
In Jacquard, we need a script to run parallel programs, since Jacquard does not support interactive parallel processing. Instead, we need to submit the task to a queue. A sample script (run_H5testFpar.scr) may look like below:

+++++++++++++++++++++++++++++++++++++++
#!/bin/csh
#PBS -l nodes=1:ppn=2,walltime=00:05:00
#PBS -N  H5testFpar
#PBS -o H5testFpar.out
#PBS -e H5testFpar.err
#PBS -q debug
#PBS -A mpccc
#PBS -V

setenv PBS_OWORKDIR /home/H5Part/test

cd $PBS_O_WORKDIR
mpirun -np 2 ./H5testFpar
+++++++++++++++++++++++++++++++++++++++

Then, we need to submit the task to a queue by running:

qsub run_H5testFpar.scr

After processed, the result will appear in H5testFpar.out, and error messages will appear in H5testFpar.err.





(3) Bassi <bassi.nersc.ogv> (AIX5.3.0.0-Power 3)
-------------------------------------------------
FIRST THING FIRST!! Type:

module load gcc

to have the proper compilers set up for use.

Brief profile:
CC = cc_r
CXX = cc_r
FC = xlf_r
MPICC = mpcc_r
MPICXX = mpcc_r
MPIFC = mpxlf_r



If default doesn't work, try:

For C shell: 
env CC=cc_r CXX=cc_r FC=xlf_r MPICC=mpcc_r MPICXX=mpcc_r MPIFC=mpxlf_r ./configure && make install

For Korn or Bourne shell:
CC=cc_r CXX=cc_r FC=xlf_r MPICC=mpcc_r MPICXX=mpcc_r MPIFC=mpxlf_r ./configure && make install

And, of course, you should add configure options, such as --enable-fortran --enable-parallel.



On this host, executing:

For C shell: 
env CC=cc_r CXX=cc_r FC=xlf_r MPICC=mpcc_r MPICXX=mpcc_r MPIFC=mpxlf_r ./configure --enable-fortran --enable-parallel && make install

For Korn or Bourne shell:
CC=cc_r CXX=cc_r FC=xlf_r MPICC=mpcc_r MPICXX=mpcc_r MPIFC=mpxlf_r ./configure --enable-fortran --enable-parallel && make install

has functioned correctly.



To run test program, go to test directory:

(i) Serial test
run:
./H5testF
./H5PartTest

(ii) Parallel test
run:
unsetenv MP_SINGLE_THREAD
poe ./H5PartTestP -procs 2 -nodes 1
poe ./H5testFpar -procs 2 -nodes 1

For more details on how to run parallel programs on Bassi, go to:

http://www.nersc.gov/nusers/resources/bassi/running_jobs/





(4) Starsky <starsky.lbl.gov> (Darwin8.5.0-PowerPC)
----------------------------------------------------
FIRST THING FIRST!! Set environment variables: (in tcsh)

setenv LD_LIBRARY_PATH /usr/local/g95/lib/gcc-lib/powerpc-apple-darwin8.5.0/4.0.3/
setenv PATH ${PATH}:/usr/local/g95/bin

NOTE: This environment variable setting is specifit to Starsky. It is to make configure find the fortran compiler.

Brief profile:
CC = gcc
CXX = g++
FC = g95



If default doesn't work, try:

For C shell: 
env CC=gcc CXX=g++ FC=g95 ./configure && make install

For Korn or Bourne shell:
CC=gcc CXX=g++ FC=g95 ./configure && make install

And, of course, you should add configure options, such as --enable-fortran --enable-parallel.



On this host, executing:

For C shell: 
env CC=gcc CXX=g++ FC=g95 ./configure --enable-fortran && make install

For Korn or Bourne shell:
CC=gcc CXX=g++ FC=g95 ./configure --enable-fortran && make install

has functioned correctly.



To run test program, go to test directory:

(i) Serial test
run:
./H5testF
./H5PartTest





(5) Linux AMD64 Visualization group workstations (Linux"SUSE"-x86_64)
---------------------------------------------------------
Brief profile:
CC = gcc
CXX = g++
FC = g95



If default doesn't work, try:

For C shell: 
env CC=gcc CXX=g++ FC=g95 ./configure && make install

For Korn or Bourne shell:
CC=gcc CXX=g++ FC=g95 ./configure && make install

And, of course, you should add configure options, such as --enable-fortran --enable-parallel.



On this host, executing:

For C shell: 
env CC=gcc CXX=g++ FC=g95 ./configure --enable-fortran && make install

For Korn or Bourne shell:
CC=gcc CXX=g++ FC=g95 ./configure --enable-fortran && make install

has functioned correctly.



To run test program, go to test directory:

(i) Serial test
run:
./H5testF
./H5PartTest





==============================================================================


+ 4. Trouble shooting (Things to check for...)
--------------------------------------------
(0) Have you set the LD_LIBRARY_PATH?
---Some systems require the user to manually set the environment variable, LD_LIBRARY_PATH. To do so:

set the environment variable HDF5ROOT or PHDF5ROOT to point to your installation of HDF5 (serial and/or parallel respectively).

For Korn or Bourne shell:
	LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${HDF5ROOT}/lib;export LD_LIBRARY_PATH
	LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:{PHDF5ROOT}/lib;export LD_LIBRARY_PATH

For C shell:
	setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${HDF5ROOT}/lib
	setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${PHDF5ROOT}/lib

Note that the values of HDF5ROOT & PHDF5ROOT will be in the "summary" section when you run configure.

Not properly set LD_LIBRARY_PATH value may result in a runtime error:

./H5PartTest: error while loading shared libraries: libhdf5.so.0: cannot open shared object file: No such file or directory

(1) Are the compilers set correctly? 
---Check with: which COMPILER

(2) Have you installed HDF5?
---You can get it at: http://vis.lbl.gov/Research/AcceleratorSAPP/index.html

(3) Have you loaded the proper modules? 
---It is necessary in Davinci & Bassi, and configure && make install may not work without it.