From 0a3fcb59d38f843c9f3e52a93137fd82ce96e4f1 Mon Sep 17 00:00:00 2001 From: Christopher Bull <5499680+chrisb13@users.noreply.github.com> Date: Thu, 5 Feb 2026 12:41:17 +1100 Subject: [PATCH 1/7] Update decoding_mom6.md --- documentation/docs/pages/decoding_mom6.md | 101 ++++++++++++++++++++++ 1 file changed, 101 insertions(+) diff --git a/documentation/docs/pages/decoding_mom6.md b/documentation/docs/pages/decoding_mom6.md index cd062e7..a1bcf4a 100644 --- a/documentation/docs/pages/decoding_mom6.md +++ b/documentation/docs/pages/decoding_mom6.md @@ -106,6 +106,107 @@ Further information: - [MOM6 development presentation](https://www.marshallward.org/mom6workshop/develop.html) by @marshallward. ## How to find code that corresponds to a particular executable (both ACCESS-NRI and other MOM6 executables e.g. from Angus) +### ACCESS-NRI executables +Presenter: @jbisits +Scope: where and how to find which model components and source code are used in an OM3 configuration that are built with Spack (this applies to all ACCESS-NRI models). + +#### Through ACCESS-NRI release database (friendly) + +The easiest way to find a related version is to use the [release database](https://reporting.access-nri-store.cloud.edu.au/release-provenance/releases +). For example, suppose we are interested in model version `2025.08.001` (listed by a `config.yaml` file in an `access-om3-configs` file). + +Then we can find it [here](https://reporting.access-nri-store.cloud.edu.au/release-provenance/releases/32/). Then clicking on any of the github icons for the relevant component takes you to the version of the code that was used in that release. + +#### Directly through GitHub (more complicated) + +For example looking at `ACCESS-OM3`, we start by looking at the [configuration repository](https://github.com/access-nri/access-om3-configs/): `ACCESS-NRI/access-om3-configs`. Note that the main branch does not contain configurations -- you have to look at the branches. + +You may wish to know what are the model components being used in [a particular release](https://github.com/ACCESS-NRI/access-om3-configs/tags)? Looking at the release: `release-MC_25km_jra_iaf-1.0-beta` we can browse the repository at the relevant [tag here](https://github.com/ACCESS-NRI/access-om3-configs/tree/release-MC_25km_jra_iaf-1.0-beta). + +Then in the `config.yaml`, see [the model software version](https://github.com/ACCESS-NRI/access-om3-configs/blob/95ac4456b2e08a3dc1e6476e8dc96900005151ce/config.yaml#L18-L23): + +```yaml +modules: + use: + - /g/data/vk83/modules + load: + - access-om3/2025.08.001 +``` + +`access-om3/2025.08.001` refers to [this repository](https://github.com/access-nri/access-om3) with this at the tag: `2025.08.001`. To find the tags one goes to [the repository](https://github.com/ACCESS-NRI/ACCESS-OM3) --> Releases --> Tags. Here is the related `access-om3` release: +https://github.com/ACCESS-NRI/ACCESS-OM3/releases/tag/2025.08.001 + +Browsing the related `spack.yaml` we can see the versions of the components in the build, [for example](https://github.com/ACCESS-NRI/ACCESS-OM3/blob/7439c61acbe167abd79fc9be4dc333fadb9ac0cb/spack.yaml#L10-L82) for CICE and MOM6 we have: +```yaml + access-cice: + require: + - '@CICE6.6.1-0' + - io_type=PIO + - 'fflags="-march=sapphirerapids -mtune=sapphirerapids -unroll"' + - 'cflags="-march=sapphirerapids -mtune=sapphirerapids -unroll"' + - 'cxxflags="-march=sapphirerapids -mtune=sapphirerapids -unroll"' + access-mom6: + require: + - '@2025.07.000' + - 'fflags="-march=sapphirerapids -mtune=sapphirerapids -unroll"' + - 'cflags="-march=sapphirerapids -mtune=sapphirerapids -unroll"' + - 'cxxflags="-march=sapphirerapids -mtune=sapphirerapids -unroll"' +``` + +Like before, we go to the related `ACCESS-NRI` repositories and find the related tags, in this instance they are: + - [access-CICE](https://github.com/ACCESS-NRI/CICE/releases/tag/CICE6.6.1-0); + - [access-mom6](https://github.com/ACCESS-NRI/MOM6/releases/tag/2025.07.000). + +Note that the above two repositories are forks of the upstream repositories ([CICE](https://github.com/ESCOMP/CICE) and [MOM6](https://github.com/mom-ocean/MOM6)) + +For more information and other related steps: + - https://access-om3-configs.access-hive.org.au/infrastructure/Building/ + - https://docs.access-hive.org.au/getting_started/spack/ + - https://docs.access-hive.org.au/models/build_a_model/build_source_code/ + - https://docs.access-hive.org.au/models/build_a_model/create_a_prerelease/ (not shown in this tutorial but can be very simple) + +---- + +### COSIMA executables (e.g. `mom6-panan`) +Presenter: @angus-g. +Scope: where and how to find which model components and source code are used in a COSIMA configuration built with ninja. + +COSIMA made executables use a different build system and way of tracking provenance. Here's an example using the `mom6-panan`. Going to [the relevant line](https://github.com/COSIMA/mom6-panan/blob/master/config.yaml#L17) in the `config.yaml` we have: `exe: /g/data/ik11/inputs/mom6/bin/symmetric_FMS2-e7d09b7` + +If one then goes on Gadi to the related folder, one finds: +`/g/data/ik11/inputs/mom6/bin/manifest.yaml` + +Looking inside the manifest file we see a series of executables with information related to the major components (MOM6, SIS2, FMS) with the git hash used. The compiler flags are also included but not the more minor components. Below is an example: +```yaml +exe: "symmetric_FMS2-e7d09b7" + build-date: 2022-01-20 + sha256: "e7d09b7687fba4cf0693adf3c1a5f653dee312df996b99da384c64c279a53eef" + git: + - component: MOM6 + ref: "93968bd8ec1a993c705846ec91c4cf33b86bc4fb" + - component: SIS2 + ref: "d18605eacdd2c92b8262458fcad107c546dd080f" + - component: FMS + ref: "2d373d20af28b9d8e2cc0d0acf2334fcff457e47" + modules: + - "intel-mkl/2020.2.254" + - "python3/3.8.5" + - "netcdf/4.7.4p" + - "openmpi/4.1.2" + - "intel-compiler/2021.4.0" + keywords: [SIS2, symmetric, FMS2] + flags: + fflags: "-fno-alias -auto -safe-cray-ptr -ftz -assume byterecl -i4 -r8 -nowarn -sox -g -O2 -debug minimal -fp-model precise -qoverride-limits -xHost" + cflags: "-D__IFC -sox -g" +``` + +With the above information, one could then compile using the `mom6-ninja-nci` workflow written by @angus-g -- [see here](https://github.com/angus-g/mom6-ninja-nci). + +More information: + - https://github.com/angus-g/mom6-ninja-nci + - https://github.com/COSIMA/access-om2/wiki/Developers-guide (possibly out of date) + - http://github.com/cosima/access-om3 (deprecated!) + ## How to find what diagnostics are available ## Overview of MOM6 configuration (input files etc) ## Searching through the MOM parameter docs and other output, e.g. what’s in what file, how to interpret maxCFL, truncations, warnings, errors From 371febdf9d8f7a5d9ad10e9156bb2aab50c16a7c Mon Sep 17 00:00:00 2001 From: Christopher Bull <5499680+chrisb13@users.noreply.github.com> Date: Thu, 5 Feb 2026 13:41:24 +1100 Subject: [PATCH 2/7] see if this is removing the lychee errors --- documentation/docs/pages/AOMSS_Lecture_Notes.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/documentation/docs/pages/AOMSS_Lecture_Notes.md b/documentation/docs/pages/AOMSS_Lecture_Notes.md index abf2b5a..51226cc 100644 --- a/documentation/docs/pages/AOMSS_Lecture_Notes.md +++ b/documentation/docs/pages/AOMSS_Lecture_Notes.md @@ -160,7 +160,7 @@ $\tilde{f}=2 \Omega \cos\phi$. ## Hydrostatic balance -In the vertical direction, the primary balance is between gravity pressure gradients -- hydrostatic balance. To see this, take the vertical component of [\[eq:nsrot\]](#eq:nsrot){reference-type="eqref" reference="eq:nsrot"}, +In the vertical direction, the primary balance is between gravity pressure gradients -- hydrostatic balance. To see this, take the vertical component of `[\[eq:nsrot\]](#eq:nsrot){reference-type="eqref" reference="eq:nsrot"}`, $\frac{\partial w}{\partial t} + \mathbf{u} \cdot \nabla w - \tilde{f} u = -g -\frac{1}{\rho}\frac{\partial p}{\partial z} + \nu \nabla^2 w.$ @@ -173,8 +173,7 @@ $\label{eq:hydrostatic} \frac{\partial p}{\partial z} = -\rho g.$ This is the hydrostatic balance and for large-scale models it replaces the vertical component of the momentum equation. Thus, we only find vertical velocity from the continuity equation, -[\[eq:continuity\]](#eq:continuity){reference-type="eqref" -reference="eq:continuity"}: +`[\[eq:continuity\]](#eq:continuity){reference-type="eqref" reference="eq:continuity"}`: $\frac{\partial w}{\partial z} = - \frac{\partial u}{\partial x} - \frac{\partial v}{\partial y}$ @@ -192,8 +191,7 @@ These $\tilde{f}$ terms are sometimes called the non-traditional Coriolis terms, ## Boussinesq approximation -Equation [\[eq:hydrostatic\]](#eq:hydrostatic){reference-type="eqref" -reference="eq:hydrostatic"} uses the full ocean density on the RHS, but +Equation `[\[eq:hydrostatic\]](#eq:hydrostatic){reference-type="eqref" reference="eq:hydrostatic"}` uses the full ocean density on the RHS, but for the horizontal momentum (where the projection of gravity is zero) the role of density in momentum conservation is small. Thus, we invoke the Boussinesq approximation, where momentum in the horizontal direction From e28278fcc873f95380e903ec8e981b81850338c1 Mon Sep 17 00:00:00 2001 From: Christopher Bull <5499680+chrisb13@users.noreply.github.com> Date: Thu, 5 Feb 2026 13:43:24 +1100 Subject: [PATCH 3/7] removing more problem references for the link checker --- .../docs/pages/AOMSS_Lecture_Notes.md | 26 ++++++++----------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/documentation/docs/pages/AOMSS_Lecture_Notes.md b/documentation/docs/pages/AOMSS_Lecture_Notes.md index 51226cc..a28bb14 100644 --- a/documentation/docs/pages/AOMSS_Lecture_Notes.md +++ b/documentation/docs/pages/AOMSS_Lecture_Notes.md @@ -289,7 +289,7 @@ $\begin{aligned} & = \nabla \cdot (\mathbf{u} u). \end{aligned}$ -Let's write [\[eq:momu\]](#eq:momu){reference-type="eqref" reference="eq:momu"} as +Let's write `[\[eq:momu\]](#eq:momu){reference-type="eqref" reference="eq:momu"}` as $\frac{\partial u}{\partial t} + \frac{\partial uu}{\partial x} + \frac{\partial vu}{\partial y} + \frac{\partial wu}{\partial z} - fv = g' \frac{\partial \eta_1}{\partial x} + \nu \nabla^2u$ @@ -325,10 +325,8 @@ $\label{eq:momlayer} (where the $\mathbf{v}\mathbf{v}$ term implies an outer product, or $v_i v_j$ in tensor form). The shallow water equations, -[\[eq:masslayer\]](#eq:masslayer){reference-type="eqref" -reference="eq:masslayer"} and -[\[eq:momlayer\]](#eq:momlayer){reference-type="eqref" -reference="eq:momlayer"}, are a nice compact set of equations that we +`[\[eq:masslayer\]](#eq:masslayer){reference-type="eqref" reference="eq:masslayer"}` and +`[\[eq:momlayer\]](#eq:momlayer){reference-type="eqref" reference="eq:momlayer"}`, are a nice compact set of equations that we can use to understand idealised flows -- and to explore numerics! ## Quasigeostrophy @@ -352,7 +350,7 @@ TO BE ADDED ## Finite difference Take a simple example from -[\[eq:masslayer\]](#eq:masslayer){reference-type="eqref" reference="eq:masslayer"}: +`[\[eq:masslayer\]](#eq:masslayer){reference-type="eqref" reference="eq:masslayer"}`: $\frac{\partial h}{\partial t} + \frac{\partial (uh)}{\partial x} + \frac{\partial (vh)}{\partial y}=0.$ @@ -427,8 +425,7 @@ is defined at the same point as $u_i$. ![ArakawaC](../assets/ArakawaC.png){: style="height:600px;width:600px"} Let's extend this idea to two dimensions -- here is the Arakawa C-grid. Apply this to the shallow water equation -[\[eq:momlayer\]](#eq:momlayer){reference-type="eqref" -reference="eq:momlayer"}: +`[\[eq:momlayer\]](#eq:momlayer){reference-type="eqref" reference="eq:momlayer"}`: $\frac{\partial \mathbf{v}h}{\partial t} + \nabla \cdot (\mathbf{v}\mathbf{v}h) + f \mathbf{\hat{z}} \times \mathbf{v}h = g' h \nabla \eta_1+ \nu h \nabla_h^2\mathbf{v} + \pmb{\tau}$ @@ -447,7 +444,8 @@ An alternative approach here is a semi-implicit framework, where the Coriolis te We have already derived the equation for a single (reduced gravity) shallow water model. Here we will derive, in a slightly more rigorous manner, equations for a series of stacked shallow water models, following the derivation of Ward & Hogg (2011). -We are going to start with the primitive equations [\[eq:momu\]](#eq:momu){reference-type="eqref" reference="eq:momu"}--[\[eq:cont\]](#eq:cont){reference-type="eqref" reference="eq:cont"} transformed into density space. We write this transformation to occurs from $(x,y,z,t) \to (x, y, \rho, t)$, which +We are going to start with the primitive equations +`[\[eq:momu\]](#eq:momu){reference-type="eqref" reference="eq:momu"}--[\[eq:cont\]](#eq:cont){reference-type="eqref" reference="eq:cont"}` transformed into density space. We write this transformation to occurs from $(x,y,z,t) \to (x, y, \rho, t)$, which gives us $\frac{d }{d z} \to \frac{1}{z_\rho} \frac{d }{d \rho}$ @@ -523,10 +521,8 @@ $\label{eq:momlayers} where $\mathbf{F}$ are the frictional/viscous terms which we will not worry about here. Multiply equation -[\[eq:momlayers\]](#eq:momlayers){reference-type="eqref" -reference="eq:momlayers"} by $z_\rho$ and add $\mathbf{v}$ times -[\[eq:layers\]](#eq:layers){reference-type="eqref" -reference="eq:layers"}: +`[\[eq:momlayers\]](#eq:momlayers){reference-type="eqref" reference="eq:momlayers"}` by $z_\rho$ and add $\mathbf{v}$ times +`[\[eq:layers\]](#eq:layers){reference-type="eqref" reference="eq:layers"}`: $z_\rho \frac{\partial \mathbf{v}}{\partial t} + \mathbf{v} \frac{\partial z_\rho}{\partial t} + z_\rho \mathbf{v}\cdot \nabla \mathbf{v} + \mathbf{v} \nabla \cdot (\mathbf{v} z_\rho) + f \mathbf{\hat{z}} \times \mathbf{v} z_\rho = - z_\rho \nabla M + z_\rho \mathbf{F}$ $\frac{\partial \mathbf{v}z_\rho }{\partial t} + \nabla \cdot (\mathbf{v} \mathbf{v} z_\rho) + f \mathbf{\hat{z}} \times \mathbf{v} z_\rho = - z_\rho \nabla M + z_\rho \mathbf{F}$ Now integrate across a region in between two isopycnal surfaces, noting @@ -535,7 +531,7 @@ $\frac{\partial \mathbf{v}_k h_k }{\partial t} + \nabla \cdot (\mathbf{v}_k \ ![StackedLayers](../assets/StackedLayers.png){: style="height:650px;width:900px"} -The hydrostatic equation [\[eq:Mont\]](#eq:Mont){reference-type="eqref" reference="eq:Mont"} can also be integrated in density space to give +The hydrostatic equation `[\[eq:Mont\]](#eq:Mont){reference-type="eqref" reference="eq:Mont"}` can also be integrated in density space to give $\int_{\rho_k}^{\rho_{k+1}} \frac{\partial M}{\partial \rho} \, d\rho = M_{k+1} - M_k = \frac{\Delta \rho g z}{\rho_0} = g_k \eta_k$ @@ -545,7 +541,7 @@ $M_{k+1} = M_k + g_k \eta_k$ where $g_k = g(\rho_k - \rho_{k-1})/\rho_0$. -We can also integrate [\[eq:layers\]](#eq:layers){reference-type="eqref" reference="eq:layers"} on its own to give +We can also integrate `[\[eq:layers\]](#eq:layers){reference-type="eqref" reference="eq:layers"}` on its own to give $\frac{\partial h_k}{\partial t} + \nabla \cdot (\mathbf{v}_k h_k) = 0$ From 5ea94d7c148ce328bdbf5af532965f164a37707c Mon Sep 17 00:00:00 2001 From: Christopher Bull <5499680+chrisb13@users.noreply.github.com> Date: Thu, 5 Feb 2026 13:50:16 +1100 Subject: [PATCH 4/7] Update decoding_mom6.md tiny tweaks --- documentation/docs/pages/decoding_mom6.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/documentation/docs/pages/decoding_mom6.md b/documentation/docs/pages/decoding_mom6.md index a1bcf4a..60dab0e 100644 --- a/documentation/docs/pages/decoding_mom6.md +++ b/documentation/docs/pages/decoding_mom6.md @@ -105,9 +105,10 @@ Further information: - [NOAA-GFDL MOM6 development guide](https://github.com/NOAA-GFDL/MOM6-examples/wiki/Developers-guide); - [MOM6 development presentation](https://www.marshallward.org/mom6workshop/develop.html) by @marshallward. -## How to find code that corresponds to a particular executable (both ACCESS-NRI and other MOM6 executables e.g. from Angus) +## How to find code that corresponds to a particular executable ### ACCESS-NRI executables -Presenter: @jbisits +Presenter: @jbisits. + Scope: where and how to find which model components and source code are used in an OM3 configuration that are built with Spack (this applies to all ACCESS-NRI models). #### Through ACCESS-NRI release database (friendly) @@ -169,6 +170,7 @@ For more information and other related steps: ### COSIMA executables (e.g. `mom6-panan`) Presenter: @angus-g. + Scope: where and how to find which model components and source code are used in a COSIMA configuration built with ninja. COSIMA made executables use a different build system and way of tracking provenance. Here's an example using the `mom6-panan`. Going to [the relevant line](https://github.com/COSIMA/mom6-panan/blob/master/config.yaml#L17) in the `config.yaml` we have: `exe: /g/data/ik11/inputs/mom6/bin/symmetric_FMS2-e7d09b7` From 8b888107a8e1fae8e1b7caf2346a1b92ed3e06a4 Mon Sep 17 00:00:00 2001 From: Josef Bisits Date: Thu, 5 Feb 2026 16:02:20 +1100 Subject: [PATCH 5/7] Small wording chagens Clarified instructions for finding model versions in the release database and GitHub. --- documentation/docs/pages/decoding_mom6.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/docs/pages/decoding_mom6.md b/documentation/docs/pages/decoding_mom6.md index 60dab0e..048f5db 100644 --- a/documentation/docs/pages/decoding_mom6.md +++ b/documentation/docs/pages/decoding_mom6.md @@ -114,9 +114,9 @@ Scope: where and how to find which model components and source code are used in #### Through ACCESS-NRI release database (friendly) The easiest way to find a related version is to use the [release database](https://reporting.access-nri-store.cloud.edu.au/release-provenance/releases -). For example, suppose we are interested in model version `2025.08.001` (listed by a `config.yaml` file in an `access-om3-configs` file). +). For example, suppose we are interested in model version `2025.08.001` (listed in a `config.yaml` file in an `access-om3-configs` branch or directory if you have already cloned an experiment). -Then we can find it [here](https://reporting.access-nri-store.cloud.edu.au/release-provenance/releases/32/). Then clicking on any of the github icons for the relevant component takes you to the version of the code that was used in that release. +We can find this model version [here](https://reporting.access-nri-store.cloud.edu.au/release-provenance/releases/32/). Then clicking on any of the github icons for the relevant component takes you to the version of the code that was used in that release. #### Directly through GitHub (more complicated) From a0ed58ffdde1bd2f2fa89ad2183199d0b7091b93 Mon Sep 17 00:00:00 2001 From: Christopher Bull <5499680+chrisb13@users.noreply.github.com> Date: Thu, 5 Feb 2026 17:25:40 +1100 Subject: [PATCH 6/7] Update hide_pages_url_segment.py as suggested by @atteggiani https://github.com/ACCESS-Community-Hub/decoding-om3/pull/9#issuecomment-3850928269 --- documentation/hooks/hide_pages_url_segment.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/hooks/hide_pages_url_segment.py b/documentation/hooks/hide_pages_url_segment.py index bb7f074..c38c350 100644 --- a/documentation/hooks/hide_pages_url_segment.py +++ b/documentation/hooks/hide_pages_url_segment.py @@ -6,4 +6,5 @@ def on_page_markdown(markdown, *, page, config, files): if page.file.url.startswith("pages/"): page.file.url = page.file.url.removeprefix("pages/") page.file.dest_uri = page.file.dest_uri.removeprefix("pages/") - page.file.abs_dest_path = page.file.abs_dest_path.removeprefix("pages/") \ No newline at end of file + page.file.abs_dest_path = page.file.abs_dest_path.removeprefix("pages/") + page.canonical_url = config.site_url + page.file.url From a0aeb555bde9d34edcd07ca54eb4183a874831a9 Mon Sep 17 00:00:00 2001 From: Christopher Bull <5499680+chrisb13@users.noreply.github.com> Date: Thu, 5 Feb 2026 17:25:46 +1100 Subject: [PATCH 7/7] Update mkdocs.yml as suggested by @atteggiani https://github.com/ACCESS-Community-Hub/decoding-om3/pull/9#issuecomment-3850928269 --- documentation/mkdocs.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index 762f72d..bb506bd 100755 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -4,7 +4,8 @@ site_name: decoding-om3 # Site URL -site_url: !ENV [SITE_URL, "https://access-community-hub.github.io/decoding-om3/"] +# site_url: !ENV [SITE_URL, "https://access-community-hub.github.io/decoding-om3/"] +site_url: !ENV READTHEDOCS_CANONICAL_URL # Git repository (Adds a link to the GitHub repository at the top) repo_url: https://github.com/ACCESS-Community-Hub/decoding-om3