lpjml(1)

NAME
lpj, lpjml - Dynamic global vegetation model with managed land and river routing

SYNOPSIS
lpjml [-h] [-l] [-v] [-vv] [-param] [-pp cmd] [-fpe] [-image host[:inport[,outport]]] [-wait time] [-output {write|gather|mpi2|socket=hostname[:port]}] [-outpath dir] [-inpath dir] [-restartpath dir] [[-Dmacro[=value]] [-Idir] ...] [filename] lpj [-h] [-l] [-v] [-vv] [-param] [-pp cmd] [-fpe] [-image host[:inport[,outport]]] [-wait time] [-output {write|gather|mpi2|socket=hostname[:port]}] [-outpath dir] [-inpath dir] [-restartpath dir] [[-Dmacro[=value]] [-Idir] ...] [filename]

DESCRIPTION
The model simulates vegetation dynamics, hydrology and soil organic matter dynamics on an area-averaged grid cell basis using one-year time step. The name derives from the three locations Lund-Potsdam-Jena but is no longer to be interpreted that way. Input parameters are monthly mean air temperature, total precipitation and percentage of full sunshine, annual atmospheric CO2 concentration and soil texture class. The simulation for each grid cell begins from "bare ground", requiring a "spin up" (under non-transient climate) of c. 1000 years to develop equilibrium vegetation and soil structure. A restart file can be created to save compute time for the spin-up phase. If the Message Passing Interface (MPI) library is available a parallel version of the program is built. If -DIMAGE flag is set in Makefile.inc coupling the IMAGE model via the TDT library is enabled.

OPTIONS

-h  print a short help text

-l  print the license file

-v  print information about program version, operating system, compiler used, and compiler flags set.

-vv verbosely print the actual values during reading of the configuration files.

-param
    print LPJmL parameter for soils and PFTs.

-pp cmd
    set preprocessor program to cmd. Default is cpp -P.

-fpe
    enable floating point exceptions. A core file is generated in case of an arithmetic error. Option is only available if lpjml has been compiled with -DWITH_FPE flag.

-image host[:inport[,outport]]
    set host where IMAGE model is running. Default is localhost. inport and outport are the port numbers for ingoing and outgoing data. Default port numbers are 2225 and 2224, respectively. This option is only available for the IMAGE version of the code.

-wait time
    set time to wait for connection to IMAGE model. Time is measured in seconds. Default value is 10 sec. This option is only available for the IMAGE version of the code.

-output {gather|mpi2|socket=hostname[:port]]}
    use the given output method to write data to disk or to a output channel. Valid output methods are write, gather, mpi2, and socket. The default output method for the MPI version is gather sending all output to the root task, while the default method is write for the sequential version of the code. Method mpi2 uses MPI-2 parallel file functions, while output method socket sends output data via a TCP/IP socket to a remote host hostname. Default port is 2222. lpjliveview is a program to display output variables on a X11 display at run time. The mpi2 and gather output methods are only valid for the MPI version of the code.

-outpath dir
    set the output directory path. The path is added to the output filenames if they do not contain an absolute path.

-inpath dir
    set the input directory path. The path is added to the input filenames if they do not contain an absolute path.

-restartpath dir
    set the restart directory path. The path is added to the restart filenames if they do not contain an absolute path.

-Dmacro[=value]
    define macro for the preprocessor of the configuration file

-Idir
    define include directory for the preprocessor of the configuration file

filename
    name of configuration file, default is lpjml.conf for lpjml and lpj.conf for lpj.

EXAMPLES

Perform simulation with input from the /scratch file system:
    lpjml -inpath /scratch/02/lpj

Perform simulation with output sent to host aix:
    lpjml -output socket=aix

Start simulation from restart file with floating point exceptions enabled:
    lpjml -DFROM_RESTART -fpe lpjml.conf

For running the MPI version of the program on more than one task the lpjsubmit script has to be used.

ENVIRONMENT

LPJCONFIG
    default LPJmL configuration filename

LPJPREP
    defines preprocessor command for LPJmL configuration file, default is cpp -P. Same as '-pp' option.

LPJROOT
    defines the root directory for LPJmL. This directory is added to the include directories of the preprocessor. Invoking lpj_paths.sh or lpj_paths.csh will set this environment variable correctly.

LPJIMAGE
    sets the host where IMAGE model is running. Same as '-image' option.

LPJWAITIMAGE
    sets time to wait for connection to IMAGE model. Same as in '-wait' option.

LPJINPATH
    path appended to the input filenames. Only done for filenames without absolute path. Same as '-inpath dir' option.

LPJOPTIONS
    runtime options for the preprocessor of LPJmL configuration files

LPJOUTPATH
    path appended to the output filenames. Only done for filenames without absolute path. Same as '-outpath dir' option.

LPJRESTARTPATH
    path appended to the restart filenames. Only done for filenames without absolute path. Same as '-restartpath dir' option.

LPJOUTPUT
    default method for generating output files. Valid values are mpi2, gather, and socket. Same as '-output method' option.

EXIT STATUS
lpjml and lpj returns a zero exit status if the simulation finishes successfully. Non zero is returned in case of failure.

DIAGNOSTICS
On error the program prints the following message on stderr: ERRORxxx: message, program terminated unsuccessfully where xxx is the return code of the program. The following error codes are defined:

ERROR001
    Error reading configuration. Check syntax of configuration file. External error

ERROR002
    Error initializing input. Check whether all input files are present. External error

ERROR003
    Error initializing grid, check for missing input files. External error

ERROR004
    Invalid carbon balance. Internal error

ERROR005
    Invalid water balance. Internal error

ERROR006
    Negative discharge. Internal error

ERROR007
    Negative fire probability. Internal error.

ERROR008
    Negative soil moisture. Internal error

ERROR009
    Error allocating memory. Rerun parallel program on more MPI tasks to reduce memory per task. External error

ERROR010
    Negative stand fraction. Internal error.

ERROR011
    Stand fraction sum error. Can be caused by invalid restart file. External error

ERROR012
    List is empty in dellistitem(). Internal error.

ERROR013
    Index out of range in dellistitem(). Internal error

ERROR014
    Error in newlanduse(). Can be caused by invalid restart file. External error

ERROR015
    Invalid year in getco2(). CO2 data file is too short. External error

ERROR016
    Crop fraction >1. Internal error.

ERROR017
    No natural stand for deforest(). Internal error.

ERROR018
    Wrong cultivation type. Internal error.

ERROR019
    Floating point error occurred. Floating point exceptions will only be thrown if -fpe option is set. This is in particular useful if NaNs appear in the output files. Internal error.

ERROR021
    PFT list is not empty in setaside(). Internal error.

ERROR022
    Negative establishment rate. Internal error.

ERROR023
    Output channel is broken. This error is only raised if '-output socket' option is set. It is usually caused by a premature end of the corresponding live view program. External error.

ERROR024
    Error sending data to the IMAGE model. This error can only be raised if LPJmL is compiled with the -DIMAGE flag set in Makefile.inc. External error.

ERROR025
    Error opening connection to IMAGE model. This error can only be raised if LPJmL is compiled with the -DIMAGE flag set in Makefile.inc. External error.

ERROR026
    Not enough setaside stand created to put the reservoir. Internal error.

ERROR027
    Forest left after deforestation. Internal error.

ERROR028
    Outflow reservoir error. Internal error.

ERROR029
    Error in permafrost module. Internal error. -TP ERROR030 Error in global water balance. Internal error.

ERROR031 Error in store climate function. ERROR032 No FMS coupler supported. Internal errors will generate a core dump and have to be fixed by changes in the code. A "post-mortem" analysis can be made by calling gdb $LPJROOT/bin/lpjml core It is recommended to compile the code without optimization and inlining making the inspection of the core file easier. Configure in $LPJROOT with
configure.sh -debug
make clean
make
will do the job. If no core file is generated set the user limit for core files: ulimit -c unlimited Some of these errors are only raised if the -DSAFE flag has been set in Makefile.inc. The flags set at compile time can be obtained by invoking lpjml -v. After the core file has been created a backtrace of the failed program can be obtained by calling backtrace Without any arguments lpjml will be inspected and the call tree displayed using the core file in the working directory.

AUTHORS
Werner von Bloh (Werner.von.Bloh@pik-potsdam.de), Sibyll Schaphoff (Sibyll.Schaphoff@pik-potsdam.de), Stefanie Rost (Jachner) (Stefanie.Rost@pik-potsdam.de), Marlies Gumpenberger (Marlies.Gumpenberger@pik-potsdam.de), Tim Beringer (Erbrecht) (Tim.Beringer@pik-potsdam.de), Christoph Mueller (Christoph.Mueller@pik-potsdam.de), Jens Heinke (Jens.Heinke@pik-potsdam.de), Hester Biemans (Hester.Biemans@wur.nl), Kirsten Thonicke (Kirsten.Thonicke@pik-potsdam.de), Ursula Heyder (Ursula.Heyder@pik-potsdam.de),

COPYRIGHT
(C) Potsdam Institute for Climate Impact Research (PIK), see COPYRIGHT file

SEE ALSO
lpjsubmit(1), lpjcheck(1), lpjliveview(1), configure.sh(1), backtrace(1), cru2clm(1), txt2clm(1), grid2clm(1), cft2clm(1), lpjcat(1), lpjprint(1), printharvest(1), printclm(1), printheader(1), cat2bsq(1), output_bsq(1), lpj_paths.sh(1), lpj_paths.csh(1), lpjml.conf(5), lpj.conf(5), lpjml_image.conf(5), clm(5)

Contact: https://gitlab.pik-potsdam.de/lpjml/lpjml