Installing and running LPJmL C Version 3.4.018

Installation for Unix-like systems

This text describes how to install and run LPJmL on your system. The code has been tested for AIX, Linux, Mac OS X, and Windows with cygwin and Microsoft C compiler (sequential version without MPI). Cygwin is a Linux-like environment for Windows (http://www.cygwin.com) On Mac OS the xcode suite must be installed in order to have the gcc compiler.

create lpj directory:

mkdir lpjml

Go to lpj directory:

cd lpjml

untar source and data files

gzip -cd lpjml-3.4.018.tar.gz|tar -xf -
gzip -cd cru.tar.gz|tar -xf -

Directory tree after extracting the tar files:

--lpjml
  |
  +-config      : OS- and compiler-specific Makefiles
  |
  +-bin         : Directory for executables and shell scripts
  |
  +-loadl       : Loadleveler job control files
  |
  +-man         : Manual pages root directory
  | |
  | +-man1      : Manual pages for programs and scripts
  | |
  | +-man3      : Manual pages for functions
  | |
  | +-man5      : Manual pages for file formats
  |
  +--html       : Documentation and man page in HTML format
  |
  +--doc        : Documentation
  |
  +--par        : Parameter files for PFTs and soils
  |
  +--input      : input data set for climate
  |
  +--output     : output data (created by make test)
  |
  +--restart    : restart data (created by make test)
  |
  +--lib        : library files (created by make)
  |
  +--include    : include files
  |
  +--src        : source tree
     |
     +--numeric : source for numerical routines
     |
     +--tools   : source for tools
     |
     +--pnet   :  source for library for distributed networks
     |
     +--climate : climate code 
     |
     +--lpj     : lpj functions
     |
     +--soil    : soil code
     |
     +--grass   : grass PFT code
     |
     +--tree    : tree PFT code
     |
     +--crop    : crop PFT code
     |
     +--landuse : land use code
     |
     +--socket  : socket communication library
     |
     +--utils   : utility programs

Configure for your operating system

% ./configure.sh
Configuring LPJmL 3.4.018...
Operating system is Linux
Intel MPI found
Create executables with make all
Put . $PWD/bin/lpj_paths.sh in your $HOME/.profile

The configure script creates scripts lpj_paths.sh/lpj_paths.csh for the bash/csh shell that sets all necessary environment variables. They are set by invoking

. bin/lpj_paths.sh

from the LPJmL root directory. It is recommended to put this statement into your ~./.profile. If configure script exits with message "Unsupported operating system", Makefile.$osname is created from Makefile.gcc and probably has to be modified for your operating system/compiler. If the configure script finds a MPI environment a parallel version of lpjml is built. This is done by checking for mpicc/mpiicc in the search path for commands. The configure script creates a copy of the following OS-specific makefiles from directory config:

Makefile Description

Makefile.aix IBM AIX settings (xlc compiler)

Makefile.aix_mpi IBM AIX and MPI environment

Makefile.gcc GNU C-compiler settings

Makefile.intel Intel C-compiler settings

Makefile.intel_mpi Intel C-compiler and Intel MPI settings

Makefile.mpich GNU C-Compiler and MPI Chameleon settings

Makefile.win32 Windows settings (used by configure.bat)

Makefile	Description
`Makefile.aix`	IBM AIX settings (xlc compiler)
`Makefile.aix_mpi`	IBM AIX and MPI environment
`Makefile.gcc`	GNU C-compiler settings
`Makefile.intel`	Intel C-compiler settings
`Makefile.intel_mpi`	Intel C-compiler and Intel MPI settings
`Makefile.mpich`	GNU C-Compiler and MPI Chameleon settings
`Makefile.win32`	Windows settings (used by `configure.bat`)

Compilation flags

Compilation of lpjml is customized by definition of macros in the LPJFLAGS section of Makefile.inc:

LPJFLAGS= -Dflag1 ...

Flag	Description
DEBUG	diagnostic output is generated for debugging purposes
LINEAR_DECAY	use linearized functions for litter decay
SAFE	code is compiled with additional checks
USE_MPI	compile parallel version of LPJmL
USE_RAND48	use `drand48()` random number generator
WITH_FPE	floating point exceptions are enabled for debugging purposes

Create executables:

make

One executable in directory bin is created:

lpjml - LPJmL simulation code

Utility programs are compiled by

make utils

The following programs are created in the bin directory:

Program	Description
`lpjliveview`	Live view on screen of simulation output. lpjml must be started with '-output socket=hostname' option.
`cft2clm`	convert binary land use data files to clm data files for LPJmL
`lpjcat`	concatenates LPJmL restart files.
`lpjcheck`	checks syntax of LPJmL configuration files.
`cru2clm`	converts CRU data into file format suitable for LPJmL.
`printheader`	prints file header of LPJmL input data files.
`lpjprint`	prints content of restart file to stdout.
`lpjshuffle`	shuffles input data randomly to improve efficiency of parallel code. River routing must be disabled.
`txt2clm`	converts CRU data files into LPJmL climate data files. CRU data files have to be in the format specified here.

An installation directory can be defined during configuration:

./configure.sh -prefix /data/bios/lpjml-3.4.018

Then the binaries can be copied in the installation directory by invoking

make install

The necessary parameter and include files will be copied, too. Create output and restart directory:

make test

On the compute cluster at PIK it is better to create symbolic links of the input, output, and restart directory to the parallel GPFS filesystem /scratch. This improves performance in particular for the parallel code.

% mkdir -p /scratch/02/$USER/lpj/input
% gzip -cd cru.tar.gz|tar -xf - -C /scratch/02/$USER/lpj
% mkdir -p /scratch/02/$USER/lpj/restart
% mkdir -p /scratch/02/$USER/lpj/output
% ln -sf /scratch/02/$USER/lpj/input input
% ln -sf /scratch/02/$USER/lpj/restart restart
% ln -sf /scratch/02/$USER/lpj/output output

Man pages

Manual pages for the man command are located in the $LPJROOT/man directory. The MANPAPTH variable is set by the lpj_paths.sh script. HTML versions of the manual pages are located here. Invoking

apropos lpj

yields list of man pages related to LPJmL.

Running the program

Sequential version can be started by invoking:

./bin/lpjml

By default the configuration file lpjml.conf is read. The contents of this file can be viewed here. If you run lpjml outside the root directory of LPJmL, the following environment variable should be set (done by lpj_paths.sh):

export LPJROOT=$HOME/lpjml

Then all includes are found.

Environment variables

The following environment variables are used by LPJmL:

Environment variable	Description
LPJCONFIG	default LPJmL configuration filename
LPJPREP	defines preprocessor command for LPJmL configuration file, default is `cpp -P`
LPJROOT	defines the root directory for LPJmL. This directory is added to the include directories of the preprocessor. Is usually set by `lpj_paths.sh`.
LPJINPATH	Path append to the input filenames. Only done for filenames without absolute path.
LPJRESTARTPATH	Path append to the restart filenames. Only done for filenames without absolute path.
LPJOPTIONS	preprocessor runtime options for LPJmL
LPJOUTPATH	Path appended to the output filenames. Only done for filenames without absolute path.
LPOUTPUT	Default method for generating output files. Valid values are write, mpi2, buffer, gather, and socket. Method mpi2, buffer and gather are used by the MPI version only.

Runtime options of LPJmL

A list of runtime options defined can be obtained by calling lpjml -h:

% lpjml -h
lpjml C Version 3.4.018 (Dec  1 2008) - Dynamic global vegetation model with managed land
Usage: lpjml [-h] [-v] [-fpe] [-output {gather|mpi2|buffer|socket=hostname[:port]}] [-outpath dir] [-inpath dir] [-restartpath dir] [[-Dmacro[=value]] [-Idir] ...] [filename]
Arguments:
-h               print this help text
-v               print version, compiler and compile flags
-fpe             enable floating point exceptions
-output method   output method. Must be gather, mpi2, buffer, socket. Default is gather.
-outpath dir     directory appended to output filenames
-inpath dir      directory appended to input filenames
-restartpath dir directory appended to restart filename
-Dmacro[=value]  define macro for preprocessor of configuration file
-Idir            directory to search for include files
filename         configuration filename. Default is 'lpjml.conf'

The shell script lpjdistribute can be used to create *.conf files in order to divide the simulation into pieces for the sequential version:

lpjdistribute <number of pieces> [<number of grid cells>]

For the parallel version LoadLeveler files for Linux and AIX are provided. A job can be submitted by invoking the lpjsubmit script:

lpjsubmit ntasks LPJmL_args...

Templates for customized LoadLeveler job control files are in the loadl directory:

Script	Description
`lpjml_aix.jcf`	for AIX with POE
`lpjml_intel.jcf`	for Linux with Intel MPI
`lpjml_mpich.jcf`	for Linux with MPICH

Depending on your MPI version installed the program can be started interactively:

mpirun -np 32 $LPJROOT/bin/lpjml

Displaying output during simulation

A socket connection from LPJmL to a remote displaying program can be setup by the '-output socket' option. Program lpjliveview is a simple viewer for LPJmL output data. It must be started at first on the local machine pcxx:

pcxx% lpjliveview -DFROM_RESTART lpjml.conf mnpp

Then the LPJmL can be started on the compute cluster:

login01a% lpjsubmit 64 -DFROM_RESTART -output socket=pcxx lpjml.conf

After the job is started a window will appear on host pcxx showing global maps of monthly NPP. Output data is additionally stored in files specified in the LPJmL configuration file.

Error codes

If lpjml fails an error message is displayed in the following format

ERRORxxx: message

where xxx is the error code returned. The following error codes are defined:

Error code	Description	Error type
1	Error reading configuration	External
2	Error initializing climate	External
3	Error initializing land use	External
4	Error initializing water use	External
5	Error initializing grid	External
6	Error initializing drainage	External
7	Invalid carbon balance	Internal
8	Invalid water balance	Internal
9	Negative discharge	Internal
10	Negative fire probability	Internal
11	Negative soil moisture	Internal
12	Error allocating memory	External
13	Negative stand fraction	Internal
14	Stand fraction sum error	Internal
15	List is empty in `dellistitem`	Internal
16	Index out of range in `dellistitem`	Internal
17	Error in `newlanduse`	External
18	Invalid year in `getco2`	External
19	Crop fraction >1	Internal
20	No natural stand for deforest	Internal
21	Wrong cultivation type	Internal
22	Floating point error	Internal
23	Cannot allocate buffer memory	External
24	PFT list is not empty in `setaside`	Internal
25	Negative establishment rate	Internal
26	Output channel is broken in socket connection	External

External errors are caused by invalid or missing input files while internal errors are caused by problems inside the LPJmL code. The latter will cause a core dump and have to be fixed by program changes. Some errors will only be generated if -DSAFE is set in the compile options of Makefile.inc. The options set at compile time can be obtained by invoking

% lpjml -v
lpjml C Version 3.4.018 (Nov 26 2008)
Operating system: Linux, little endian
Compiler:         Intel C version 10.00, 64 bit
Compile flags:    "-DUSE_RAND48 -DUSE_MPI -DSAFE -DWITH_FPE"

It is recommended to compile the code without optimization and inlining making the inspection of the core file easier. Configuring in $LPJROOT with

configure.sh -debug
make clean
make

will do the job. If no core file is generated set the user limit for core files:

% ulimit -c
0
% ulimit -c unlimited

Then the core can be analysed with the gdb debugger:

gdb $LPJROOT/bin/lpjml core

or by invoking the backtrace script:

backtrace

Installation for Windows XP without cygwin

The code without MPI has been tested on Windows XP using the free Microsoft C++ compiler and nmake. The Microsoft SDK has to be installed, too. Download the Microsoft Visual C++ Studio 2005 and SDK from the Microsoft download center http://msdn.microsoft.com/vstudio/express/visualc/.

Building inside the windows shell

The necessary environment variables have to be set for the VC compiler:

"c:\program files\microsoft visual studio 8\vc\vcvarsall"

Unzip the source and data files

configure makefile:

configure

If the compiler does not find the system libraries, the library path defined in Makefile.inc has to be modified.

create lpjml executable:

nmake

LPJROOT and PATH can be set by

bin\lpj_paths

Building with Visual C++ 2005

Start a new project from existing code, which starts a project wizzard:

What type of project: Visual C++
general properties

name your project
enter file location
check "add files to project from these folders"
check "add subfolders"
check "show all files in Solution Explorer"

project type

check "Use Visual Studio"
project type: "console application project"

click finish, the rest can be specified later

After the project has been created, you need to exclude all .c files from the project that are not essential to the code. This can be done in the Solution Explorer (upper left hand corner). Exclude all files from the project that are not LPJ-essential (right click -> exclude from project). This comprises all files inc src/utils and src/graphics

Finally, you need to specify the project properties. For this, right-click on the project in the Solution Explorer.

configuration properties:

General:

character set -> use Multi-Byte Character Set
IMPORTANT: if you want to run the executable also on other computers you need to statically link the libraries to the exe file. For this, choose "Use MFC in static library" for the "Use of MFC" option. Otherwise, this can remain with the "Use Standard Windows Libraries"

Debugging:

Command arguments ->(optionally -DISRANDOM ) lpjml.conf
here, you can specify your working directory

C/C++

General:

Additional include directories: add the %LPJROOT%\include directory here
Debug Information Format: C7 Compatible (/Z7)

Optimization

full (or whatever you want)

Proprocessor

preprocessor definitions: basically, here all compiler Flags from the src/Makefile can be specified, but without the "-D" prefix.

Essential preprocessor definitions are: WIN32; _DEBUG; _CONSOLE; SAFE; _USE_MATH_DEFINES; _CRT_SECURE_NO_DEPRECATE;
optional: WITH_FPE, DEBUG

Code Generation

Enable Minimal Rebuild -> No
Basic Runtime Checks -> Default

Advanced

compile as -> compile as C code (/TC)

Linker

General

Additional Library Directories -> <SDK root dir>/Lib (e.g. C:\Program Files\Microsoft Platform SDK for Windows XP SP2\Lib)
Adiitional dependency on library advap32.dll and ws2_32.lib

Done. Now right-click on the project in the Solution Explorer and select rebuild or build. To run LPJmL from the command line, you can start the Visual C++ 2005 Express Console and start LPJmL as usual from there (e.g. lpjml.exe -DISRANDOM lpjml.conf)

Last change: 27 Nov 2008 by Werner von Bloh, PIK Potsdam