LPJ How-To's

Contents

Run with land use
Run coupled to IMAGE
Rum and compile LPJ under Windows
TDT coupling
Malloc debugging
Removing list items
Format of input data (header structure)
Adding new output
Memory shortages
Compilation and Makefiles

Run with land use

If you want to account for croplands in LPJmL simulations, in some CVS branches (e.g. LPJ_SPEEDY) you need to compile the code with the -DLANDUSE (or LANDUSE under windows) option. If this is compiler switch is turned on, please make sure that
  • the path to the land-use file is specified in the cru_*.conf file and
  • the pft.par file includes the line 11 /* number of cfts */ after the line 9 /* number of pfts */

Run coupled to IMAGE

If coupled to IMAGE, the code needs to be compiled with the -DIMAGE (or IMAGE under windows) option. If this switch is activated, you need to include the correct TDT libraries (see TDT coupling). Also, you need to call the program with the -DIMAGE option in the command line (such as lpj -DIMAGE lpj.conf or lpj.exe -DIMAGE lpj.conf). Otherwise the conf files are not read in correctly.

Run and compile 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)

TDT coupling

How to

  1. Download the TDT library from the above link
    1. NOTE: If you downloaded the code before March 22, 2007, please get the newest release version!
  2. Unfortunately, TDT defines the data type "String" dynamically, while LPJmL defines it static. To avoid double definition of type String, you need to replace all "String" with "String_TDT" (or whatever you like, just be consistent!) throughout the TDT code. In the newest download package (March 22, 2007), this should be exactly 100 times. Make sure you're only replacing capital "String", not "string".
  3. compile TDT with "make lib" to generate "libtdt.a"
    1. Note that you need to set a symbolic link to really call gmake ith the make command under the AIX or CLUSTER, otherwise TDT will not compile under AIX. (Setting the symbolic link did not work for me, though, I'm afraid I'm too ignorant to do that correctly...)
  4. copy tdt.h to the LPJmL "include" folder
  5. copy your generated "libtdt.a" and "libexpat_linux.a" (or "..._aix.a", whatever you need) from the expat folder in the TDT project to the LPJmL "lib" folder
  6. add "#include tdt.h" in lpj.h
  7. add "$(LIB)/libtdt.$A" and "$(LIB)/libexpat_linux.$A" to the Makefile in src

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

  • If you delete an element of a list (e.g., pftlist, standlist) the last element is moved to the position of the deleted element

Format of input data (header)

  • all input data files (climate, coordinate grid, landuse and restart input files; except for soil data file) need a header to be read correctly by LPJ
  • the header consists of several integer variables (except headername) in the following order:
    • headername (different length), fileversion, order (CELLYEAR or YEARCELL), firstyear, nyear, firstcell, ncell, nbands

How to add a 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()

Memory shortages

  • 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)

Compilation and Makefiles

Compiler options

GCC

Option
Comment
-gProduce debugging information in the operating system's native format
-O3
Optimize yet more. -O3 turns on all optimizations specified by -O2 and also turns on the -finline-functions, -funswitch-loops and -fgcse-after-reload options.
-WallThis enables all the warnings.
-DSAFECheck LPJ variables and data. 
-DUSE_CPPEnable preprocessing
-DUSE_UNAMEInclude /sys/utsname.h for system informations
-DUSE_RAND48Use seed uniformly distributed double-precision pseudo-random number generator
-DDEBUGEFENCEneeded only to run LPJmL in a degugging environment (DDD on linux or dbx on UNIX):here, uninitialized variables are not allowed, although they are no problem in the normal running mode