LPJmL Documentation

CONTENTS

INSTALLATION

INPUT DATA

LPJ is driven by monthly fields of temperature, precipitation, cloudiness and number of days with rain. Additionally static information on soil properties, geographic coordinates of climate and soil data, and mean annual atmospheric CO2 concentration are required. Except for CO2 all files are binary data including a header (except for the soil data).

Overview of LPJ input data

Structure of the header

- header name (1 byte char array, LPJCLIMATE (10 bytes) for temp,precip,wet days and cloudiness, LPJGRID (7 bytes) for coordinate data, LPJLANDUSE (10 bytes) for landuse data, LPJ_COUNTRY (11 bytes) for country codes)
- header version (4 byte integer, currently set to 1, also used to determine if input data needs byte swapping)
- order (4 byte integer, values are either 1 (cellyear) or 2 (yearcell))
- firstyear (4 byte integer, first year of data record)
- nyear (4 byte integer, total number of years) 
- firstcell (4 byte integer)
- ncell (4 byte integer, number of grid cells represented)
- nbands (4 byte integer) 

Sorting of the climate data

coordinate data (1 file)

-----------------------------------
gridfile [scaled: degree*100]
  in C data type short (2 bytes), lon lat for each pixel
  defines the extent of your input data
  size of header: 35 bytes
-----------------------------------

soil data (1 file)

-----------------------------------
soil input
  data type char (1 byte), the grid needs to be the same as your input
  grid / climate data
  values are currently ranging from 0 to 9
  corresponding soil parameters can be found in par/soil.par
  no header 
-----------------------------------

climate data (all monthly values, 4 files + 1 file with atmospheric CO2 concentrations)

-----------------------------------

- atmospheric carbon dioxide [ppmv]
  global annual mean CO2 concentration as ASCII file
  format: year concentration
  Example
    1990 354.19
    1991 355.59
    1992 356.37
    1993 357.04
    1994 358.88
-----------------------------------

Land use data

Model parameters

HOW TO RUN IT - FIRST STEPS

•   the location of parameter files and part of the input data
•   the names and location of output files (be sure they match the number and order of outputfiles specified in conf.h, see below for further information on output files)
•   the spin-up period (number of years the model is run towards equilibrium with constant climate)
•   the number of the first and last cell (from the input grid)
•   the start/endyear of the simulation

FLAGS FOR RUNNING LPJ

COMPILER FLAGS

LPJ specific

Compiler specific

RUNNING AND COMPILING LPJ UNDER WINDOWS

Windows requires some specific adjustments to make LPJ compile and run. Here's a first overview of what to do:

General

• All experience reported here refers to the Microsoft Visual C++ 2005 Express Edition and the SDK Platform
• Download the VC and SDK from the microsoft download center http://msdn.microsoft.com/vstudio/express/visualc/ (the link specified in the INSTALL file is outdated, but still forwards you to the correct site)
• Follow the instructions there. Although this is a Microsoft tool, installing is not just click and run. You need to manually edit a few files to make VC and SDK work together (although VC does not work properly without SDK...). Usually, installation from the internet does not work properly, but MS also offers to download a CD image (*.img or *.iso), which can be used to install the program.
• Make sure you add the path "C:\Program Files\Microsoft Visual Studio 8\Common7\IDE\" to your environment variable "path"
  
• environment variables can be set by right-clicking on "my computer", then choose "properies".  Select the "advanced" tab and at the bottom there will be a button for "environment variables".  You will see these are divided up into "user variables" and "system variables", and in the list one should be "PATH".  If you highlight that one and click edit, then you can add "C:\Program Files\Microsoft Visual Studio 8\Common7\IDE;" (or the appropriate path for your PC)
• Don't forget the semi-colon at the end if you put it first, or you can scroll through all the others and insert it at the end.
• Don't insert spaces between semi-cola and the following path.
  
• Also, go to vs2005 install path c:\program files\microsoft visual studio 8\vc, run vcvarsall.bat to set environment variable; then c:\program files\microsoft platform sdk\, run setenv command: eg: setenv /SRV32 /DEBUG.
• Windows compilers seem to be more sensitive than Linux compilers, which are, in turn, more sensitive than AIX compilers...
• Never declare variables within the code. All declarations need to be before the first statement
• Never include #define statements in code (*.c) files. All #define statements need to be in the header (*.h) files.
• fopen(filename,options) calls need a 'b' in the options statement if a binary file is to be opened. Do not include a 't' if a text file is to be opened, here Linux seems to be touchy...
  

CVS

• CVS works as under Linux and AIX, but you need to install a Windows client for CVS. We've tried 2 clients, WinCVS and TortoiseCVS and TortoiseCVS proved to be much easier to use and understand. Here's what you need to do:
• Get TortoiseCVS from http://www.tortoisecvs.org and install it to your computer. You don't need administrator rights for this.
• Tortoise CVS works from within Windows Explorer. Simply create a new folder where you want your working copy of LPJ to be and right click on it. The menu now offers "CVS checkout" (and later on also "update" and "upload" etc.). Here, you can specify your settings, you do not need to define SSH tunnels before. Change the following items:
• Module
• Protocol: SSH
• Server: aix.pik-potsdam.de
• Repository folder: /data/biosx/CVS/
• User name: <your PIK user name>
• Module: LPJv3
• Revision
• specify the CVS branch you want to check out: e.g. LPJv3_1

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:
  
• in src/: cat2bsq.c, catlpj.c, cfts26_lu2clm.c, cru2clm.c, drainage.c, grd2bsq.c, headergrid.c, printlpj.c, river_sections_input_climate.c, river_sections_input_grid.c, river_sections_input_landuse.c, river_sections_input_soil.c
• in src/lpj/: iteratecell.c
• in src/base/: gp.c
• 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 -DIMAGE) lpj.conf
  
• here, you can specify your working directory
• C/C++
• General:
• Additional Include directories: add the LPJv3/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; USE_CPP
• optional: LANDUSE; DEBUGEFENCE; IMAGE
• 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 Server 2003 R2\Lib)
• Done. Now right-click on the project in the Solution Explorer and select rebuild or build.
• To run LPJ from the command line, you can start the Visual C++ 2005 Express Console and start LPJ as usual from there (e.g. LPJ.exe -DISRANDOM lpj.conf)

RUNNING IT IN PARALLEL

RUNNING IT WITH LAND USE

RUNNING IT IN RIVER-ROUTING MODE

RUNNING IT COUPLED TO IMAGE

MALLOC DEBUGGING

• We used the efence library to locate array accesses out of bounds

How to

• Change associated Makefiles (Makefile.gcc, Makefile.aix) to link the efence library
  
• Make sure Makefile.inc is up-to-date (using configure.sh or configure.bat) because this file is actually used for the compilation and the compiler-specific Makefiles
  
• CFLAGS  = -g -O3 -Wall -pedantic -DSAFE  -DUSE_CPP -DUSE_UNAME -DUSE_RAND48 -DDEBUG -DDEBUGEFENCE -lefence
• Run lpj in debugger (Linux: ddd/gdb, AIX: dbx)

• The location of each error reported is shown with the where command in the debugger

• If experiencing problems such as "cannot open file" or such alike, try to start the DDD debugger from your LPJv3 directory via "ddd lpj &". Otherwise, the command "run -DWHATEVEROPTION lpj.conf" may not find the correct lpj.conf or any other file used later on (such as TDT configuration files).

REMOVING LIST ELEMENTS

WHAT IS THE OUTPUT?

output file formats

some common output variables:

•   fpc: foliage projected cover in %
•   firef: fire return intervall, calculated as 1/(fraction of gridcell burned this year)
•   firec: fire carbon emissions in gC/m2/year
•   vegc, litc, soilc: carbon pools (vegetation, litter, soil) in gC/m2
•   mnpp: monthly net primary production in gC/m2/month
•   mrh: monthly heterotrophic respiration in gC/m2/month
•   mswcx: monthly average soilmoisture of layer x (fraction of field capacity, from 0-1)
•   mtransp, mevap, mrunoff, minterc: monthly transpiration, evaporation, runoff and interception  (on leaves) in mm/month

HOW TO HANDLE OUTPUT FILES?

• if lpj has been run in distributed mode, use output_bsq.ksh to join the output parts to one file. All following steps will be the same.
• to create a rectangular binary image from the output use the program grd2bsq (call it with [-h] to get help). Don't forget to use the output grid, not the input grid ... 
• read it into your favourite visualization software

READING BINARY FILES

•  quite simple with any programming language, once you know how the data is stored (output format); if you are transferring data between different computer systems, you might need to account for different byte order
•  most image processing programs have an option to import binary data (but they usually need it in a rectangular grid)
•  R can read binary data (there is a sample script on /data/biosx/tools/R)
•  ArcView / ArcGIS: they DO read binary input data, but the online help system will not tell you ... You need to specify a header with data type, coordinates etc. There should be information on the web about the specifications for the version you are using. It seems to cause problems to read negative values, though.
•  if you have problems importing binary data to the software you are using for analysis, you might need to convert the output data to ASCII or a different binary file format first

HOW TO ADD NEW OUTPUT

• lpj.conf
• adjust the number as well as the names of the output files
  
• the number of names has to be equal to the numeric number of output files
• the order has to be the same as in include/conf.h
  
• include/conf.h
• define synonyms for numbers for the outputs
• number serially of the synonyms with start at 0
  
• the order of the numbers of the synonyms has to be the same as in lpj.conf
  

• include/output.h
• declaration of output variables in structure `Output´
• struct `Cell´ contains struct `Output´ named output
• src/lpj/newgrid.c
• allocate memory for array variables, that means especially pft-specific output
  
• src/lpj/output.c
• initialization of output variables in local function initoutput_monthly() or initoutput_annual()
• write output values in local function fwriteoutput_monthly() or fwriteoutput_annual()
• free any memory you have allocated in function freeoutput()

ABOUT BYTE ORDERING / ENDIANNESS

MEMORY SHORTAGES (XLC COMPILER)

• xlc compiler flag: -bmaxdata:0x80000000
• this allows the program to allocate up to 2 GB of memory (instead of the standard limit of 256 MB)

STRUCTURE OF THE CODE