LPJ How To Pages
- Deutsch | English
Help on how to download and manage LPJ/LPJmL code
Content
- Retrieve the code (PIK account required)
- Developer Environments
- Compiling/Installing LPJmL
- Debugging
- Running LPJmL
- Benchmarking
Retrieve the code (PIK account required)
In order to retrieve the code as described here, you need to have a PIK user account. If you don't have one, please contact your cooperation partner at PIK or download the release version of LPJ here.
If you have a PIK account, you need to set up a SSH tunnel and use a SVN client to download the code and/or commit changes.
SSH tunnel
- If you already have an account at PIK, you probably also have the SSH client installed.
If not, and you're a Windows user, download it e.g. from
http://ssh-secure-shell.soft-ware.net/download.asp - Install the downloaded SSH client and run it. If you already have the client installed and a PIK profile set up to the aix.pik-potsdam.de, including the SSH tunnel for the SVN server, you can skip steps a-c.
- click on quick connect and enter “aix.pik-potsdam.de” into the host field and your PIK username into the username field. Port-number should be on 22 (default) and authentication method should be “password” (default).
- Click on the settings icon (or via menus: Edit->Settings), select Profile Settings -> Tunneling and add a new outgoing tunnel. Settings are as in the picture below:
- Save settings to your PIK profile (or create a new profile if you have not used the SSH client to connect to PIK before).
- Connect to PIK, you will be promted for your password and as soon as the connection is established, your SSH tunnel to the PIK subversion server is in place.
Linux/Unix users usually have SSH daemons installed.
SVN client
Linux/Unix users:
You usually have SVN daemons installed.
Helpful commands:
- Checking out a working copy
- svn checkout http://subversion/svn/LPJ/trunk <yourworkingdirectory>
- commiting your changed files. Note, this will commit all changes files in the current directory and all directories therein. If you want to commit single files only, specify the filename as last argument. You can also specify several file names.
- svn commit -m "your message to explain what you've changed" [filename[ filename2]]
- updating your working copy. Note again, this applies to the current directory and everything therein. You may specify specific directories or files
- svn update
- svn update src/crop/new_crop.c
- If you have not installed TortoiseSVN client, please go to
-
and install it now. No restart of your computer should be necessary.
- Create a new folder where you want to store the LPJmL source code.
- Right-click on that folder, select the SVN checkout button
- SVN opens a window, where you should specify the URL of the subversion repository, which is
- If you ever have to work on a temporary developer branch (e.g. “MY_BRANCH”), the syntax is like this
http://localhost:8888/svn/LPJ/branches/MY_BRANCH - Click on OK and download will start, prompting you for your PIK username and PIK password.
- Comminting changed code, diff etc. can all be accessed by a right-mouse-click menue in the Windows Explorer.
Developer Environment
If you plan to actually work with the code, it is very recommendable to use a developer environment.
Eclipse
You can get a platform independent development environement (JAVA based) at
Bug in Eclipse's SVN client under Linux
There seems to be a bug in the current Galileo release for Linux. Using the Subversive plugin fails with "Validate Repository Location’ operation finished with error: Selected SVN connector library is not available or cannot be loaded.".
In order to fix this, you need to add additional third party SVN connectors:
- Select Help - Install New Software from the menu bar
- Click Add
- Enter http://community.polarion.com/projects/subversive/download/eclipse/2.0/update-site/ as location and click OK
- Unfold Subversive SVN Connectors and select the SVNKit connectors
- Install the files and restart Eclipse
Visual Studio C++ Express
Microsoft free version of of the Visual Studio allows you to download the program, including a debugger. You can get it at
http://www.microsoft.com/express/download/
(look for version 2008) and opposed to previous releases, this works smoothly.
If you are working with windows systems anyway, this is a nice and handy developer environment. The main difference to alternatives (eclipse, text editors, etc.) is that VS uses no makefiles. Instead, you'll have to configure the project by hand.
However, you still may use the makefiles supplied with the code in windows systems, if you have VS C++ installed.
Setting up a VS project
- 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: graphics, oracle, utils, ...
- 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 lpjml.conf
- here, you can specify your working directory
- C/C++
- General:
- Additional Include directories: add the ../include directory here
- Debug Information Format: C7 Compatible (/Z7)
- Optimization
- full (or whatever you want)
- Preprocessor
- 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;_USE_MATH_DEFINES;WITH_FPE;SAFE;_CRT_SECURE_NO_WARNINGS;
- optional: SINGLECROP; IMAGE
- Code Generation
- Enable Minimal Rebuild -> No
- Basic Runtime Checks -> Default
- Advanced
- compile as -> compile as C code (/TC)
- Linker
- General
- necessary Additional Library Directories -> <SDK root dir>/Lib (e.g. C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Lib)
- Input
- Additional Dependencies -> advapi32.lib ws2_32.lib
- Ignore Specific Library -> LIBCMT.lib
- Done. Now right-click on the project in the Solution Explorer and select rebuild or build.
Compiling/Installing LPJmL
To compile the code using MAKEFILES that come with the code just open a console window and move to the directory where your code is at. Windows users have to start the following from the Visual C++ 2005 Express Console in order to have access to the VS compiler.
Windows:
- call "configure.bat" to adjust the makefile.inc for your operating system (windows). Check for path names in config/Makefile.win32 and rerun in case of changes.
- type "nmake" to compile the code
- type "nmake clean" to delete the last executable and all object/library files
- type "nmake all" to compile the code and additional utility programs (all source code for utility programs is at src/utils/
Linux/Unix:
- call "configure.sh" to adjust the makefile.inc for your operating system (windows)
- type "make" to compile the code
- type "make clean" to delete the last executable and all object/library files
- type "make all" to compile the code and additional utility programs (all source code for utility programs is at src/utils/
- Debian/Ubuntu users need to make sure that libxt-dev is installed. Otherwise the compilation of lpjliveview fails due to missing libraries.
- type "make install" to compile the code and set up man pages
Debugging
Even the most accurately programmed code will eventually not work properly. In this case, the code needs to be debugged. This can be done either by hand (and amounts of printf-statements) or with the support of debuggers, small programs designed to support debugging.
For debugging, the source code should be compiled without any optimization. For all systems using the Makefiles provided with the code, just run
configure.sh -debug or configure.bat -debug
and re-compile the entire code (make clean; make all).
Once compiled, you can either use the gdb debugger directly or its GUI ddd:
For ddd on the cluster, make sure that you have exported the DISPLAY
export DISPLAY=[MYCOMPUTERNAME|MYIPADDRESS]:0.0
and an X-server running (e.g. Exceed), otherwise ddd will not be able to open a window on your computer.
With ddd you can either examine a core file (copy of the memory used by the program at program crash) or rerun the program and examine its behavior during the run.
Alternatively, you may also use the valgrind debugger, which we often used to detect memory leakages (reading/writing out of array bounds -- a very nasty bug to find). It's a command line tool, so it needs some arguments to do what you want it to do. Try
valgrind --help
to see the most important ones. We've mainly used these two (for checking leakages and for writing a log file):
valgrind --leak-check=full --log-file=YOURLOGFILENAME YOURPROG YOURARGS
Werner has installed valgrind on his home directory, so you can access it via
/home/bloh/bin/bin/valgrind YOURPROGRAMNAME
In order to debug a job running in parallel mode on the cluser, just add the valgrind command in front of the mpiexec command in the job.jcf file (at about line 33):
/home/bloh/bin/bin/valgrind --leak-check=full --log-file=vallog.log mpiexec ...
Running LPJmL
After compiling, you are almost ready to start. All you need to do is specify the simulation settings in the lpjml.conf file, which is provided in the main directory. Since LPJmL can be run with a variety of settings, you’ll find a lot of different flags, which makes this look a bit confusing.
- The only decision that you have to make when running your model is whether you run it from a restart file or not. If not, the default option is that you generate no output files except the restart file. Starting from a restart file is indicated by starting the model with an extra flag:
- lpjml.exe –DFROM_RESTART lpjml.conf
- lpjml.exe lpjml.conf
- You can leave most settings as they are. If you don’t need to compute river routing, it is recommendable to comment out the line
#define RIVER_ROUTING
as that makes the model considerably slower (factor 2 at least).
- The flag
#define WITH_LANDUSE 1
should never be changed. The options “NEW” and “CONST” are nice in principle but don’t work yet…
- In line 61 (or close by) you can specify the type of irrigation. Note that you need river routing if you want to have limited irrigation
- In the INPUT DATA SECTION the file “input.conf” is included. In this file (also in the main directory) you have to specify the names and paths to the input files you want to use. Note that the order of input files MUST NOT be changed
- All input data you need can be downloaded via the SSH file transfer client (connected to the aix.pik-potsdam.de). Just go to the directory
/data/biosx/LPJ/input_new/
or
/data/biosx/LPJ/input_cru2000_image/coupling1970/ddm30/
for the data for the IMAGE coupling (CRU 2002, ordered after river basins)
- Output files can be specified in any order. In include/conf.h you can see, what outputs are already available (~80 so far). You do not need to specify any output at all and it usually is not recommendable to generate all possible outputs (a LOT OF data!). The default output path is “output” make sure to change that accordingly or to create that subfolder.
Local PC
You may run the model on your local PC (global runs take about 1 to 5 min/simulation year), just in the way as described above. Just make sure that all input and output directories are specified correctly and that the executable runs on your PC (was compiled there, preferably).
To run LPJmL from the command line, just open a console windows and start LPJ as usual from there (e.g. LPJ.exe lpjml.conf). Windows users have to start the program from the Visual C++ 2008 Express Console if the executable has been compiled with VS.
CLUSTER
If you're planing longer simulation runs or several scenarios, it's recommendable to use the "super" computer @ PIK, see here for a general introduction and here for the user guide.
- To connect to the cluster, you'll need a key-pair for SSH. See here for instructions.
- once connected you should compile LPJmL there (configure.sh, make all) -> the make all is important to have some utility programs and scripts available that make life easier...
- in the basic directory, execute ". bin/lpj_paths.sh" (note the syntax: dot space ...)
- call "lpjsubmit <number_of_nodes_you_want_to_use> <your_conf_file>"
- all output (and preferably input, since it's faster) should be written to (read from) /scratch/01/<your_subdirectory>
- BEWARE! All data on /scratch/01/ will be deleted if untouched for at least 3 months!
- To avoid deletion, use the touch command in your /scratch/01/<your_subdirectory> directory, regularly:
find ./ -exec touch {} \;
Windows users:
- the cluster and CLME require public key authentication, which is not possible with the SSH client as described above. So we need another client instead (note this new client can also handle all the tunnels, you just have to set them up accordingly): the tunnelier, available at http://www.bitvise.com/tunnelier-download
- Click on “tunnelier installer”
- Once installed a new blank profile is opened automatically.
- Now you need to generate a key pair which should also work under windows, but we haven't figured out how to do that, so here's maybe not the most direct way there is:
- open a ssh connection to any unix host @ PIK, preferably the aix.pik-potdam.de, which also works with the client described above -- or with the tunnelier without publickey authentication
- On the unix host, execute ssh-keygen –t dsa, you must then specify the location and name of of the private/public key pair. Just choose the default. Don’t set a passphrase (according to Werner this gives problems with running lpj in parallel mode). This creates a pair of files (id_dsa & id_dsa.pub)
- Check if the files are created by typing ls –al .ssh
- If there is not yet a file called authorized_keys copy the public key (id_dsa.pub) to this file by
cp ~/.ssh/id_dsa.pub ~/.ssh/authorized_keys
cat ~/.ssh/id_dsa.pub >> ~.ssh/authorized_keys
CLME
If you'r planning longer simulation runs or several scenarios, it's recommendable to use the "super" computer @ PIK. As long as the new cluster is not yet available, you'll have to use the CLME, which is a project cluster and suffers from overtaxing and long waiting queues.
Anyway, it's often worth the waiting time.
- To connect to the CLME, you'll need a key-pair for SSH. See here for instructions.
- once connected you should compile LPJmL there (configure.sh, make all) -> the make all is important to have some utility programs and scripts available that make life easier...
- in the basic directory, execute ". bin/lpj_paths.sh"
- call "lpjsubmit <number_of_nodes_you_want_to_use> <your_conf_file>"
- all output (and preferably input, since it's faster) should be written to (read from) /scratch/02/<your_subdirectory>
Benchmarking
After major changes in the code, all outputs should be checked for consistency with previous LPJ versions. Runs should follow the protocol below and can be compared with the the R script provided with the LPJmL code.
Protocol
- Restart 1: 1000 years spinup with natural vegetation
- Restart 2: starting from Restart 1, 398 years with landuse
- Run 1: Natural vegetation only, no river routing, from Restart 1
- Run 2: Actual vegetation, no river routing, from Restart 2
- Run 3: Actual vegetation, river routing, from Restart 2
With the following settings:
- Input data: CRU-PIK 2003, cft1700_2005.bin
- #define BENCHMARK_LAI in lpjml.conf (fixed LAI_max of 5)
- random seed of 2
- POT_IRRIGATION
Reference runs can be found on:
- /data/biosx/valid/Benchmark_runs/output_nv (for Run 1)
- /data/biosx/valid/Benchmark_runs/output_lu (for Run 2)
- /data/biosx/valid/Benchmark_runs/output_lu_rr (for Run 3)
Reference data can be found on:
- /data/biosx/valid/nee/nep.csv (NEP)
- /data/biosx/valid/evapotr/tpi.csv (water fluxes)
- /data/biosx/valid/runoff/runoff.csv (river discharge gauge data)
Script
LPJmL comes with an R-Script for comparison of two runs with each other and with reference data, which should be used for benchmarking.
Files:
- R/benchmark.settings (to specify path names, resolution, byte order, etc)
- R/lpj_benchmark.r (the main script)
- R/benchmark_functions.r (some R functions)
- R/layouts.r (page layouts & parameter settings)
The script can be started with
R CMD BATCH lpj_benchmark.r
or from a running R process with
source("lpj_benchmark.r")
R is installed on PIK's clusters or can be downloaded from
http://www.r-project.org/
Programming in C
LPJmL is written in C. See here for the history of LPJ versions.
There a lots of online tutorials for learning C.
For German speakers, the best online book we know of is found at
http://openbook.galileocomputing.de/c_von_a_bis_z/
or download the book directly at
http://download.galileo-press.de/openbook/c_von_a_bis_z/galileocomputing_c_von_a_bis_z.zip
Any suggestions for English literature on C programming is most welcome.
As a starter, take a look at this wikibook
http://en.wikibooks.org/wiki/C_Programming
Pointers to functions
An important feature to know, when programming LPJmL is the concept of pointers to functions.
In fact, this is mimicking object oriented programming. So far there are 2 types of pointers to functions: PFT-specific functions and STAND-specific functions. Instead of calling a function with CASE of IF/ELSE constructs that determine what function would be appropriate to call for this specific PFT or STAND, a macro is called, which directs the call to the general function (say a call to NPP) to the function, which's pointer is stored in the PFT/STAND structure. In our example of the NPP function, the PFT knows which type it is (grass, crop or tree) and calls the appropriate function (npp_grass.c, npp_crop.c, or npp_tree.c).
In a way, this makes the code much cleaner (since it saves a lot of CASE/IF statments) but also more difficult, since macros are not easily detectible in the code and the call-strucutre of functions is therefore not straigth forward to see.
Anyway, if you want to work with LPJmL, you'll have to understand what pointers are and how pointers to functions work.
Here are some links to online tutorials on pointers to functions:
http://publications.gbdirect.co.uk/c_book/chapter5/function_pointers.html
http://www.newty.de/fpt/index.html
Programming LPJmL
Adding new output
In order to add new outputs, you'll have to take care of several things. There are in principle 4 different output types available
- annual outputs per pixel
- annual outputs per PFT/CFT
- monthly outputs per pixel
- daily outputs per pixel for 1 single CFT
Unless you plan to provide a new type of output, you could try to copy/paste one of these structures/functionalities.
- Add new elements to the struct Output in include/output.h ATTENTION! Monthly outputs need to be added to the struct Outputmonth as well, daily outputs only have to be added to the struct Daily_outputs (which is an element of the general Output struct).
- For PFT/CFT-specific outputs: allocate memory to element in src/lpj/initoutput.c
- For PFT/CFT-specific outputs: free memory of element in src/lpj/freeoutput.c
- Initialize new output elements in corresponding init function (e.g. initoutput_monthly.c)
- Create a unique identifyer in include/conf.h
- Increment NOUT in include/conf.h by the number of new outputs created
- MONTHLY outputs only: Add output identifyer to function that checks type of output (i.e. src/lpj/ismonthlyoutput.c)
- MONTHLY/DAILY outputs only: Add new output structure element(s) to function that allocates memory: src/lpj/newoutput[daily|monthly].c
- Add output identifyer to src/lpj/outputbuffersize.c (mind the correct position!)
- Write away output in corresponding fwriteoutput_* function (e.g. fwriteoutput_monthly.c) ATTENTION! There are 2 functions for monthly and daily outputs, both are needed (one for with river routing, the other for without)
- Add output names to src/lpj/outputvars.c
The order here needs to be consistent with the identifyer numbering. - Fill output structure with values wanted (pay attention to the difference between + and +=) at the appropriate place in the code. Pay attention that the output works for all options (e.g. with and without river routing).
