nasa-lis / nasa-land-coupler

NASA Land Coupler

NASA Land Coupler

Coupled surface-hydrology application with data assimilation.

Components

NASA Land Coupler Driver and Mediator: The NASA Land Coupler driver and mediator have been designed in collaboration by NOAA, NASA, and NCAR. The custom driver couples LIS and WRF-Hydro within the NUOPC framework. Coupled system configuration is controlled via settings in the nlc.runconfig file. The custom mediator couples an in memory ensemble to multiple instances of a component, which allows users to run a coupled ensemble entirely in memory. Each component is individually configured based on the needs of the component (see documentation for each component).

Land Information System (LIS): LIS is a land surface modeling framework devloped by NASA.
Documentation: https://lis.gsfc.nasa.gov/
Repository: https://github.com/NASA-LIS/LISF

WRF-Hydro: WRF-Hydro is a hydrometeorological and hydrologic modeling system developed by the research applications labratory at NCAR.
Documentation: https://ral.ucar.edu/projects/wrf_hydro/overview
Repository: https://github.com/NCAR/wrf_hydro_nwm_public

SSH keys

We are using ssh URLs for cloning submodules, so you will need to ensure that you have added your public SSH key from your platform (Discover and/or Cheyenne) to your GitHub account. Help is available here: https://help.github.com/articles/connecting-to-github-with-ssh/

Clone Instructions

These have been tested on Discover (NASA) and Cheyenne (NCAR).

Clone the repository including the submodules.

$ git clone --recursive [email protected]:NESII/lishydro.git <directory>

LIS and WRF-Hydro are included as git submodules. The following commands provide an alternative to using the --recursive git clone option.

$ cd <directory>        # go into the cloned repository
$ git submodule init
$ git submodule update

Prerequisites

System requires ESMF v8.0.1 or later.

Build Instructions

Configure Submodules Configure LIS and WRFHYDRO using the configure.sh script. For more information run ./configure.sh --help.

$ ./configure.sh

Build Application Build NASA Land Coupler (NLC) using the build.sh script. For more information run ./build.sh --help. NLC.exe will be installed into src/driver.

$ ./build.sh

Run Instructions

NOTE: Runs are currently only supported on Discover and Cheyenne.

Use cases are preconfigured using settings in usecases directory and preprocessed data. Input data, including configuration, domain, and parameter files, is stored on Discover and Cheyenne

Current supported use cases:

Use Cases	Description
coupled_irene.noahmp.nldas2	Coupled LIS-WRFHYDRO Hurricane Irene NoahMP v3.6
coupled_irene.noah.nldas2	Coupled LIS-WRFHYDRO Hurricane Irene Noah v3.6
coupled_irene_noMed.noah.nldas2	Directly Coupled LIS-WRFHYDRO Hurricane Irene (No MED)
coupled_tar.noahmp_v4.0.1_cold.nldas2	Coupled LIS-WRFHYDRO Tar River NoahMP v4.0.1
coupled_tuolumne.ens002.noahmp.nldas2	Coupled LIS-WRFHYDRO Tuolumne NoahMP v4.0.1 Ensemble
coupled_tuolumne.ens020.noahmp_v4.0.1_da.nldas2	Coupled LIS-WRFHYDRO Tuolumne NoahMP v4.0.1 Ensemble with DA
coupled_tuolumne.noahmp.nldas2	Coupled LIS-WRFHYDRO Tuolumne NoahMP v3.6
coupled_tuolumne.noahmp_v4.0.1_cold.nldas2	Coupled LIS-WRFHYDRO Tuolumne NoahMP v4.0.1
coupled_tuolumne.noahmp_v4.0.1_da.nldas2	Coupled LIS-WRFHYDRO Tuolumne NoahMP v4.0.1 with DA
coupled_tuolumne.noah.nldas2	Coupled LIS-WRFHYDRO Tuolumne Noah v3.6
coupled_tuolumne_noMed.noah.nldas2	Directly Coupled LIS-WRFHYDRO Tuolumne (No MED)
sbys_tuolumne_hyd.ens002.ldas	Uncoupled LIS-WRFHYDRO Tuolumne Ensemble (2 member)
stdalone_frontrange_hyd.ldas	Standalone WRFHYDRO Frontrange
stdalone_irene_lnd.nldas2	Standalone LIS Hurricane Irene
stdalone_tuolumne_hyd.ldas	Standalone WRFHYDRO Tuolumne

Setup Run Directory Preconfigured use cases can be set up using the setuprun.sh script. For more information run ./setuprun.sh --help. For a list of use cases run ./setuprun.sh --list-usecases.

$ ./setuprun.sh USECASE

This will create and populate a run directory in run/<usecase>.

Submit Run

The batch script run.sh can be modified if needed, for example to change the number of MPI tasks or the project number.

$ cd run/<usecase>
$ sbatch run.sh   # Discover - SLURM
$ qsub run.sh     # Cheyenne - PBS

This will submit the run to the batch queue. Output will appear in the same directory.