Add page for building LIS.

content/applications/app_specific/building_lis.md

++++
+title = "Building LIS"
+description = "How to build NASA LIS on HCC resources."
++++
+
+The [NASA LIS](https://lis.gsfc.nasa.gov/) (Land Information System) software is a framework
+for high performance terrestrial hydrology modeling and data assimilation developed with the
+goal of integrating satellite and ground-based observational data products and advanced modeling
+techniques to produce optimal fields of land surface states and fluxes.
+
+The software suite consists of three modeling components: (1) Land surface Data Toolkit (LDT),
+a formal environment that handles the data-related requirements of LIS including land surface
+parameter processing, geospatial transformations, consistency checks, data assimilation preprocessing,
+and forcing bias correction, (2) Land Information System (LIS), the modeling system that encapsulates
+physical models, data assimilation algorithms, optimization and uncertainty estimation algorithms, and
+high performance computing support, and (3) Land surface Verification Toolkit (LVT), a formal model
+verification and benchmarking environment that can be used for enabling rapid prototyping and
+evaluation of model simulations by comparing against a comprehensive suite of in-situ,
+remote sensing, and model and reanalysis data products.
+
+## Building LIS
+
+Due to the way LIS operates, users are expected to compile it themselves on HCC resources.
+To simplify this process as much as possible, HCC provides an `LIS` module which loads all of
+the needed dependency packages and sets up the build environment. Example outputs showing the
+correct choices for the `configure` scripts are also provided.
+
+{{% notice warning %}}
+The `LIS` module sets the `LIS_`/`LDT_`/`LVT_` build variables to their proper values. Users should
+not set these varibles themselves, nor modify their `~/.profile` files.
+{{% /notice %}}
+
+The following sections assume you have downloaded one of the LIS [releases](https://lis.gsfc.nasa.gov/releases)
+and unpacked it somewhere with sufficient space to work. All commands in each section are run
+starting relative to the top-level directory, denoted here as `<LIS root`>.
+
+### Building LDT
+
+The following example commands show how to compile the Land surface Data Toolkit (LDT).
+
+{{% panel theme="info" header="Building LDT" %}}
+{{< highlight bash >}}
+[demo01@login.crane LISF_public_release_7.3.3]$ ls
+docs  env  ldt  LICENSE.txt  lis  lvt  README.adoc
+[demo01@login.crane ldt]$ module purge
+[demo01@login.crane ldt]$ module load compiler/intel/19 openmpi/4.0 LIS/7.3
+	This module loads the LIS suite (lis,lvt,ldt) build environment.
+	Users are expected to compile LIS themselves.
+	For convenience, example outputs from the configure scripts showing the proper choices are provided by the following variables:
+	$LIS_CONFIG_OUT, $LVT_CONFIG_OUT, $LDT_CONFIG_OUT
+	To view, use the cat command, i.e. 'cat $LIS_CONFIG_OUT'
+[demo01@login.crane ldt]$ make -C make realclean
+make: Entering directory '/lustre/work/demo/demo01/LISF_public_release_7.3.3/ldt/make'
+Makefile:50: configure.ldt: No such file or directory
+make: *** No rule to make target 'configure.ldt'.  Stop.
+make: Leaving directory '/lustre/work/demo/demo01/LISF_public_release_7.3.3/ldt/make'
+[demo01@login.crane ldt]$ ./configure
+------------------------------------------------------------------------
+Setting up configuration for LDT
+Parallelism (0-serial, 1-dmpar, default=0): 1
+Optimization level (-3=strict checks with warnings, -2=strict checks, -1=debug, 0,1,2,3, default=2): 2
+Assume little/big_endian data format (1-little, 2-big, default=2): 2
+Use GRIBAPI/ECCODES? (0-neither, 1-gribapi, 2-eccodes, default=2): 2
+NETCDF version (3 or 4, default=4)?: 4
+NETCDF use shuffle filter? (1-yes, 0-no, default = 1): 1
+NETCDF use deflate filter? (1-yes, 0-no, default = 1): 1
+NETCDF use deflate level? (1 to 9-yes, 0-no, default = 9): 9
+Use HDF4? (1-yes, 0-no, default=1): 1
+Use HDF5? (1-yes, 0-no, default=1): 1
+Use HDFEOS? (1-yes, 0-no, default=1): 1
+Enable GeoTIFF support? (1-yes, 0-no, default=1): 1
+Enable LIBGEOTIFF support? (1-yes, 0-no, default=1): 1
+Include date/time stamp history? (1-yes, 0-no, default=1): 1
+-----------------------------------------------------
+ configure.ldt file generated successfully
+-----------------------------------------------------
+Settings are written to configure.ldt in the make directory.
+If you wish to change settings, please edit that file.
+
+To compile, run the compile script.
+------------------------------------------------------------------------
+[demo01@login.crane ldt]$ ./compile -j 4
+-------------------------------------------------------------------
+Compiling LDT
+
+[INFO] Compiling LDT source code
+...
+<intermediate output omitted for clarity>
+
+[INFO] Compile finished
+-------------------------------------------------------------------
+[demo01@login.crane ldt]$ ls
+ANNdata  compile  configure  DAobs    interp  lib   make        MetforcScale  plugins   statDscale  USAFSI
+arch     configs  core       domains  LDT     main  metforcing  params        runmodes  testcases   utils
+{{< /highlight >}}
+{{% /panel %}}
+
+If the build finishes successfully there will be no error messages and the `LDT` program will be present
+in the directory.
+
+### Building LIS
+
+The following example shows how to compile LIS (Land Information System).
+
+{{% panel theme="info" header="Building LIS" %}}
+{{< highlight bash >}}
+[demo01@login.crane lis]$ module purge
+[demo01@login.crane lis]$ module load compiler/intel/19 openmpi/4.0
+[demo01@login.crane lis]$ module load compiler/intel/19 openmpi/4.0 LIS/7.3
+	This module loads the LIS suite (lis,lvt,ldt) build environment.
+	Users are expected to compile LIS themselves.
+	For convenience, example outputs from the configure scripts showing the proper choices are provided by the following variables:
+	$LIS_CONFIG_OUT, $LVT_CONFIG_OUT, $LDT_CONFIG_OUT
+	To view, use the cat command, i.e. 'cat $LIS_CONFIG_OUT'
+[demo01@login.crane lis]$ make -C make realclean
+make: Entering directory '/lustre/work/demo/demo01/LISF_public_release_7.3.3/lis/make'
+grep: LIS_misc.h: No such file or directory
+Makefile:61: configure.lis: No such file or directory
+make: *** No rule to make target 'configure.lis'.  Stop.
+make: Leaving directory '/lustre/work/demo/demo01/LISF_public_release_7.3.3/lis/make'
+[demo01@login.crane lis]$ ./configure
+------------------------------------------------------------------------
+Setting up configuration for LIS
+Parallelism (0-serial, 1-dmpar, default=1): 1
+Optimization level (-3=strict checks with warnings, -2=strict checks, -1=debug, 0,1,2,3, default=2): 2
+Assume little/big_endian data format (1-little, 2-big, default=2): 2
+Use GRIBAPI/ECCODES? (0-neither, 1-gribapi, 2-eccodes, default=2): 2
+Enable AFWA-specific grib configuration settings? (1-yes, 0-no, default=0): 0
+Use NETCDF? (1-yes, 0-no, default=1): 1
+NETCDF version (3 or 4, default=4): 4
+NETCDF use shuffle filter? (1-yes, 0-no, default = 1): 1
+NETCDF use deflate filter? (1-yes, 0-no, default = 1): 1
+NETCDF use deflate level? (1 to 9-yes, 0-no, default = 9): 9
+Use HDF4? (1-yes, 0-no, default=1): 1
+Use HDF5? (1-yes, 0-no, default=1): 1
+Use HDFEOS? (1-yes, 0-no, default=1): 1
+Use MINPACK? (1-yes, 0-no, default=0): 1
+Use LIS-CRTM? (1-yes, 0-no, default=0): 0
+Use LIS-CMEM? (1-yes, 0-no, default=0): 0
+Use LIS-LAPACK? (1-yes, 0-no, default=0): 1
+Use LIS-MKL-LAPACK? (1-yes, 0-no, default=0): 1
+-----------------------------------------------------
+ configure.lis file generated successfully
+-----------------------------------------------------
+Settings are written to configure.lis in the make directory.
+If you wish to change settings, please edit that file.
+
+To compile, run the compile script.
+------------------------------------------------------------------------
+[demo01@login.crane lis]$ ./compile -j 4
+-------------------------------------------------------------------
+Compiling LIS
+
+[INFO] Compiling LIS source code
+...
+<intermediate output omitted for clarity>
+
+[INFO] Compile finished
+-------------------------------------------------------------------
+[demo01@login.crane lis]$ ls
+apps  compile  configure  dataassim  forecast  irrigation  LICENSES  make        offline  params   RESTRICTED  rtms      surfacemodels  utils
+arch  configs  core       domains    interp    lib         LIS       metforcing  optUE    plugins  routing     runmodes  testcases
+{{< /highlight >}}
+{{% /panel %}}
+
+If the build finishes successfully there will be no error messages and the `LIS` program will be present
+in the directory.
+
+### Building LVT
+
+The following example commands show how to compile the Land surface Verification Toolkit (LVT).
+
+{{% panel theme="info" header="Building LVT" %}}
+{{< highlight bash >}}
+[demo01@login.crane LISF_public_release_7.3.3]$ ls
+docs  env  ldt  LICENSE.txt  lis  lvt  README.adoc
+[demo01@login.crane LISF_public_release_7.3.3]$ cd lvt
+[demo01@login.crane lvt]$ module purge
+[demo01@login.crane lvt]$ module load compiler/intel/19 openmpi/4.0 LIS/7.3
+	This module loads the LIS suite (lis,lvt,ldt) build environment.
+	Users are expected to compile LIS themselves.
+	For convenience, example outputs from the configure scripts showing the proper choices are provided by the following variables:
+	$LIS_CONFIG_OUT, $LVT_CONFIG_OUT, $LDT_CONFIG_OUT
+	To view, use the cat command, i.e. 'cat $LIS_CONFIG_OUT'
+[demo01@login.crane lvt]$ make -C make realclean
+make: Entering directory '/lustre/work/demo/demo01/LISF_public_release_7.3.3/lvt/make'
+Makefile:50: configure.lvt: No such file or directory
+make: *** No rule to make target 'configure.lvt'.  Stop.
+make: Leaving directory '/lustre/work/demo/demo01/LISF_public_release_7.3.3/lvt/make'
+[demo01@login.crane lvt]$ ./configure
+------------------------------------------------------------------------
+Setting up configuration for LVT
+Optimization level (-3=strict checks with warnings, -2=strict checks, -1=debug, 0,1,2,3, default=2): 2
+Assume little/big_endian data format (1-little, 2-big, default=2): 2
+Use GRIBAPI/ECCODES? (1-gribapi, 2-eccodes, default=2): 2
+Use NETCDF? (1-yes, 0-no, default=1): 1
+NETCDF version (3 or 4, default=4): 4
+NETCDF use shuffle filter? (1-yes, 0-no, default = 1): 1
+NETCDF use deflate filter? (1-yes, 0-no, default = 1): 1
+NETCDF use deflate level? (1 to 9-yes, 0-no, default = 9): 9
+Use HDF4? (1-yes, 0-no, default=1): 1
+Use HDF5? (1-yes, 0-no, default=1): 1
+Use HDFEOS? (1-yes, 0-no, default=1): 1
+Enable AFWA-specific grib configuration settings? (1-yes, 0-no, default=0): 0
+Enable GeoTIFF support? (1-yes, 0-no, default=1): 1
+Use MATLAB support? (1-yes, 0-no, default=0): 0
+-----------------------------------------------------
+ configure.lvt file generated successfully
+-----------------------------------------------------
+Settings are written to configure.lvt in the make directory.
+If you wish to change settings, please edit that file.
+
+To compile, run the compile script.
+------------------------------------------------------------------------
+[demo01@login.crane lvt]$ ./compile -j 4
+-------------------------------------------------------------------
+Compiling LVT
+
+[INFO] Compiling LVT source code
+...
+<intermediate output omitted for clarity>
+
+[INFO] Compile finished
+-------------------------------------------------------------------
+[demo01@login.crane lvt]$ ls
+arch  compile  configs  configure  core  datastreams  domains  interp  LVT  main  make  metrics  plugins  runmodes  testcases  training  utils
+{{< /highlight >}}
+{{% /panel %}}
+
+If the build finishes successfully there will be no error messages and the `LVT` program will be present
+in the directory.
+
+## Running LIS
+
+Example scripts for running LIS/LVT/LDT are provided [here](https://github.com/unlhcc/job-examples/tree/master/LIS).