Ctrl+K

Managing KGOs#

Running UG-ANTS on different platforms may result in small numeric differences in results. Consequently, each site needs to generate a local set of known good outputs (KGOs) for use in rose stem testing.

Prerequisites#

Source data must first be added, see Managing rose stem sources.

Initial setup#

Before running the rose stem workflow, the environment variable UG_ANTS_KGO_DIRECTORY_DEFAULT needs to be set to point to a suitable central location for the KGO directory corresponding to the version of UG-ANTS being installed. The following steps will populate this directory with site specific KGO files. A version specific module file, site-specific ug-ants-launch script, or any other appropriate method can be used for setting the environment variable.

After installing UG-ANTS, and confirming the unittests pass, the rose stem workflow can be used to bootstrap a set of KGO files to protect against future changes.

To do this, run the rose stem workflow:

Changed in version 0.4.0: The rose stem workflow is now run via cylc vip rather than rose stem.

$ cd <working copy>
$ cylc vip ./rose-stem -z group=all

The rose stem tasks in the workflow will fail, since there are no KGOs yet. Wait for the workflow to complete, and then run:

$ cp -r ~/cylc-run/generate_KGOs/runN/share/data/* $UG_ANTS_KGO_DIRECTORY_DEFAULT

At this point, re-running the rose stem workflow should result in a passing workflow.

This process should be repeated for ug-ancillary-file-science, with the UG_CONTRIB_KGO_DIRECTORY_DEFAULT environment variable. The contrib part of the name is legacy and may change in a future release.

KGO directory structure#

It is recommended to keep a complete set of KGOs for the current release. It may also be necessary to store a set of KGOs for head of trunk, and a number of previous releases. The following directory structure is suggested for UG-ANTS core and ug-ancillary-file-science (using the legacy contrib name for consistency with existing installations):

UG-ANTS
  ├── developer
  │   ├── contrib
  │   │   └── <full_KGO_files>
  │   └── core
  │       └── <full_KGO_files>
  └── release
      └── X.Y.Z
          ├── contrib
          │   └── <full_KGO_files>
          └── core
              └── <full_KGO_files>

Development changes#

If a contributor has a change that adds, removes or changes KGOs, then they should:

  1. Add newly generated KGO changes to a local directory. This only needs to be the KGO files needed for any rose stem tests affected by the change, rather than the full set of KGOs.

  2. Add an UG_ANTS_KGO_DIRECTORY_OVERRIDE or UG_CONTRIB_KGO_DIRECTORY_OVERRIDE variable (that points to the local directory) to the [[[environment]]] section of each affected task’s runtime entry within the flow.cylc.

  3. Seek science owner approval for KGO changes.

  4. When the ticket is complete, please include a summary of the KGO changes on the ticket template.

On this page
Show Source