Workflow exploration: Current UFS Apps using uwtools (SRW, MRW, HAFS, others?)

[saeed-moghimi-noaa]

@Armaghan-NOAA

Would you please provide updates on which UFS workflow you are looking at?

Please share:

• What did you learn
• Your notes and ...

Thanks

[Armaghan-NOAA]

I’m looking into this repository: https://github.com/ufs-community/uwtools/

here is a summary of what I have learned do far:

1. Getting Started - Installation Conda Installation:

• sh
• Copy code
• conda create -n uwtools-env python=3.9
• conda activate uwtools-env
• conda install -c conda-forge uwtools
  • This creates a new conda environment and installs uwtools along with its dependencies.

Building Locally:

• sh
• Copy code
• git clone https://github.com/ufs-community/uwtools.git
• cd uwtools
• conda env create -f environment.yml
• conda activate uwtools-dev
• python setup.py install
  • This sequence of commands clones the repository, creates a conda environment from the environment file, activates it, and installs uwtools from the local setup script.

2. Using the Command-Line Interface (CLI) Basic Commands - Validate Configuration

• sh
• Copy code
• uw config validate --config my_config.yaml --schema schema.json
  • This command checks if my_config.yaml meets the requirements specified in schema.json. Templating

Render Mode:

• sh
• Copy code
• uw template render --template my_template.jinja2 --output rendered_config.yaml
  • This uses a Jinja2 template to render a configuration file, substituting variables as needed.

Rocoto Integration - Create Rocoto XML:

• sh
• Copy code
• uw rocoto realize --config workflow.yaml --output rocoto.xml
  • This command takes a structured YAML file describing your workflow and generates a Rocoto XML file.

3. API Reference - Using Modules FV3 Module:

• python
• Copy code
• from uwtools.api import fv3

fv3.run_fv3(config_file="fv3_config.yaml")

• This example shows how to run the FV3 model using the uwtools API by specifying a configuration file.

4. Configuring with UW YAML - Structured Configurations Example Workflow Configuration (workflow.yaml):

• yaml
• Copy code
• platform: hpc
• tasks:
• name: preprocess
• type: chgres_cube
• config: chgres_config.yaml
• name: forecast
• type: fv3
• depends_on: preprocess
• config: fv3_config.yaml

• This YAML file defines a simple workflow with two tasks: preprocessing and running a forecast, with the forecast task depending on the completion of preprocessing. Updating Values

Update YAML Values:

• sh
• Copy code
• uw config update --config workflow.yaml --values key1=value1 key2=value2
  • This updates specific keys in the YAML configuration without manually editing the file.

5. Drivers Running NWP Components Preparing a Run Directory:

• sh
• Copy code
• uw esg_grid --config esg_grid.yaml
• uw chgres_cube --config chgres_cube.yaml
• uw fv3 --config fv3.yaml
  • These commands prepare the run directory and necessary files for each step in the workflow, ready to execute on an HPC system. Submitting Batch Jobs

Submitting a Job:

• sh
• Copy code
• uw rocoto submit --workflow rocoto.xml -This command submits a job to the HPC scheduler using a Rocoto XML file generated earlier.

Developer & Contributor Guide - Setting Up Development Environment Creating a Bash Shell:

• sh
• Copy code
• conda env create -f dev_environment.yml
• conda activate uwtools-dev
  • This sets up a development environment specifically for uwtools. Maintaining Code Quality

Running Code Quality Checks:

• sh
• Copy code
• flake8 src
• pytest tests
  • These commands check the code for style issues and run unit tests to ensure code quality. Contributing

Forking and Pull Requests:

• sh
• Copy code
• git clone https://github.com/yourusername/uwtools.git
• cd uwtools
• git checkout -b feature-branch

Make your changes

• git commit -am "Add new feature"
• git push origin feature-branch
  • Then, go to GitHub and open a pull request from feature-branch to the main repository.

Building Docs Locally:

• sh
• Copy code
• cd docs
• make html
  • This command builds the HTML documentation locally, allowing to preview the changes in a web browser.

Example Workflow: Here's a simple example combining these steps into a workflow:

• Install uwtools using conda or by building locally.
• Create a YAML configuration (workflow.yaml) for the tasks.
• Render templates if needed to generate configurations.
• Validate your configurations to ensure they meet schema requirements.
• Use the API or CLI to run drivers for tasks like grid generation and model runs.
• Submit the job to the HPC scheduler using Rocoto.

By following these steps, we can set up, manage, and execute NWP workflows using Unified Workflow Tools.

[saeed-moghimi-noaa]

Please see this post: https://www.linkedin.com/posts/noaaepic_uifcw24-activity-7206726107838984192-G-1O?utm_source=share&utm_medium=member_desktop

[janahaddad]

Moving my previous notes from here to continue progress updates... let's use this issue to track this topic. Note I'm also changing issue title a bit.

@Armaghan-NOAA a few other general workflow related questions/lines of inquiry that you might be interested in pursuing:

• Here are the apps that seem to be using UW tools and UFS-Weather Model currently, from the UW tools wiki: https://github.com/ufs-community/uwtools/wiki/Component-Configuration-Management---UFS-Weather-Model#ufs-weather-model. Here are the current repos for each:
  • Short Range Weather App - regional domains
  • Medium Range Weather App - global domain
  • Hurricane Analysis and Forecast System (HAFS)

Other questions that have come to mind:

• Is there is any overlap in the Rocoto and Ecflow workflow management?
  • How much of those two tools is currently at the app-level and how much is being used from UWtools?
• It looks like these 3 apps are set up very similarly to what you've shown us for STOFS with j-jobs, ush directory, etc. To what extent is the similarity?
• How exactly is UWtools being tested in each of these apps? It looks like they are all just trying things out at this stage, and it's unclear to what level they have a stable workflow at this point. But it would be useful to know which of the apps is using many/most/all capabilities of UWtools and how.
  • E.g., looks like MRW app is importing uwtools in python scripts? is that the primary method?

I think a useful outcome of your workflow explorations would be to generate a "Backlog of (possible) Objectives" inspired by what you learn from these existing (even if currently half-baked) tools. We can then look at that list as a team or subteam (NHC team, UFS Coastal team, STOFS Ops team) and decide if it's worth testing out for each project...

Let me know what you think! I'll set up a time to review next week when you've had some tinme to explore the apps above

• meeting to review Monday 6/17
• Armaghan is currently reviewing differences between Ecflow and Rocoto in the three Apps above

[Armaghan-NOAA]

Moving my previous notes from here to continue progress updates... let's use this issue to track this topic. Note I'm also changing issue title a bit.

@Armaghan-NOAA a few other general workflow related questions/lines of inquiry that you might be interested in pursuing:

• Here are the apps that seem to be using UW tools and UFS-Weather Model currently, from the UW tools wiki: https://github.com/ufs-community/uwtools/wiki/Component-Configuration-Management---UFS-Weather-Model#ufs-weather-model. Here are the current repos for each:

  • Short Range Weather App - regional domains
  • Medium Range Weather App - global domain
  • Hurricane Analysis and Forecast System (HAFS)

Other questions that have come to mind:

• Is there is any overlap in the Rocoto and Ecflow workflow management?

  • How much of those two tools is currently at the app-level and how much is being used from UWtools?
• It looks like these 3 apps are set up very similarly to what you've shown us for STOFS with j-jobs, ush directory, etc. To what extent is the similarity?

• How exactly is UWtools being tested in each of these apps? It looks like they are all just trying things out at this stage, and it's unclear to what level they have a stable workflow at this point. But it would be useful to know which of the apps is using many/most/all capabilities of UWtools and how.

  • E.g., looks like MRW app is importing uwtools in python scripts? is that the primary method?

I think a useful outcome of your workflow explorations would be to generate a "Backlog of (possible) Objectives" inspired by what you learn from these existing (even if currently half-baked) tools. We can then look at that list as a team or subteam (NHC team, UFS Coastal team, STOFS Ops team) and decide if it's worth testing out for each project...

Let me know what you think! I'll set up a time to review next week when you've had some tinme to explore the apps above

• meeting to review Monday 6/17
• Armaghan is currently reviewing differences between Ecflow and Rocoto in the three Apps above

Thanks Jana for moving the notes here.

[Armaghan-NOAA]

Please see this post: https://www.linkedin.com/posts/noaaepic_uifcw24-activity-7206726107838984192-G-1O?utm_source=share&utm_medium=member_desktop

Thanks Saeed! This seems so interesting. I registered for that.

[janahaddad]

Other note from a duplicate issue https://github.com/noaa-ocs-modeling/SurgeTeamCoordination/issues/469 :

A reference would be a discussion @uturuncoglu had: ufs-community/uwtools#478

[janahaddad]

https://christopherwharrop.github.io/rocoto/ from @SorooshMani-NOAA

[janahaddad]

from @Armaghan-NOAA :

On Github they included rocoto: https://github.com/ufs-community/uwtools/blob/main/src/uwtools/rocoto.py

on their hpc system they have ecflow as well. you can find this from a discussion page: https://github.com/ufs-community/uwtools/pull/460

search for ecflow in this page you'll find: File "/work2/02441/bcash/frontera/workflow/ecflow/bin/uw_stage_model_files.py", line 36, in

[janahaddad]

@christinaholtNOAA would you recommend starting with SRW app to explore how uwtools is currently being used?

[Armaghan-NOAA]

I started writing a technical report on the workflow exploration: https://docs.google.com/document/d/1we9MKOyzl7xjzs7y2WsAosRQdZlUt_ocNXgAmA8qnjg/edit#heading=h.gjdgxs

I appreciate your feedbacks!

[christinaholtNOAA]

@janahaddad, I'm sorry for the delayed response. I am in the process of preparing a video on how to run a global uncoupled cold start forecast using our chgres_cube and fv3 drivers. That might be one place to start, and we can let you all know as soon as that video is available (expected in the next couple of weeks to share privately, and a few additional weeks for it to be posted publicly on YouTube).

We have also been working with NOAA GSL to incorporate some of the uwtools in an MPAS App that runs cold start forecasts. You could see that early work here: https://github.com/NOAA-GSL/mpas_app. We have the basics of a the framework in visual form in a poster we're presenting this week at the MPAS Workshop. (I've attached the PDF here: MPAS Workshop 2024.pdf)

Our UW Team is targeting a full SRW integration during this EPIC PI (in the upcoming 10-12 weeks), so it might not be the best place to start since the integration is currently limited to only a couple of configuration layer tools in the UFS Community supported version.

[janahaddad]

@christinaholtNOAA thanks for your feedback and this background/info -- I somehow completely missed MPAS as an app in the UFS system. Definitely looking forward to the how-to video!