# 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

         enabled:
              Start simulation from restart file with floating point exceptions
                   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