diff --git a/documentation/docs/pages/AOMSS_Lecture_Notes.md b/documentation/docs/pages/AOMSS_Lecture_Notes.md index abf2b5a..a28bb14 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 @@ -291,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$ @@ -327,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 @@ -354,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.$ @@ -429,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}$ @@ -449,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}$ @@ -525,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 @@ -537,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$ @@ -547,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$ diff --git a/documentation/docs/pages/decoding_mom6.md b/documentation/docs/pages/decoding_mom6.md index cd062e7..048f5db 100644 --- a/documentation/docs/pages/decoding_mom6.md +++ b/documentation/docs/pages/decoding_mom6.md @@ -105,7 +105,110 @@ 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. + +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 in a `config.yaml` file in an `access-om3-configs` branch or directory if you have already cloned an experiment). + +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) + +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 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 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