# lpj.1

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

         SYNOPSIS
              lpjml [-h] [-v] [-vv] [-fpe] [-output {gather|mpi2|buffer}]
              [-outpath dir] [-inpath dir] [-restartpath dir]
              [[-Dmacro[=value]] [-Idir] ...] [filename]

              lpj [-h] [-v] [-vv] [-fpe] [-output {gather|mpi2|buffer}]
              [-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.

         OPTIONS
              -h   display a short help text

              -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.

              -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.

              -output {gather|mpi2|buffer}
                   use the given output method to write data to disk.
                   Valid output methods are gather, mpi2, and buffer. The
                   default output method is gather sending all output to
                   the root task. If memory allocation fails use other
                   output method. Method mpi2 uses MPI-2 parallel file
                   functions, while method buffer stores all output in
                   memory.  If memory allocation fails for buffer use
                   other output method. The option is 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

         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.

              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.

              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, buffer, gather. Used by the MPI
                   version only. 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.

              ERROR002
                   Error initializing climate. Check whether all input
                   files are present.

              ERROR003
                   Error initializing land use, check for missing input
                   file.

              ERROR004
                   Error initializing water use, check for missing input
                   file.

              ERROR005
                   Error initializing grid, check for missing input files.

              ERROR006
                   Error initializing drainage, check for missing input
                   files.

              ERROR007
                   Invalid carbon balance. Internal error

              ERROR008
                   Invalid water balance. Internal error

              ERROR009
                   Negative discharge. Internal error

              ERROR010
                   Negative fire probability. Internal error.

              ERROR011
                   Negative soil moisture. Internal error

              ERROR012
                   Error allocating memory. Rerun parallel program on more
                   MPI tasks to reduce memory per task.

              ERROR013
                   Negative stand fraction. Internal error.

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

              ERROR015
                   List is empty in dellistitem. Internal error.

              ERROR016
                   Index out of range in dellistitem. Internal error

              ERROR017
                   Error in newlanduse. Can be caused by invalid restart
                   file.

              ERROR018
                   Invalid year in 'getco2'. CO2 data file is too short.

              ERROR019
                   Crop fraction >1. Internal error.

              ERROR020
                   No natural stand for deforest. Internal error.

              ERROR021
                   Wrong cultivation type. Internal error.

              ERROR022
                   Invalid discharge. Internal error.

              ERROR023
                   Cannot allocate buffer memory. Rerun program with
                   option '-output mpi2' or '-output gather'. The total
                   amount of memory allocated for the output buffers can
                   be obtained by invoking lpjcheck. The buffer size has
                   to be divided by the number of MPI tasks.

              ERROR024
                   PFT list is not empty in setaside. Internal error.

              ERROR025
                   Negative establishment rate. Internal error.

              ERROR026
                   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.

              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.

         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)

         SEE ALSO
              lpjsubmit(1), lpjcheck(1), cru2clm(1), txt2clm(1),
              grid2clm(1), cft2clm(1), lpjdistribute(1),
              lpjdistribute_river(1), lpjcat(1), lpjprint(1),
              printheader(1), cat2bsq(1), output_bsq(1), lpj_paths.sh(1),
              lpj_paths.csh(1), newpft.sh(1), lpjml.conf(5), lpj.conf(5),
              clm(5)

              The LPJ & LPJmL Web Distribution Portal:
                   http://www.pik-potsdam.de/lpj