1. INSTALLATION

- see INSTALL in the LPJ distribution

2. INPUT

- general input
  a) gridfile [deg*100] 
  in C data type short (2 bytes), lon lat for each pixel
  defines the extent of your input data
- climate input:
  monthly values for:
  a) precipitation [mm/month]
  b) air temperature [°C*10]
  c) "cloudiness" [%] for internal computation of radiation
  d) number of wet days per month (needed only, if your are using the "weather generator", see below)
  all in C data type short (2 bytes) with a binary climate header (*.clm format)
  data needs to be stored in the same order as the input grid
  Data can be converted to clm from plain binary input files (BIP) with the binary cru2clm that has been provided with the LPJ distribution.
  In case you want to look at *.clm input files:
  - use freadheader(...) to read the climate header
  - data is either stored as "YEARCELL" (band interleaved by pixel) or "CELLYEAR" (a mixture between BIP/BSQ, check in the code of cru2clm.c if you really need to know the format)
- CO2
  global annual mean CO2 concentration as ASCII file
  format: year concentration
- soil input:
  in C 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
- land use:
  in C data type short (2 bytes), the grid needs to be the same as your input grid / climate data
  values range between 0 and 1000 (fraction *1000)
  each grid cell and year has 24 entries: 12 for rain-fed crops, 12 for irrigated crops
  crop oder is as follows:
  1: temperate cereals, 2: rice, 3: maize, 4: tropical cereals, 5: pulses,
  6: temperate roots, 7: tropical roots, 8: oil crops sunflower, 9: oil crops soybean,
  10: oil crops groundnut, 11: oil crops rapeseed, 12: pasture (C3/C4 mix left to LPJmL to determine)
- country codes:
  in C data type short (2 bytes)
  for each cell two values: countrycodes (n=197) and regioncodes (n=433)
- river routing:
  in C data type short (2 bytes), the grid needs to be the same as your input grid / climate data
  for each cell two values: one in which cell to rout the water  
                            one with the distance [km] between the midpoints of the two cells
  -9: inland sink or outflow to the ocean
- parameter files
  a) pft parameters
  b) soil parameters
  c) management parameters
  see sample files provided

3. HOW TO RUN IT - FIRST STEPS

- If lpjml is started from a different directory than the root directory set environemnt variable LPJROOT:
  export LPJROOT=<lpjml root directory>
- change lpjml.conf to specify 
  - 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
- change cru*.conf for the location of most of the input data (climate / grid / management / landuse/ routing)

4. FLAGS FOR RUNNING LPJ

switch flags by calling lpjml -DFLAG, e.g lpjml -DISRANDOM
ISRANDOM: switches on the weather generator
RIVER_ROUTING: without flag: no routing, potential irrigation
               with flag: routing, irrigation depends on available water in the rivers
FROM_RESTART: a restart-file is generated at the end of each LPJ run. Set this flag to restart from this point (which might be useful e.g. to start multiple runs from the same spin-up run)

5. COMPILER FLAGS

Compiler flags need to be set in Makefile.inc, and you have to call "make clean all" to recompile afterwards
add -DFLAG to the line specifying CFLAGS
USE_MPI: compile with message passing parallelism enabled
SAFE: Some consistency checks are enabled. 
USE_RAND48: using drand48() random number generator instead of generatore defined in libnum.a 
DEBUG: include lots of print statements in the code
LANDUSE: so far only in the LPJ_SPEEDY branch. Includes all land-use specific routines, especially the memory allocation to the cropdates and the landuse structure.

6. RUNNING IT IN PARALLEL

The MPI version of the code can be run on an arbitrary number of processors with and
without river routing. For PIK cluster job control file *.jcf are provided for the
LoadLeveler batch system.

Without MPI use distribute.sh to create command files for the PIK cluster and *.conf 
files for each package.  The matrix is split into packages of pixels; each package
 can be run separately 
If you are using PIK's cluster, change the parameters for the command file and the lines of the *.conf files as necessary. If you run LPJ outside PIK, adapt the script accordingly.
You need a different script if you want to use river routing

7. RUNNING IT IN RIVER-ROUTING MODE

For a global run packages for input are already generated
see /data/biosx02/input_clm/input_river/README for more informations
use distribute_river.sh to send it to the cluster

8. WHAT IS THE OUTPUT?

a) see  http://portal.pik-potsdam.de/members/erbrecht/lpj-how-to-s for a tutorial how to add/remove output files 
b) output file formats
   grid.out: short (2 bytes) plain binary, lon lat [deg*100]; this may be different from the input grid, as it only contains those pixels with a soilcode > 0
   all other output files: 
   plain binary (BSQ), data type float (4 bytes) 
   output files that start with "m" are monthly output and have thus 12 bands per year
   fpc is calculated for each pft from the natural vegetation, the first band contains the fraction of natural vegetation, pfts follow in the order they occur in pft.par. If you have 9 pfts, you'll have 10 bands output per year.
   agricultural output??
c) some common output variables:
  - fpc: foliage projected cover in %
  - firef: fire return intervall, calculated as 1/(fraction of gridcell burned this year)
  - firec
  - vegc, litc, soilc: carbon pools in ?
  - mnpp: monthly net primary production in ?
  - mrh: monthly respiration in ?

9. HOW TO HANDLE OUTPUT FILES?
a) 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
b) creating 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 input grid ... ;-)
c) see next point on how to read binary data

10. READING BINARY FILES

 - quite simple with any programming language, once you know how the data is stored (as described under point 8b, but see below for byte order issues)
 - most image processing programs have an option to import binary data (but they usually need it in a rectangular grid, see point 9 b)
 - R can read binary data
 - 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 write a program that converts the output data to ASCII (or use the respective function of a different software package)

11. ABOUT BYTE ORDERING / ENDIANNESS

   if you get strange errors (such as really unsensible values for your output data) when reading binary data, one reason might be that the data has been written on a different system architecture than the one you are using for reading it, and that those systems - just bad luck - store data internally in a different byte order. You might use the functions in src/tools/swap.c to change the byte order if you are programming in C, and there are many examples in other languages on the web. Those functions should work fine for all integer data types (i.e. short/int/long in C/C++), and you don't need to think about char data, as it is one byte only. Things get more complicated if you look at floating point data types: additionally to byte order issues the internal representation of the number might be different. You are on the safe side if you avoid reading binary floating point data from a different architecture. However, most systems seem to follow the IEEE floating point standard, so you might be lucky using the integer byte swapping functions.
