[skip ci] Merge pull request #11

Merge into main the configuration and documentation without deploying to Gadi.

.github/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
     uses: access-nri/build-cd/.github/workflows/ci.yml@main
     with:
       model: ${{ vars.NAME }}
-      # root-sbd: if different from vars.NAME
+      root-sbd: access-esm1p6
     permissions:
       pull-requests: write
       contents: write
@@ -36,7 +36,7 @@ jobs:
     uses: access-nri/build-cd/.github/workflows/ci-comment.yml@main
     with:
       model: ${{ vars.NAME }}
-      # root-sbd: if different from vars.NAME
+      root-sbd: access-esm1p6
     permissions:
       pull-requests: write
       contents: write

README.md

@@ -1,82 +1,47 @@
-# model-deployment-template
+# ACCESS-ESM1.6
 
-A template repository for the deployment of `spack`-based models.
+## About the model
+The ACCESS Earth System Model (ACCESS-ESM) is a fully-coupled global climate model that includes atmoshpere, land, ocean, sea ice, ocean biogeochemistry and land biogeochemistry components, linked together by a coupler. ACCESS-ESM1.6 is an update to ACCESS-ESM1.5, developed for CMIP7 fast tracks.
 
-> [!NOTE]
-> Feel free to replace this README with information on the model once the TODOs have been ticked off.
+## Support
 
-## Things TODO to get your model deployed
+Any questions about ACCESS-NRI releases of ACCESS-ESM1.6 should be done through the [ACCESS-Hive Forum](https://forum.access-hive.org.au/). See the [ACCESS Help and Support topic](https://forum.access-hive.org.au/t/access-help-and-support/908) for details on how to do this.
 
-### Settings
+### Build
 
-#### Repository Settings
+ACCESS-NRI is using [spack](https://spack.io), a build from source package manager designed for use with high performance computing. This repository contains a [spack environment](https://spack.readthedocs.io/en/latest/environments.html) definition file ([`spack.yaml`](https://github.com/ACCESS-NRI/ACCESS-ESM1.6/blob/main/spack.yaml)) that defines all the essential components of the ACCESS-ESM1.6 model, including exact versions.
 
-Branch protections should be set up on `main` and the special `backport/*.*` branches, which are used for backporting of fixes to major releases (the `YEAR.MONTH` portion of the `YEAR.MONTH.MINOR` version) of models.
+Spack automatically builds all the components and their dependencies, producing model component executables. Spack already contains support for compiling thousands of common software packages. Spack packages for the components in ACCESS-ESM1.6 are defined in the [spack packages repository](https://github.com/ACCESS-NRI/spack_packages/).
 
-#### Repository Secrets/Variables
+ACCESS-ESM1.6 is built and deployed automatically to `gadi` on NCI (see below). However it is possible to use spack to compile the model using the `spack.yaml` environment file in this repository. To do so follow the [instructions on the ACCESS Forum for configuring spack on `gadi`](https://forum.access-hive.org.au/t/how-to-build-access-om2-on-gadi/1545).
 
-There are a few secrets and variables that must be set at the repository level.
+Then clone this repository and run the following commands on `gadi`:
 
-##### Repository Secrets
+```bash
+spack env create access-esm1.6 spack.yaml
+spack env activate access-esm1.6
+spack install
+```
 
-* `BUILD_DB_CONNECTION_STR`: A postgresql connection url to the release provenance database
-* `GH_COMMIT_CHECK_TOKEN`: GitHub Token that allows workflows to run based on workflow-authored commits (in  the case where a user uses `!bump` commands in PRs that bumps the version of the model)
+to create a spack environment called `access-esm1.6` and build all the ACCESS-ESM1.6 components, the locations of which can be found using `spack find --paths`.
 
-##### Repository Variables
+### Deployment
 
-* `BUILD_DB_PACKAGES`: List of `spack` packages that are model components that will be uploaded to the release provenance database
-* `NAME`: which corresponds to the model name - which is usually the repository name
-* `CONFIG_VERSIONS_SCHEMA_VERSION`: Version of the [`config/versions.json` schema](https://github.com/ACCESS-NRI/schema/tree/main/au.org.access-nri/model/deployment/config/versions) used in this repository
-* `SPACK_YAML_SCHEMA_VERSION`: Version of the [ACCESS-NRI-style `spack.yaml` schema](https://github.com/ACCESS-NRI/schema/tree/main/au.org.access-nri/model/spack/environment/deployment) used in this repository
+ACCESS-ESM1.6 is deployed automatically when a new version of the [`spack.yaml`](https://github.com/ACCESS-NRI/ACCESS-ESM1.6/blob/main/spack.yaml) file is committed to `main` or a dedicated `backport/VERSION` branch. All the ACCESS-ESM1.6 components are built using `spack` on `gadi` and installed under the [`vk83`](https://my.nci.org.au/mancini/project/vk83) project in `/g/data/vk83`. It is necessary to be a member of [`vk83`](https://my.nci.org.au/mancini/project/vk83) project to use ACCESS-NRI deployments of ACCESS-ESM1.6.
 
-#### Environment Secrets/Variables
+The deployment process also creates a GitHub release with the same tag. All releases are available under the [Releases page](https://github.com/ACCESS-NRI/ACCESS-ESM1.6/releases). Each release has a changelog and meta-data with detailed information about the build and deployment, including:
 
-GitHub Environments are sets of variables and secrets that are used specifically to deploy software, and hence have more security requirements for their use.
+- paths on `gadi` to all executables built in the deployment process (`spack.location`)
+- a `spack.lock` file, which is a complete build provenance document, listing all the components that were built and their dependencies, versions, compiler version, build flags and build architecture
+- the environment `spack.yaml` file used for deployment
 
-Currently, we have two Environments per deployment target - one for `Release` and one for `Prerelease`. Our current list of deployment targets and Environments can be found in this [deployment configuration file in `build-cd`](https://github.com/ACCESS-NRI/build-cd/blob/main/config/deployment-environment.json).
+Additionally the deployment creates environment modulefiles, the [standard method for deploying software on `gadi`](https://opus.nci.org.au/display/Help/Environment+Modules). To view available ACCESS-ESM1.6 versions:
 
-In order to deploy to a given deployment target:
+```bash
+module use /g/data/vk83/apps/spack/0.22/release/modules/linux-rocky8-x86_64
+module avail access-esm1.6
+```
 
-* Environments with the name of the deployment target must be created _in this repository_ and have the associated secrets/variables set ([see below](#environment-secrets))
-* There must be a `Prerelease` Environment associated with the `Release` Environment. For example, if we are deploying to `SUPERCOMPUTER`, we require Environments with the names `SUPERCOMPUTER`, `SUPERCOMPUTER Prerelease`.
+For users of ACCESS-ESM1.6 model configurations released by ACCESS-NRI the exact location of the ACCESS-ESM1.6 model executables is not required. Model configurations will be updated with new model components when necessary.
 
-When setting the environment up, remember to require sign off by a member of ACCESS-NRI when deploying as a `Release`.
-
-Regarding the secrets and variables that must be created:
-
-##### Environment Secrets
-
-* `HOST`: The deployment location SSH Host
-* `HOST_DATA`: The deployment location SSH Host for data transfer (may be the same as `HOST`)
-* `SSH_KEY`: A SSH Key that allows access to the above `HOST`/`HOST_DATA`
-* `USER`: A Username to login to the above `HOST`/`HOST_DATA`
-
-##### Environment Variables
-
-* `DEPLOYMENT_TARGET`: Name of the deployment target for logging purposes
-* `SPACK_INSTALLS_ROOT_LOCATION`: Path to the directory that contains all versions of a deployment of `spack`. For example, if `/some/apps/spack` is the `SPACK_INSTALLS_ROOT_LOCATION`, that directory will contain directories like `0.20`, `0.21`, `0.22`, which in turn contain an install of `spack`, `spack-packages` and `spack-config`
-* `SPACK_YAML_LOCATION`: Path to a directory that will contain the `spack.yaml` from this repository during deployment
-* (Optional) `SPACK_INSTALL_PARALLEL_JOBS`: Explicit number of parallel jobs for the installation of the given model. Must be either of the form `--jobs N` or unset (for the default `--jobs 16`).
-
-### File Modifications
-
-#### In `.github/workflows`
-
-* Reminder that these workflows use `vars.NAME` (as well as inherit the above environment secrets) and hence these must be set.
-* If the name of the root SBD for the model (in [`spack-packages`](https://github.com/ACCESS-NRI/spack-packages/tree/main/packages)) is different from the model name (for example, `ACCESS-ESM1.5`s root SBD is `access-esm1p5`), you must uncomment and set the `jobs.[pr-ci|pr-comment].with.root-sbd` line to the appropriate SBD name.
-
-#### In `config/versions.json`
-
-* `.spack` must be given a version. For example, it will clone the associated `releases/VERSION` branch of `ACCESS-NRI/spack` if you give it `VERSION`.
-* `.spack-packages` should also have a CalVer-compliant tag as the version. See the [associated repo](https://github.com/ACCESS-NRI/spack-packages/tags) for a list of available tags.
-* `.spack-config` should also have a CalVer-compliant tag as the version. See the [associated repo](https://github.com/ACCESS-NRI/spack-config/tags) for a list of available tags.
-
-#### In `spack.yaml`
-
-There are a few TODOs for the `spack.yaml`:
-
-* `spack.specs`: Set the root SBD as the only element of `spack.specs`. This must also have an `@git.YEAR.MONTH.MINOR` version as it is the version of the entire deployment (and indeed will be a tag in this repository).
-* `spack.packages.*`: In this section, you can specify the versions and variants of dependencies. Note that the first element of the `spack.packages.*.require` must be only a version. Variants and other configuration can be done on subsequent lines.
-* `spack.packages.all`: Can set configuration for all packages. For example, the compiler used, or the target architecture.
-* `spack.modules.default.tcl.include`: List of package names that will be explicitly included and available to `module load`.
-* `spack.modules.default.tcl.projections`: For included modules, you must set the name of the module to be the same as the `spack.packages.*.require[0]` version, without the `@git.`.
+For information on contributing your own fixes to the ACCESS-ESM1.6 `spack.yaml`, see the [CONTRIBUTING.md](./CONTRIBUTING.md) file.

config/versions.json

@@ -1,5 +1,5 @@
 {
     "$schema": "https://github.com/ACCESS-NRI/schema/blob/main/au.org.access-nri/model/deployment/config/versions/3-0-0.json",
     "spack": "0.22",
-    "spack-packages": "SOME_SPECIFIC_TAG"
+    "spack-packages": "2024.11.2"
 }

spack.yaml

@@ -4,53 +4,76 @@
 # configuration settings.
 spack:
   specs:
-    # The root Spack Bundle Recipe (SBR) for the model and overall version of
-    # the deployment:
-    # TODO: Replace the MODEL and VERSION.
-    # - [email protected]
-
+    - [email protected]
   packages:
-    # Specification of dependency versions and variants. CI/CD requires that
-    # the first element of the require is only a version:
-    # TODO: Specify versions and variants of dependencies as required.
-    # openmpi:
-    #   require:
-    #     - '@4.1.5'
+    # Direct ACCESS-NRI dependencies
+    # Note: some packages have branch-specific logic and hence can't use
+    # the usual '@git.DATE' calver (https://calver.org) format, instead
+    # requiring a `@git.DATE=BRANCH` version.
+    mom5:
+      require:
+        - '@git.dev_2024.08.14=access-esm1.6'
+        - '+access-gtracers'
+    cice4:
+      require:
+        - '@git.2024.05.21=access-esm1.5'
+    um7:
+      require:
+        - '@git.18-esm15-cable3=access-esm1.5'
+    # Lower-level ACCESS-NRI dependencies
+    gcom4:
+      require:
+        - '@git.2024.05.28=access-esm1.5'
+    oasis3-mct:
+      require:
+        - '@git.access-esm1.5_2024.05.24=access-esm1.5'
+    # Other dependencies
+    openmpi:
+      require:
+        - '@4.0.2'
+    netcdf-c:
+      require:
+        - '@4.7.4'
+    netcdf-fortran:
+      require:
+        - '@4.5.2'
+    hdf5:
+      require:
+        - '@1.10.11'
+    access-fms:
+      require:
+        - '@git.dev_2024.11.0'
+    access-generic-tracers:
+      require:
+        - '@git.dev_2024.11.0'
+    access-mocsy:
+      require:
+        - '@git.2017.12.0'
 
-    # Specifications that apply to all packages
+    # Preferences for all packages
     all:
-      # TODO: Specify compiler/targets for all packages
-      # require:
-      #   - '%[email protected]'
-      #   - 'target=x86_64'
+      require:
+        - '%[email protected]'
+        - 'target=x86_64_v4'
   view: true
   concretizer:
     unify: true
   modules:
     default:
       tcl:
         include:
-          # TODO: Add MODEL and PACKAGEs that will have a corresponding module
-          # - MODEL
-          # - PACKAGE1
-          # - PACKAGE2
+          - access-esm1p6
+          - cice4
+          - um7
+          - mom5
         projections:
-          # These projection VERSIONs must be the same as the
-          # `spack.packages.*.require[0]` VERSION but without the `@git.` and
-          # without the RHS of the equals sign, if there is one.
-          #
-          # For a MODEL, an example projection is `{name}/2024.10.0`.
-          # For a PACKAGE where `require` VERSION is
-          # `@git.2024.04.21=access-esm1.5`, the projection becomes
-          # `{name}/2024.04.21-{hash:7}`.
-          # TODO: Add explicit projections for modules that will be found with
-          #       `module load`.
-          # MODEL: '{name}/VERSION'
-          # PACKAGE1: '{name}/VERSION1-{hash:7}'
-          # PACKAGE2: '{name}/VERSION2-{hash:7}'
-  # config:
-  #   overridden spack configurations, if needed
-  # mirrors:
-  #   overridden spack package tarball directories, if needed
-  # repos:
-  #   overridden repo sources, if needed
+          access-esm1p6: '{name}/2024.10.0'
+          cice4: '{name}/2024.05.21-{hash:7}'
+          um7: '{name}/18-esm15-cable3-{hash:7}'
+          mom5: '{name}/dev_2024.08.14-{hash:7}'
+  config:
+    install_tree:
+      root: $spack/../restricted/ukmo/release
+    source_cache: $spack/../restricted/ukmo/source_cache
+    build_stage:
+    - $TMPDIR/restricted/spack-stage