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-DA_workflow) combining the Noah-MP land surface model (LSM) and 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/role-epic/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

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.

Hierarchical Repository Structure

The UFS land-DA_workflow repository contains several subrepositories. It contains land-DA, ufs-land-driver, and land-vector2tile. Each of these components has its own repository. All the repositories are currently in GitHub with public access to the broad community. Below is the UFS offline Land DA System hierarchical repository structure:

Hierarchy of repositories	Authoritative repo URL
UFS land-DA_workflow	https://github.com/ufs-community/land-DA_workflow
|── land-DA	https://github.com/ufs-community/land-DA/
└──land-apply_jedi_incr	https://github.com/NOAA-PSL/land-apply_jedi_incr
|── ufs-land-driver	https://github.com/NOAA-EMC/ufs-land-driver
└── ccpp-physics	https://github.com/NCAR/ccpp-physics
|── land-vector2tile	https://github.com/NOAA-PSL/land-vector2tile

In the table, the left column shows the component names and the right column shows the component authoritative repositories. The UFS offline Land DA System currently uses git submodules to manage the subcomponents.

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.