Phred - Phred is a parallel finite difference time domain
	electromagnetics simulator.



  Copyright (C) 2004 Matt Hughes

  Phred is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Comments are welcome.

	- Matt Hughes <mhughe@uvic.ca>

COMPILERS:

* GCC 3.3.3 is known to work well. Other versions also work fine. 


* ICC 8.1
Getting Intel's compiler to work takes a little effort. If everything
is installed and your environment variables are set, you just have to
tell your mpic++ script to use it. For LAM, do this:

export LAMHCP=/opt/intel_cc_80/bin/icpc
export GXX_INCLUDE=/usr/include/c++/3.3

You have to use icpc rather than icc because otherwise the final link
step will not be able to find the Intel C++ symbols. 

If you want to try vectorizing the code, add the -restrict and
-vec_report. Use -vec_report5 for more information about what can and
can't be vectorized and why. 

On the Westgrid Glacier cluster, phred has to be compiled using MPICH
and the Intel compiler. In order to do this, follow these steps: 

1) source /global/software/intel/cc-8.0/bin/iccvars.sh
2) export CXX=/global/software/mpich-1.2.5.2/ssh/bin/mpiCC
3) export CC=/global/software/mpich-1.2.5.2/ssh/bin/mpiCC
4) export PATH=/global/software/mpich-1.2.5.2/ssh/bin/:$PATH
5) ../Phred-0.1.3/configure --enable-openmp

If netCDF, Python, and Boost.Python are installed in non-standard
locations, then it is probably also necessary to set the CPPFLAGS and
LDFLAGS vairables. On Glacier, I've set mine to:

LDFLAGS="-L/global/home/mch/opt/netCDF/lib -L/global/home/mch/opt/boost/lib -L/global/home/mch/opt/python2.4/lib -Wl,-rpath,/global/home/mch/opt/python2.4/lib -Wl,-rpath,/global/home/mch/opt/netCDF/lib -Wl,-rpath,/global/home/mch/opt/boost/lib"

CPPFLAGS="-I/global/home/mch/opt/netCDF/include -I/global/home/mch/opt/boost/include -I/global/home/mch/opt/python2.4/include"

I need to fix the configure script so that the paths to the files can
be specified as configure options.


* VisualAge 6 for AIX

Aix xlC_r optimize flags (from Blitz++):
-O3 -qstrict -Q -qansialias -qhot

-Q turns on inlining
-qstrict turns off optimizations that might alter program semantics 
-qhot turns on high order transformations; pad arrays etc to avoid
      cache misses, use vector library routines where possible
-qhot=vector does as above, plus it can replace code with calls to
             vector library routines
-qansialias Use type-based aliasing during optimization
-qalias=allp Tells the compiler that pointer are never aliased
-qassert=allp Tells the compiler that pointer are never aliased


Hmmm, array padding: -qhot=arraypad


* MIPSPro 7.3.1.1m on IRIX

See README.IRIX

Had to run configure like this: 
CPPFLAGS="-I/opt/boost/include/boost-1_31/boost/compatibility/cpp_c_headers/ -I/opt/boost/include/boost-1_31/" ../phred/configure --with-cxx=CC --enable-openmp

Newer versions of CC may not require the use of the boost
compatibility headers. YMMV. 


* Compaq C++ on HPUX
No successful compile yet, due to template problems. 

http://h30097.www3.hp.com/cplus/ugu.htm

CPPFLAGS="-I/opt/boost/include/boost-1_31/" CXXFLAGS="-D__USE_STD_IOSTREAM" ../Phred-0.1.0/configure --with-cxx=cxx


* NEC C++ for SuperUX on a SX-6
Python is tempermental about compilers... it's tricky to get it to use
the cross compiler. This compiler seems to work. 


USING PYTHON:

Python is a very powerful feature of Phred. Although Phred can be
used without Python, it is a very useful thing to compile in. Python
is known to work on Linux, Mac OS X, and AIX. If you install
Python yourself, be sure to 'make libinstall' and 'make
libpython2.3.so'. 'make altinstall' seems to be the only target that
actually installs the shared library in $PREFIX/lib. 

On some systems, it is necessary to install a Python which does not
use threads. 

Phred uses Boost.Python (http://boost.org/) to bring the C++ and
Python languages together. Boost.Python is a sophisticated library
that depends on a number of modern C++ compiler features, so make
sure things are up to date. One thing about boost is that it is
somewhat of a pain to install, partly due to the use of their own
build tool, bjam. If you are compiling from source (download from
boost.org), you may need to compile bjam before you can start. 

cd boost/tools/build/jam_src/
./build.sh
cp bin.XXX SOME_BIN_DIR
cd ../../..
bjam -sTOOLS=gcc --layout=system --prefix=/opt/boost_OR_SOMETHING install

On Minerva (an RS/6000 SP), I could not compile python because the
compiler version we have has a bug related to partial template
specialization which the Boost.Python glue library relies on. Recent
versions of Visual Age C++ should have fixed this, but the Minerva
admins are understandably reluctant to change things outside of their
normal upgrade cycle, so I'm stuck with a buggy version and cannot
test it. 


LICENCES:
This program optionally depends on a number of other software
packages which are available under a variety of licences. This affects
what licences phred may be made availble under, which is currently
only the GPL, but it could be made availble under other licences by
request. These are:

netCDF (data file output), unknown

HDF (data file output), unknown

LAM/MPI (Message passing), under a special license which is probably
GPL compatible. 

MPICH (Message passing), under a special license which is probably
GPL compatible. 

Python 2.3, Python license, GPL compatible

readline, GPL

Boost, Boost licence, GPL compatible



DOCUMENTATION:
Documentation can be generated using Doxygen. If you want to generate
the latex docs, you need to have a very complete installation of
latex. I use tetex and on Debain the tetex-extras package was
required. The autoconf macros that check for Doxygen do not check for
all of the required LaTeX packages. 




Computing the number of lines of code:
find . -name "*.cc" -or -name "*.hh" -exec wc -l "{}" ";" | gawk '{nlines = nlines + $1} END {print nlines}'