Commit 707b3540 authored by Christoph Mueller's avatar Christoph Mueller
Browse files

Initial commit of LPJmL4.0.001 as published in Schaphoff et al. 2017

Authors of LPJmL C-version
Werner von Bloh (
Sibyll Schaphoff (
Stefanie Rost (Jachner) (
Marlies Gumpenberger (
Tim Beringer (Erbrecht) (
Christoph Mueller (
Hester Biemans (
Jens Heinke (
Ursula Heyder (
Kirsten Thonicke (
Katharina Waha (
Susanne Rolinski (
Matthias Forkel (
Jonas Jaegermeyr (
Elke Stehfest (
Liesbeth de Waal (
Based on Fortran/C++ version
Stephen Sitch (
Ben Smith (
Dieter Gerten (
Alberte Bondeau (
Copyright (C) 2007-2017 Potsdam Institute for Climate Impact Research
_ ____ _ _
| | | _ \ | |_ __ ___ | |
| | | |_) | | | '_ ` _ \| |
| |___| __/ |_| | | | | | | |___
|_____|_| \___/|_| |_| |_|_____| Version 4.0.001
Installation of LPJmL C Version 4.0.001
Installation for Unix-like systems
This text describes how to install 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 (
On Mac OS the xcode suite must be installed in order to have the gcc
create LPJmL directory:
mkdir lpjml
Go to LPJmL directory:
cd lpjml
untar source and data files
gzip -cd lpjml-4.0.001.tar.gz|tar -xf -
gzip -cd cru.tar.gz|tar -xf -
Directory tree after extracting the tar files:
+-config : OS- and compiler-specific Makefiles
+-bin : Directory for executables and shell scripts
+-R : Scripts for R statistical package
+-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 pages 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
+--spitfire : spitfire fire code
+--reservoir : reservoir code
+--socket : socket communication library
+--image : coupler to IMAGE model
+--netcdf : NetCDF output functions
+--utils : utility programs
Configure for your operating system
On the HLRS2015 cluster at PIK you have to set several modules for compilation and linking:
module load gmp/4.3.2
module load mpi/intel/5.1.1
module load compiler/intel/15.0.3
module load compiler/gnu/4.9.2
module load netcdf-c/ udunits/2.2.19 expat/2.1.0
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.
The configure script creates a copy of the following OS-specific makefiles from
directory config:
Makefile.aix - IBM AIX settings (xlc compiler)
Makefile.aix_mpi - IBM AIX and MPI environment
Makefile.gcc - GNU C-compiler settings
Makefile.darwin_gcc - GNU C-compiler settings for MacOS X - Intel C-compiler settings
Makefile.intel_mpi - Intel C-compiler and Intel MPI settings
Makefile.cluster2015 - Intel C-compiler and Intel MPI on HLRS2015 cluster at PIK
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
LPJFLAGS= -Dflag1 ...
Flag Description
------------------- ------------------------------------------------------------
COUPLING_WITH_FMS enable coupling to FMS
DAILY_ESTABLISHMENT Enable daily establishment
DEBUG diagnostic output is generated for debugging purposes
DOUBLE_HARVEST adding correct sequencing of harvest events
IMAGE include coupler to IMAGE model
LINEAR_DECAY use linearized functions for litter decay
MICRO_HEATING Enable microbial heating
SAFE code is compiled with additional checks
STORECLIMATE store climate data in memory for spin up phase
USE_MPI compile parallel version of LPJmL
USE_NETCDF enable NetCDF input/output
USE_NETCDF4 enable NetCDF version 4 input/output
USE_RAND48 use drand48() random number generator
USE_UDUNITS enable unit conversion in NetCDF files
WITH_FPE floating point exceptions are enabled for debugging purposes
------------------- ------------------------------------------------------------
Create executables:
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:
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.
txt2clm - converts CRU data files into LPJmL climate data files.
CRU data files have to be in the format specified in
The binaries can be copied in an installation directory by invoking
make install
The necessary parameter and include files will be copied, too.
The target directory must be specified by setting the environment variable LPJROOT:
export LPJROOT=<installation directory>
Environment variables
The following environment variables are used by LPJmL:
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
LPJIMAGE - sets host where IMAGE is running
LPJWAITIMAGE - sets time to wait for connection to IMAGE model
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 - cpp runtime options for LPJmL
LPJOUTPATH - Path appended to the output filenames. Only done for filenames
without absolute path.
LPJOUTPUT - Default method for generating output files. Valid values
are write, mpi2, gather, and socket.
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.
Man pages
Manual pages for the man command are located in the $LPJROOT/man directory. Setting the
environment variable MANPATH to:
will enable help.
apropos lpj
yields list of man pages related to LPJmL.
Running the code
Sequential version can be started by invoking:
If you run lpjml outside the root directory of LPJmL, the following environment
variable should be set:
export LPJROOT=$HOME/lpjml
Then all includes are found. You can include the bin directory in the search path:
export PATH=$PATH:$LPJROOT/bin
Script is defined in bin setting all environment variables. Put
. <Path to LPJmL root dir>/
in your profile. Then LPJROOT, PATH and MANPATH are set accordingly.
Runtime options of lpjml
The following runtime options are defined:
-Iincludepath - Adds include path for LPJmL configuration file
-Dmacro[=value] - Defines macro
-h - print usage of lpjml
-l - print license
-v - print compiler used and LPJmL flags set
-vv - verbosely print the actual values during reading of the
configuration files
-param - print LPJmL parameter for soils and PFTs
-fpe - enable floating point exceptions
-image host - set host where IMAGE model is running. Option is only
available for the IMAGE version
-wait time - set time to wait for connection to IMAGE model
-output method - Method for generating output files. Valid values for method
are mpi2, gather, and socket. Methods mpi2 and
gather are only available for the MPI version
-inpath dir - input directory path
-outpath dir - output directory path
-restartpath dir - restart directory path
The first two options will be sent to the preprocessor.
For the parallel version SLURM and LoadLeveler files for Linux and AIX are provided.
A job can be submitted by invoking the bin/lpjsubmit script:
bin/lpjsubmit ntasks LPJmL_args...
Templates for customized LoadLeveler job control files are in the
loadl directory:
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 ./bin/lpjml
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 input data External
3 Error initializing grid External
4 Invalid carbon balance Internal
5 Invalid water balance Internal
6 Negative discharge Internal
7 Negative fire probability Internal
8 Negative soil moisture Internal
9 Error allocating memory External
10 Negative stand fraction Internal
11 Stand fraction sum error Internal
12 List is empty in dellistitem Internal
13 Index out of range in dellistitem Internal
15 Invalid year in getco2() External
16 Crop fraction >1 Internal
17 No natural stand for deforest Internal
18 Wrong cultivation type Internal
19 Floating point error Internal
21 PFT list is not empty in setaside Internal
22 Negative establishment rate Internal
23 Output channel is broken in socket connection External
24 Sending data to IMAGE model failed External
25 Opening connection to IMAGE model failed External
26 Not enough setaside stand created Internal
27 Forest left after deforestation Internal
28 Outflow reservoir error Internal
29 Permafrost error Internal
30 Global waterbalance error Internal
31 Cannot store climate data External
32 NO FMS coupler External
33 Cannot initialize soil temperature External
---------- --------------------------------------------- --------
External errors are caused by invalid or missing input files while internal
errors are caused by problems inside the LPJ 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
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. All necessary
programs can be downloaded from the Microsoft webpage.
Unzip the source and data files
configure makefile:
If the compiler does not find the system libraries, the library path defined in has to be modified.
create lpjml executable:
This diff is collapsed.
## ##
## M a k e f i l e ##
## ##
## Makefile for C implementation of LPJmL ##
## The call of ./ copies os-specific makefile.* in ##
## directory config to ##
## ##
## (C) Potsdam Institute for Climate Impact Research (PIK), see COPYRIGHT file ##
## authors, and contributors see AUTHORS file ##
## This file is part of LPJmL and licensed under GNU AGPL Version 3 ##
## or later. See LICENSE file or go to ##
## Contact: ##
## ##
INC = include
HDRS = $(INC)/buffer.h $(INC)/cell.h $(INC)/climate.h $(INC)/conf.h\
$(INC)/config.h $(INC)/coord.h $(INC)/crop.h $(INC)/cropdates.h\
$(INC)/date.h $(INC)/discharge.h $(INC)/param.h $(INC)/input.h\
$(INC)/errmsg.h $(INC)/grass.h $(INC)/header.h $(INC)/landuse.h\
$(INC)/list.h $(INC)/lpj.h $(INC)/manage.h $(INC)/managepar.h\
$(INC)/numeric.h $(INC)/tree.h $(INC)/image.h $(INC)/biomes.h\
$(INC)/output.h $(INC)/pft.h $(INC)/pftlist.h $(INC)/pftpar.h\
$(INC)/soil.h $(INC)/soilpar.h $(INC)/stand.h $(INC)/swap.h\
$(INC)/types.h $(INC)/units.h $(INC)/climbuf.h $(INC)/intlist.h\
$(INC)/queue.h $(INC)/pnet.h $(INC)/channel.h\
$(INC)/natural.h $(INC)/grassland.h $(INC)/agriculture.h\
$(INC)/reservoir.h $(INC)/spitfire.h $(INC)/biomass_tree.h\
$(INC)/biomass_grass.h $(INC)/cdf.h $(INC)/outfile.h $(INC)/cpl.h
CONF = lpjml.conf input.conf param.conf lpj.conf\
lpjml_netcdf.conf input_netcdf.conf lpjml_fms.conf input_fms.conf
DATA = par/*.par
SCRIPTS = configure.bat\
bin/output_bsq bin/lpjsubmit_aix bin/lpjsubmit_intel\
bin/lpjsubmit_mpich bin/lpjrun bin/backtrace\
bin/filetypes.vim bin/regridlpj
FILES = Makefile config/* AUTHORS INSTALL VERSION LICENSE magic.mgc\
$(MKDIR) lib
(cd src && $(MAKE))
(cd src && $(MAKE) libs)
(cd src/utils && $(MAKE) all)
all: main utils
install: all
$(MKDIR) $(LPJROOT)/include
$(MKDIR) $(LPJROOT)/man/man1
$(MKDIR) $(LPJROOT)/man/man5
$(MKDIR) $(LPJROOT)/man/man3
chmod 755 $(LPJROOT)
chmod 755 $(LPJROOT)/bin
chmod 755 $(LPJROOT)/include
chmod 755 $(LPJROOT)/lib
chmod 755 $(LPJROOT)/par
chmod 755 $(LPJROOT)/man
chmod 755 $(LPJROOT)/man/man1
chmod 755 $(LPJROOT)/man/man5
chmod 755 $(LPJROOT)/man/man3
install bin/* $(LPJROOT)/bin
install -m 644 $(HDRS) $(LPJROOT)/include
install -m 644 lib/* $(LPJROOT)/lib
install -m 644 $(DATA) $(LPJROOT)/par
install -m 644 INSTALL VERSION AUTHORS config/Makefile.template\
$(JCFFILE) lpjml.conf input.conf param.conf $(LPJROOT)
install -m 644 man/whatis $(LPJROOT)/man
install -m 644 man/man1/*.1 $(LPJROOT)/man/man1
install -m 644 man/man5/*.5 $(LPJROOT)/man/man5
install -m 644 man/man3/*.3 $(LPJROOT)/man/man3
test: main
$(MKDIR) output
$(MKDIR) restart
(cd src && $(MAKE) clean)
tar -cf lpjml-4.0.001.tar $(FILES) src/Makefile src/*.c\
src/climate/Makefile src/climate/*.c\
man/man1/*.1 man/man3/*.3 man/man5/*.5 man/whatis\
man/man1/Makefile man/man3/Makefile man/man5/Makefile man/Makefile\
src/crop/*.c src/crop/Makefile src/grass/*.c src/grass/Makefile\
src/image/Makefile src/image/*.c\
src/landuse/*.c src/landuse/Makefile src/lpj/*.c src/lpj/Makefile\
src/numeric/*.c src/numeric/Makefile src/soil/*.c src/soil/Makefile\
src/tools/*.c src/tools/Makefile src/tree/*.c src/tree/Makefile\
src/lpj/FILES src/pnet/*.c src/pnet/FILES src/socket/Makefile\
src/socket/*.c html/*.html html/*.css src/reservoir/Makefile\
src/image/Makefile src/image/*.c src/reservoir/*.c\
src/pnet/Makefile REFERENCES COPYRIGHT README doc/* src/utils/*.c src/utils/Makefile\
src/spitfire/Makefile src/spitfire/*.c R/*.r src/netcdf/Makefile src/netcdf/*.c\
src/cpl/Makefile src/cpl/*.c
gzip -f lpjml-4.0.001.tar
zip -l $(FILES) src/Makefile src/*.c\
src/climate/Makefile src/climate/*.c config/* man/* man/man1/*.1\
man/man3/*.3 man/man5/*.5\
src/crop/*.c src/crop/Makefile src/grass/*.c src/grass/Makefile\
src/image/Makefile src/image/*.c R/*.r\
src/landuse/*.c src/landuse/Makefile src/lpj/*.c src/lpj/Makefile\
src/numeric/*.c src/numeric/Makefile src/soil/*.c src/soil/Makefile\
src/tools/*.c src/tools/Makefile src/tree/*.c src/tree/Makefile\
src/lpj/FILES src/pnet/*.c src/pnet/FILES src/socket/Makefile\
src/socket/*.c src/reservoir/Makefile\
src/image/*.c src/image/Makefile src/reservoir/*.c\
src/pnet/Makefile REFERENCES COPYRIGHT README doc src/utils/*.c src/utils/Makefile\
src/spitfire/Makefile src/spitfire/*.c src/netcdf/Makefile src/netcdf/*.c\
src/cpl/Makefile src/cpl/*.c
This file contains some basic information on the open source distribution of the computer simulation model LPJmL.
LPJmL is developed and maintained at the Potsdam Institute for Climate Impact Research (PIK) in Potsdam, Germany.
All source code, configuration and parameter files are subject to
copyright (C) by the Potsdam Institute for Climate Impact Research, see the file COPYRIGHT
and are licensed under the GNU AFFERO GENERAL PUBLIC LICENSE Version 3, see the file LICENSE
and is the result of collaborative work, see the file AUTHORS
For setting up the model, see the file INSTALL
The source code is distributed via a git repository at after registration.
The registration is free of costs.
Outside joint collaborative agreements with PIK, there is absolutely no support in model download, setup, development, application or similar.
New model development can be submitted to the LPJmL git repository in separate repository branches and pull requests can be issued. There is no guarantee or obligation that external model features, bug fixes or other developemnts will be merged into the standard LPJmL distribution at PIK.
Discussions on model development features can only be initiated via issues at after registration.
We strongly encourrage considering the coding standards and style recommendations in LPJmL. For details see the file STYLESHEET
Biemans, H, Haddeland, I, Kabat, P, Ludwig, F, Hutjes, RWA, Heinke, J,
von Bloh, W, & Gerten, D 2011 Impact of reservoirs on river discharge and
irrigation water supply during the 20th century, Water Resour. Res., 47,
W03509, doi:10.1029/2009WR008929.
Bondeau A, Smith P, Zaehle S, Schaphoff S, Lucht W, Cramer W, Gerten D,
Lotze-Campen H, Mueller, C, Reichstein M, Smith B 2007 Modelling the role
of agriculture for the 20th century global terrestrial carbon balance.
Global Change Biology 13, doi: 10.1111/j.1365-2486.2006.01305.x
Carslaw, HS & Jaeger JC 1959 Conduction of Heat in Solids, Oxford University
Press, London
Collatz, GJ, Ball, JT, Grivet C & Berry, JA 1991 Physiological and
environmental regulation of stomatal conductance, photosynthesis and
transpiration: a model that includes a laminar boundary layer. Agricultural
and Forest Meteorology 54: 107-136
Collatz, GJ, Ribas-Carbo, M & Berry, JA 1992 Coupled photosynthesis-stomatal
conductance models for leaves of C4 plants. Australian Journal of Plant
Physiology 19: 519-538
Farquhar GD & von Caemmerer 1982 Modelling of photosynthetic response to
environmental conditions. In: Lange, OL, Nobel PS, Osmond CB, Ziegler H
(eds) Physiological Plant Ecology II: Water Relations and Carbon
Assimilation, Vol 12B. Springer, Berlin, pp 549-587.
Foley J A 1995 An equilibrium model of the terrestrial carbon budget.
Tellus 47B: 310-319
Gerten D, Schaphoff S, Haberlandt U, Lucht W, Sitch S 2004 Terrestrial
vegetation and water balance: hydrological evaluation of a dynamic global
vegetation model. Journal of Hydrology 286: 249-270
Harper JL 1977 Population Biology of Plants, Academic Press, London
Haxeltine A & Prentice IC 1996 BIOME3: an equilibrium terrestrial biosphere
model based on ecophysiological constraints, resource availability, and
competition among plant functional types. Global Biogeochemical Cycles 10:
Haxeltine A & Prentice IC 1996a A general model for the light-use efficiency
of primary production. Functional Ecology 10: 551-561
Henderson-Sellers, A & Robinson, PJ 1986 Contemporary Climatology. Longman,
Jaegermeyr J, Gerten D, Heinke J, Schaphoff S., Kumm M & Lucht W 2015 Water
savings potentials of irrigation systems: global simulation of processes
and linkages. Hydrol. Earth Syst. Sci 19: 3073-3091
Jarvis, PG & McNaughton KG 1986 Stomatal control of transpiration: scaling up
from leaf to region. Advances in Ecological Research 15: 1-49
Jury WA, Gardner WR & Gardner WH 1991 Soil Physics 5th ed, John Wiley, NY
Larcher W 1983 Physiological Plant Ecology, 2nd ed, Springer-Verlag, Berlin
Lloyd, J & Taylor JA 1994 On the temperature dependence of soil respiration
Functional Ecology 8: 315-323
Monsi, M & Saeki, T 1953 Ueber den Lichtfaktor in den Pflanzengesellschaften
und seine Bedeutung fuer die Stoffproduktion. Japanese Journal of Botany
14: 22-52
Monteith, JL & Unsworth, MH 1990 Principles of Environmental Physics, 2nd ed,
Arnold, London
Prentice, IC, Sykes, MT & Cramer W 1993 A simulation model for the transient
effects of climate change on forest landscapes. Ecological Modelling 65:
Press, WH, Teukolsky, SA, Vetterling, WT & Flannery, BT. 1986. Numerical
Recipes in FORTRAN, 2nd ed. Cambridge University Press, Cambridge
Reich, PB, Walters, MB & Ellsworth, DS 1997. From tropics to tundra: global
convergence in plant functioning. Proceedings of the National Academy of
Sciences USA 94: 13730-13734.
Rost, S, Gerten, D, Bondeau, A, Lucht, W, Rohwer, J & Schaphoff, S 2008
Agricultural green and blue water consumption and its influence on the
global water system. Water Resources Research 44: W09405
Ryan, GR 1991 Effects of climate change on plant respiration. Ecological
applications 1: 157-167
Schaphoff, S, Heyder, U, Ostberg, S, Gerten, D, Heinke, J, Lucht, W 2013
Contribution of permafrost soils to the global carbon budget.
Environ. Res. Lett. 8, 014026.
Shinozaki, K, Yoda, K, Hozumi, K & Kira, T 1964 A quantitative analysis of
plant form - the pipe model theory. I. basic analyses. Japanese Journal of
Ecology 14: 97-105
Shinozaki, K, Yoda, K, Hozumi, K & Kira, T 1964 A quantitative analysis of
plant form - the pipe model theory. II. further evidence of the theory and
its application in forest ecology. Japanese Journal of Ecology 14: 133-139
Sitch S, Smith B, Prentice IC, Arneth A, Bondeau A, Cramer W, Kaplan J, Levis S,
Lucht, W, Sykes M, Thonicke K, Venevsky S 2003 Evaluation of ecosystem dynamics,
plant geography and terrestrial carbon cycling in the LPJ Dynamic Vegetation
Model. Global Change Biology 9: 161-185
Sprugel, DG, Ryan, MG, Brooks, JR, Vogt, KA, Martin, TA, Respiration from the
organ level to the stand (in press '93 ---> look up)
Thonicke K, Spessa A, Prentice IC, Harrison SP, Dong L & Carmona-Moreno C 2010
The influence of vegetation, fire spread and fire behaviour on biomass
burning and trace gas emissions: results from a process-based model.
Biogeoscience 7(6):1991-2011
van Duin, RHA 1963 The influence of soil management on the temperature
wave near the surface. Tech Bull 29 Inst for Land and Water Management
Research, Wageningen, Netherlands
von Bloh, W, Rost, S, Gerten, D & Lucht, W 2010 Efficient parallelization of a
dynamic global vegetation model with river routing. Environmental Modelling &
Software 25: 685-690
Waha K, van Bussel LGJ, Mueller C, Bondeau A 2012 Climate-driven simulation of
global crop sowing dates. Global Ecology and Biogeography, 21,2,
pp. 247-259, doi: 10.1111/j.1466-8238.2011.00678.x
Waring, RH Schroeder, PE & Oren, R 1982 Application of the pipe model theory
to predict canopy leaf area. Canadian Journal of Forest Research 12:
VERSION 0 → 100644