Inland Project's README file.

Package Overview
================
 Terrestrial ecosystems play a critical role in human activities. The availability 
of food, fibers and fresh water depends on such ecosystems. Even the regulation of 
climate is affected by large scale changes in vegetation.

 In order to represent the terrestrial processes, focusing ecosystems in Brazil 
and other parts of South America, a cooperative team of researchers of the 
Atmosphere-Biosphere Interaction group, from Federal University of Viçosa (UFV) 
(http://madeira.dea.ufv.br/) and Centre of Earth System Science (CCST/INPE) 
(http://ccst.inpe.br), is developing the Inland/IBIS.

 Inland was based on the IBIS from SAGE center from the University of Wisconsin
-Madison (http://www.sage.wisc.edu/download/IBIS/ibis.html) and on CCM3 and CCSM3
IBIS versions.

For more information please contact:
Dr. Marcos Heil Costa - [email protected]
Dr. Gilvan Sampaio de Oliveira - [email protected]
and the Inland R&D team - [email protected]

Installation Notes
==================
 There are some specifics for installing this package on your system. The first
requirement for the offline version is having NetCDF libraries installed on your
system. Major distributions like Ubuntu, Gentoo, RHEL, CentOS, Fedora and
possibly others already come with binary distributions of this library, install-
ed via apt-get, emerge, yum or whatever package manager the distribution has.

 If you are not using GNU compiler suite to make your model run, you should
specify the compiler you are trying to use in the ./configure stage, or else the
default choice, GNU, will be used. To specify a different compiler, as our 
project is all fortran language based, you should issue (assuming you want to 
use the intel compiler suite):
FC=ifort ./configure

 Supported compilers as of yet are GNU, Intel and PGI. Other compiler suites may
be tried but at your own risk. The --enable-compiler-optimizations configure
flag only applies to compilers supported by us. We will detail custom options 
below.

 In order to facilitate resolution of custom library installs or tune up a model
run to better use the resources of the running machine, we have defined several
configure options, that you should use or not depending on your judgement. In
general, making the program run faster with aggressiver compiler optimizations
tend to change the result slightly.

Configure flags
---------------

--enable find_searches
 The configure script will search for candidates to be the NetCDF library using
the 'find' command. It will be slower but, if you don't have slocate installed,
know you have an installation of NetCDF somewhere on your machine but just don't
know where it is, this option can save your day. The configure script tries
different manners to link against the NetCDF library, so if you have any NetCDF
library compatible with your compiler installed on your computer, it will be
found. Please notice that, if you compiled NetCDF for GNU (or installed the
precompiled version for your distro), it will probably not work for PGI or Intel
compilers, and vice-versa, and you will have to build NetCDF by yourself and
either use this option to locate the library or specify the path to NetCDF as
described below.

--enable-compiler-optimizations
 For each compiler we support, we build up some aggressive compilation options
to decrease the run time of a long run. This feature is experimental an may re-
sult on a wrong model output due to numeric and rounding errors. In general,
this option implies -O3 or more, multi-source file optimizations, loop unrolling
and indexing, and non IEEE-compliant math operations. Also, as the optimization
level increases, there is a likeliness to have longer compilation time as the 
price for a better software performance.

--disable-intel-heap-arrays
 If you enabled the above compiler optimizations option for an intel compiler
there is a bug where the compiled program tries to load anything into stack no
matter what. As this model uses a lot of memory, you get an stack overflow. To
circumvent this problem, the configure script tries to guess your max stack size
and specifies that the Intel compiler uses up to the maximum stack size to 
allocate variables and, beyond that size, allocate variables to the Heap, with
lots more space. If you specify this option, this calculation will not be made
and the resulting program will try to allocate all resources on the stack. This
will work fine for regional runs, but if you are doing a big region or global
run, it will most likely crash your program. This option is left for the case
your version of the intel compiler does not support this option and will affect
only compiling the package using the Intel compiler suite.

--with-netcdf=<path_to_netcdf>
 If you have made a custom NetCDF build, don't have the slocate tool (or its
database should be outdated) and don't want the configure script to search the
NetCDF library for you, you may specify the full path to the NetCDF library (do
not include the `/lib' or `/include' to the path as it will be appended automa-
tically). You have to specify the same path you specified in --prefix during the
NetCDF library build. If you didn't, it will probably be in /usr/local and you 
would not need to specify this option anyway.

--with-hdf5
 If you are compiling and willing to link against a NetCDF4-enabled NetCDF lib-
rary, you will need the HDF5 library to be located as well. If you have a custom
HDF5 lib build, then this is the option to specify the path for the custom ins-
tall.

--with-curl
 As --with-hdf5, you should need to specify a custom path installation for the
curl library should you have compiled it by yourself and installed somewhere
else. libcurl is needed if you specify

--disable-openmp
 By default openmp is enabled, use this flag to disable (e.g. if only using the
single point model).  The OMP_NUM_THREADS environment variable controls the number 
of threads used by openmp, the default (if not set) is the number of cores on the 
system. As of October/2012 the default value is 2, due to performance limitations 
in the openmp code in the model.

make notes
----------
 Instead of installing the model on the local path or $PREFIX, you might want to
just have the model running on the directory you compiled it, so you just run it
after a successful compile. If this is the case, instead of running 
make install

 You can run just
make dev-symlinks

 This will make symlinks for the binary, default configuration and parameter
files' directories, and will make a link to the input data symlink, all to the
root package's directory.
 As the binary will be a symlink to the actual binary in the sources directory,
all you need to run a new version once you changed a source file, is `make' and
it will be ready to go.
 The output files for a run are cleared on a `make clean' and the symlinks are
removed once you `make distclean'.

 If you have several cores/threads on your machine (shared memory environment 
only), you may take advantage of a GNU make's feature that splits the compile
process between the specified number of threads. If you have a Core i7 with
four cores and HT technology (8 logical CPUs total), you may run make to build
the package with the -j9 option. In general, it is a good idea to use the number
of logical CPUs +1 to build a package. You may want to use less threads if you
already have some processes using 100% of one or more logical CPUs.
 In the example abofe of a core i7 with a total of 8 logical CPUs, you would
issue:
make -j9
 or
make -j9 all

 To build the package.

Using a CRAY supercomputer
--------------------------
Fore details on building and using the model in a CRAY supercomputer, see the 
docs/README.cray document.

Runtime config and parameter files information
==============================================
 A sample version of the configuration file and parameters are installed into
$PREFIX/share/doc/$PACKAGE under the `conf' and `params' directories, resp.
 In order to run the model you have to have the `conf', `params' and `input'
directories on your current directory. I.e., you don't need the binary on the 
current directory, only the data files.
Alternatively, by setting the INLAND_INDIR env. variable (should be set to 
$PREFIX/share/inland) you can run the model from any directory. Likewise you can 
override the location of the inland-grid.infile with the INLAND_INFILE env. 
variable.  The climate input files must be located in 
$PREFIX/share/inland/offline/{grid,single_point}/data/ or in a directory 
specified by the INLAND_DATADIR env. variable.
Output files are created in the current directory, unless the env. variable
INLAND_OUTDIR is defined.

Input data files
================
 Due to the large size, we DO NOT provide sample input data in the package file.
Instead, we do provide a different package, called inland-data-<revision>.tar.gz
with the data files, while revision is the data files' revision, not the model.
 Any version of the model should work with the sample data files.
 By default, this package has symlinks to $PACKAGE_ROOT/../inland-data/input so
all you need to do to have the input data dir in place is untar it into the same
directory you untar'ed this package file.