Skip to content

Clone and build global workflow

Jump to bottom
Walter Kolczynski - NOAA edited this page Jul 26, 2022 · 14 revisions

This section will provide details on cloning and building the global-workflow on supported NOAA HPCs.

Quick instructions

Quick clone/build/link instructions (more detailed instructions below)

For forecast-only (coupled or uncoupled):

> git clone https://github.com/NOAA-EMC/global-workflow.git
> cd global-workflow/sorc
> ./checkout.sh
> ./build_all.sh
> ./link_workflow.sh emc [hera][jet][orion]

For cycled (GSI):

> git clone https://github.com/NOAA-EMC/global-workflow.git
> cd global-workflow/sorc
> ./checkout.sh -g
> ./build_all.sh
> ./link_workflow.sh emc [hera][jet][orion]

Component access

Most components cloned via the checkout process are publicly available on GitHub and do not require special access. There is one exception however: the GSI component submodules still reside on NOAA VLab and require access permissions to clone, even though the main GSI repository is available publicly on GitHub. Users cloning global-workflow will need access to the GSI submodules so the GSI checkout occurs fully/properly.

Question: What happens if I don't have access to the GSI submodule repositories?

Answer: Your sorc/gsi.fd/fix and sorc/gsi.fd/libsrc folders will be empty and your GSI build (via build_all.sh or build_gsi.sh) will fail.

Gain access to the GSI submodule repositories on VLab

  1. Ensure you have access to VLab Gerrit: log into VLab (https://vlab.noaa.gov/) with your noaa.gov email or request an outside collaborator account (discuss with your supervisor)
  2. Send an access request to the GSI code manager Mike Lueken ([email protected]).

Set up Gerrit access on HPCs to properly clone the GSI submodules from VLab Gerrit (repeat for each HPC)

  1. Add your ssh keys from the specific HPC into your VLab Gerrit account settings
  1. Create a config file in your .ssh folder on the specific HPC and add the following into it:
Host gerrit
HostName vlab.noaa.gov
        User First.Last
        Port 29418

...where "First.Last" is your VLab username (don't include the @noaa.gov part).

Users on WCOSS2 need to do the config file setup differently:

  1. Create a new .ssh-mine folder and put the config file within
  2. In your .bashrc add the following:
export GIT_SSH_COMMAND="ssh -F $HOME/.ssh-mine/config -i /u/sshKeys/$USER/id_rsa"

1) Clone workflow and component repositories

Workflow:

https method:

git clone https://github.com/NOAA-EMC/global-workflow.git

ssh method (using a password protected SSH key):

git clone [email protected]:NOAA-EMC/global-workflow.git

Check what you just cloned (by default you will have only the develop branch):

> cd global-workflow
> git branch
* develop

You now have a cloned copy of the global-workflow git repository. To checkout a branch or tag in your clone:

git checkout BRANCH_NAME

Note: Branch must already exist here ^. If it does not you need to make a new branch using the “-b” flag:

git checkout -b BRANCH_NAME

The “checkout” command will checkout BRANCH_NAME and switch your clone to that branch. Example:

> git checkout my_branch          ← checkout the ‘my_branch’ branch into clone
> git branch
* my_branch                       ← now your clone is the ‘my_branch’ branch
  develop

Components:

Once you have cloned the workflow repository it's time to checkout/clone its components. The components will be checked out under the /sorc folder via a script called checkout.sh. Run the script with no arguments for forecast-only:

> cd sorc
> ./checkout.sh

Or with the -g switch to include GSI for cycling:

> cd sorc
> ./checkout.sh -g

If wishing to run with the operational GTG UPP and WAFS (only for select users) provide the -o flag with checkout.sh:

> ./checkout.sh -o

Each component cloned via checkout.sh will have a log (checkout-COMPONENT.log). Check the screen output and logs for clone errors.

2) Build components

Under the /sorc folder is a script to build all components called build_all.sh. After running checkout.sh run this script to build all components codes:

> ./build_all.sh [-a UFS_app][-c build_config][-h][-v]
  -a UFS_app:
    Build a specific UFS app instead of the default
  -c build_config:
    Selectively build based on the provided config instead of the default config
  -h:
    Print usage message and exit
  -v:
    Run all scripts in verbose mode

A partial build option is also available via two methods:

a) modify gfs_build.cfg config file to disable/enable particular builds and then rerun build_all.sh

b) run individual build scripts also available in /sorc folder for each component or group of codes

3) Link components

At runtime the global-workflow needs all pieces in place within the main superstructure. To establish this a link script is run to create symlinks from the top level folders down to component files checked out in /sorc folders.

After running the checkout and build scripts run the link script:

./link_workflow.sh $RUN_ENVIR $MACHINE

...where:

  • RUN_ENVIR is either "emc" or "nco". The "nco" option is only used by NCO during installation into production. Users should use the "emc" option otherwise.
  • MACHINE is the HPC/platform/machine you're on. Options are: dell, cray, hera, orion

Examples:

> ./link_workflow.sh emc hera

> ./link_workflow.sh emc orion

Users running GFSv16

Clone this wiki locally