Home

Welcome to the UFS offline Land Data Assimilation (DA) System Wiki!

This repository contains the model code and external links needed to build the UFS offline Land DA System. The system includes a user-friendly workflow (land-offline_workflow) that combines the Noah-MP land surface model (LSM) with data assimilation capabilities.

Getting Started

Before running the Land DA System, users should determine which of the four levels of support is applicable to their system. Generally, Level 1 & 2 systems are restricted to those with access through NOAA and its affiliates. These systems are named (e.g., Hera, Orion, Cheyenne). However, most users can take advantage of containers to operate Land DA on any system.

Users will also need data to run an experiment. Sample data for the most recent release is publicly available via the Land DA data bucket.

Quick steps for building and running Land DA

Hera & Orion (Level 1 systems)

The locations of pre-staged data on Hera and Orion:

Platform	Data Location
Hera	/scratch1/NCEPDEV/nems/role.epic/landda/inputs
Orion	/work/noaa/epic-ps/role-epic-ps/landda/inputs
Jet	/mnt/lfs4/HFIP/hfv3gfs/role.epic/landda/inputs
Cheyenne	/glade/work/epicufsrt/contrib/landda/inputs

For example, on Hera, users can follow:

 mkdir /path/to/landda
 cd /path/to/landda
 export LANDDAROOT=`pwd`
 ln -s  /scratch1/NCEPDEV/nems/role.epic/landda/inputs . 
 git clone -b release/public-v1.1.0 --recursive https://github.com/ufs-community/land-DA_workflow.git
 cd $LANDDAROOT/land-DA_workflow
 module use modulefiles
 module load landda_hera.intel 
 mkdir build
 cd build
 ecbuild ..
 make -j 8
 cd ..
 ./do_submit_cycle.sh settings_DA_cycle_gdas

Note that before submitting a job, users may need to navigate back to the land-DA_workflow and check that the account/partition is correct in submit_cycle.sh and comment out line 5 in settings_DA_cycle_gdas.

Using a Singularity Container

1. NOAA RDHPCS Systems

On most NOAA RDHPCS systems, a container named ubuntu20.04-intel-ue-landda-v1.1.0.img has already been built, and users may access the container at the locations:

Machine	File Location
Hera	/scratch1/NCEPDEV/nems/role.epic/containers
Orion	/work/noaa/epic-ps/role-epic-ps/containers
Cheyenne	/glade/scratch/epicufsrt/containers
Jet	/mnt/lfs4/HFIP/hfv3gfs/role.epic/containers

For example, on Hera, users can follow:

 mkdir /path/to/landda
 cd /path/to/landda
 export img=/scratch1/NCEPDEV/nems/role.epic/containers/ubuntu20.04-intel-ue-landda-v1.1.0.img
 ln -s /scratch1/NCEPDEV/nems/role.epic/landda/inputs .
 module load intel/2022.1.2 impi/2022.1.2
 singularity exec -H $PWD $img cp -r /opt/land-DA_workflow .
 cd land-DA_workflow/
 sed -i 's|hera.internal|hera.sing|g' settings_DA_cycle_gdas
 source do_submit_test.sh

Note that before submitting a job, users may need to navigate back to the land-DA_workflow and check that the account/partition is correct in submit_cycle.sh. For Orion and Jet, users can still follow the above steps and only need to check that the BASELINE option is correct in settings_DA_cycle_gdas. The correct baselines for Orion/Jet are orion.sing and 'jet.sing', respectively.

2. NOAA Cloud Systems

Users can build and run Land DA on NOAA Cloud systems (i.e., GCP, AWS, and Azure). For example, on GCP, users can follow:

 sudo systemctl start docker
 mkdir /path/to/landda
 cd /path/to/landda 
 export img=/contrib/EPIC/containers/ubuntu20.04-intel-ue-landda-v1.1.0.img
 ln -s /contrib/EPIC/landda/inputs .
 module load intel/2022.1.2 impi/2022.1.2
 singularity exec -H $PWD $img cp -r /opt/land-DA_workflow .
 cd land-DA_workflow/
 sed -i 's|hera.internal|gcp.sing|g' settings_DA_cycle_gdas
 export USE_SINGULARITY=yes
 source do_submit_test.sh

Note that before submitting a job, users may need to navigate back to the land-DA_workflow and check that the account/partition is correct in submit_cycle.sh. For AWS and Azure, users can still follow the above steps and only need to check that the BASELINE option is correct in settings_DA_cycle_gdas. The correct baselines for AWS/Azure are aws.sing and 'azure.sing', respectively.

Documentation and User Support

The UFS offline Land DA System User's Guide has the most comprehensive information on the Land DA System. Users may need different versions of the User's Guide depending on their goals:

Version	Description
Release v1.1.0	Documentation for the v1.1.0 release.
Release v1.0.0	Documentation for the v1.0.0 release.
Develop Branch/Latest	Documentation for the head of the development branch. This may have gaps and errors.

Users who only need to check out the latest code or certain tags can clone the repository without having a GitHub account:

% git clone https://github.com/ufs-community/land-DA_workflow.git
% cd  land-DA_workflow
% git checkout develop (or tags)
% git submodule update --init --recursive

Users can also get expert help through the GitHub Discussions forum.