Environment variables
================

A number of optional features can be enabled via the definition of environment variables.
Most variables (unless noted otherwise) must have values of 0 (off) or 1 (on).

Environment variables can be set in 2 ways:

1) add a statement to $HOME/.bashrc, which will be used for all runs
export INLAND_VAR=value

2) add the statement for each inland execution
INLAND_VAR=value ./inland_grid


These variables control the format of output netcdf files (grid model only)

INLAND_SINGLE_PRECISION : if 0 write netcdf files with double precision (default 1, write in single precision)
INLAND_COMPRESSOUT : write netcdf files with zlib compression (requires netCDF-4 format with HDF5)
                     valid values are 0 (no compression) or 1-9 (compression level), 2 is recommended
                     see http://www.unidata.ucar.edu/software/netcdf/docs/netcdf/NetCDF_002d4-Format.html
INLAND_CHUNKOUT  : define compressed variable chunking (default 0, use netcdf default)
                   use this only if your data viewer has problems with default chunking parameters

These variables are for defining the locations of input/output files, used mainly in a supercomputing environment

INLAND_INDIR     : the location of input files, which contains parameter definition (default is ./data/offline/grid)
INLAND_INFILE    : the location of the inland_grid.infile (default is $INLAND_INDIR/inland_grid.infile)
INLAND_DATADIR   : the location of the data directory, which contains climate files (default is ./input)
INLAND_OUTDIR    : the location of the output directory (default is ./output)

These variables are for development and debugging purposes only, use at your risk!

INLAND_DEBUG     : show verbose output, increasing values give more output (default 0, no verbose output)
INLAND_RANDOMVAL : set all random values to a fixed value (valid values are between 0 and 1 ; default 0, use random values)
INLAND_FASTEXEC  : run model in fast mode (default 0, normal execution)
                   if 1 runs only 1 day per year, if 2 bypasses lsxmain call

Subgrid Tiling
================

Subgrid Tiling is an optional feature of Inland.
TODO : add more explanations (theoretical basics, input files, tile dimension in output files)


- The following entries in conf/inland-grid.infile control subgrid tiling.

! subgrid tile parameters - ignore if not using subgrid tiles
mlpt       = 1        , ! mlpt - multiplicity of land points (subgrid tiles) (default 1, no tiles)
vegtypefile= ""       , ! file to read initial vegtype (and tileprop if mlpt>1) (default '', read default)
hrmapfile  = ""       , ! hrmapfile - read high-res data to produce initial veg map (default '', don't read)


- vegtype files must contain the following:
  - vegtype variable with mlpt levels + 1 for water (vegtype 30)
  - tilefrac variable with mlpt levels + 1 for water fraction


- vegtype files with tiles can be created using contrib/inland-maketiles.sh contributed script

# see inland-maketiles.sh for more information and examples

# these commands create files with a second tile where forest(1) and cerrado(9) are replaced by pasture(18) in varying proportions (10, 25 and 50%) 
inland-maketiles.sh vegtype.nc vegtype-deforest-10p.nc 2 0.90 0.10 0.0 "" "setvals,1,18,9,18" ""
inland-maketiles.sh vegtype.nc vegtype-deforest-25p.nc 2 0.75 0.25 0.0 "" "setvals,1,18,9,18" ""
inland-maketiles.sh vegtype.nc vegtype-deforest-50p.nc 2 0.50 0.50 0.0 "" "setvals,1,18,9,18" ""

# a simple example with 2 identical tiles and second tile has 0 tilefrac values (used as a template)
inland-maketiles.sh vegtype.nc vegtype-mlpt02-equal.nc 2 1 0 0 "" "" ""
# another simple example with 2 different tiles and 10% waterfrac
inland-maketiles.sh vegtype.nc vegtype-mlpt02-diff.nc 2 0.75 0.25 0 "" "setvals,1,9,9,11,11,14" ""


- how to combine hrmap output with a global vegtype file?

# first make a "fastexec" run with hrmapfile set in infile
make && INLAND_FASTEXEC=2 ./inland-grid 
# then combine the output tile file with template vegtype-mlpt02-equal.nc
cd output
cdo -O selname,vegtype,tilefrac inland-tiles-1980.nc tmp1.nc
cdo -O mergegrid ../input/tiles/vegtype-mlpt02-equal.nc tmp1.nc ../input/tiles/vegtype-mlpt02-hrmap.nc
# finally can remove hrmapfile in infile, and vegtypefile="tiles/vegtype-mlpt02-hrmap.nc"


- data analysis

cdo does not support 5D vars, therefore files with pft dimensions (such as inland-yearly-pft-????.nc) 
cannot be handled directly by cdo. However, grads software has no problem with these files.

The following command can split the file by tile number (assuming 2 tiles with 1 extra for average):
for y in `seq 1981 1982` ; do for t in `seq 1 3` ; do if=inland-yearly-pft-${y}.nc ; of=inland-yearly-pft-t${t}-${y}.nc; ncks -O -d tile,$((t-1)) ${if} ${of} ; ncwa -O -a tile ${of} ${of} ; done ; done



Agro Model
================

In each point, only natural vegetation or a single crop are allowed to exist.
Currently there are 4 crops, with corresponding codes (as defined by pft# in params/vegetation)
13: soybean / 14: maize / 15: wheat / 16: sgc 

Two variables describe the crop present at each grid point: 
  - landusetype (=2 when a crop is present)
  - croptype, the number of the crop

The agro model can run in 2 modes, as defined by the value of isimagro in inland-grid.infile.

1) unique crop (isimagro = 1)

   The value of icroptype defines the crop present in all points.

2) defined by data read in cropsfile (isimagro = 2)

   The file defined by the cropsfile variable is read to assign crops to all points.
   The script contrib/merge_monfreda.sh can be used to prepare such a file.

   This must be used in conjunction with mlpt>1 (i.e. using subgrid tiling).
   The first subgrid tile is always natural vegetation (landusetype=1).
   Other subgrids (and their corresponding tile fractions) are assigned from data in cropsfile.

   If mlpt = 1 + #crops (currently 4) 
     A subgrid tile is created for each crop, in order of pft#,
     which implies that e.g. subgrid #2 is always soybean(13).

   Else 
     For each point a subgrid tile is created for all crops present in that point,
     in decreasing order, based on tile fraction.