Staggered grid locations and names

[briochemc]

Not sure this is the right place to ask, but following today's COSIMA WG meeting, I thought it would be very useful to have a comprehensive table or document about what each character combination means in terms of locations on the staggered grids. And I thought that comparisons to other models would also be quite useful IMHO (OM2/MOM5, but also others like NEMO, POP, mitGCM, or Oceananigans).

Sometimes the tracer cell center is t (for "tracer" I think), sometimes h like here, sometimes c or CC for center (Oceananigans). Using u and v as locations can also be ambiguous if the Arakawa grid type is not clearly defined or can vary (B vs C for example). Sometimes corners are f, or q, and I'm guessing at least one model calls it c for "corner". And then there are vertical locations as well.

In short, navigating these names is confusing, so it would be great to have a document clarifying these somewhere. Not sure such a document should live here BTW, I'm just starting a discussion. Maybe there should be one per ACCESS model, and one that compares these names across ACCESS models?

I am sure one could an LLM to draft such a doc and then the knowledgable devs can "just" proof-read it? 🥺😅

But maybe something already exist somewhere? In this case just pointing to it near

decoding-om3/documentation/docs/pages/decoding_mom6.md

Lines 721 to 735 in 86861f6

	We need to understand how MOM6's grid is defined.
	Here are two different ways to visualise the C-grid that is used by MOM6.
	- The first way shows both the horizontal and vertical staggering. Note that the tracers, velocities and vorticity points are horizontally and vertically staggered:
	
	*Image from the [pycomodo project](https://web.archive.org/web/20160417032300/http://pycomodo.forge.imag.fr/norm.html).*
	- The second grid visualisation, focuses on the horizontal, and uses the the notation that is used in the MOM6 documentation:
	
	*Image from the [MOM6 RTD](https://mom6.readthedocs.io/en/dev-gfdl/api/generated/pages/Discrete_Grids.html).*

might be useful.

Of course, feel free to close quickly if this is just noise for this repo.

[chrisb13]

@briochemc thanks for coming along today and the great feedback. I've sent you an invite for this repository should you wish to make changes.

I love the idea of a table or similar! As I was writing the notes today, I kept thinking to myself, oh in NEMO "that" is called "this" and I agree it does get confusing but it helps to know the translation if you're familiar with a different model.

But maybe something already exist somewhere? In this case just pointing to it near

I think these documents might go some way to what you're after?

• https://xgcm.readthedocs.io/en/latest/xgcm-examples/02_mitgcm/
• https://xgcm.readthedocs.io/en/latest/xgcm-examples/03_MOM6/
• https://xgcm.readthedocs.io/en/latest/xgcm-examples/04_nemo_idealized/

I've spent a lot of time with the NEMO one when I was learning how to use XGCM. Personally, I found it challenging as I think much of the package (coming from Ryan A) has a MITgcm heritage. If you think they're relevant, please feel to add these links.

I am sure one could an LLM to draft such a doc and then the knowledgable devs can "just" proof-read it? 🥺😅

Fun idea! Copilot and I had a go at a diagram for this:

I don't know enough about the other models but the NEMO / MOM6 ones look ok to me (took some coercion). Although, I think the vertical MOM6 one should have h instead of T? Worth including in the notes?

Maybe there should be one per ACCESS model, and one that compares these names across ACCESS models?

I'm not sure I fully understand this suggestion but I think you mean a grid definition doc for each ACCESS model such as OM2, OM3, ESM1.5 etc? There would be a lot of redundancy but maybe it's useful to a user to be signposted such that it's clear? For example, ESM1.5 and OM2 share MOM5 so are both on the same b-grid. If this is the suggestion, I think it would be better brought up with the access hive docs team. It's possible to raise an issue here. CC'ing @paigem so she's aware.

Finally, it's a slightly different goal than what you describe but maybe of interest. At the COSIMA hackathon last year, there was a request to write a notebook that explains MOM's 5 and 6 grids (here is the accompanying PR). That effort ran out of steam but I think it would be appreciated if someone were to finish it, I'd be happy to review/collaborate... Perhaps today's notes could be useful in that sense?

Here's the related issue, started by @adele-morrison.

[briochemc]

Ha! I did not have "make the diagram" in mind for the LLM, but now it got me thinking the right approach is I think to first teach it to draw these precisely and then read the docs of the models to place the labels. I'm giving Claude a go with the typst cetz package. Will see how far I go!

---

FWIW I chose typst because it's like LaTeX but it essentially renders instantly, and cetz is the typst package for drawing stuff (first time using it), so then Claude can write code instead of generating images, and I can see the output straight away. Also makes it version-control friendly. My current attempts look like this for 2D and 3D (random labels):

and the code calling these is like for 2D (col-x are the colors; defined elsewhere):

#cetz.canvas({
  grid-cell(
    (
      "p",  "v",  "p",
      "u",  "T",  "u",
      "p",  "v",  "p",
    ),
    (
      col-p, col-v, col-p,
      col-u, col-t, col-u,
      col-p, col-v, col-p,
    ),
  )
})

and 3D:

#cetz.canvas({
  cube-cell(
    (
      // Top layer (z = s)
      "p",  "v",  "p",
      "u",  "w",  "u",
      "p",  "v",  "p",
      // Middle layer (z = s/2)
      "w",  none, "w",
      none, "T",  none,
      "w",  none, "w",
      // Bottom layer (z = 0)
      "p",  "v",  "p",
      "u",  "w",  "u",
      "p",  "v",  "p",
    ),
    (
      // Top layer
      col-p, col-v, col-p,
      col-u, col-t, col-u,
      col-p, col-v, col-p,
      // Middle layer
      col-t, none,  col-t,
      none,  col-t, none,
      col-t, none,  col-t,
      // Bottom layer
      col-p, col-v, col-p,
      col-u, col-t, col-u,
      col-p, col-v, col-p,
    ),
  )
})

[chrisb13]

Thanks, nice pic @briochemc!

FWIW I chose typst because it's like LaTeX but it essentially renders instantly, and cetz is the typst package for drawing stuff (first time using it), so then Claude can write code instead of generating images, and I can see the output straight away.

Oh interesting I hadn't heard of typst cetz, seems like it's based on TikZ...

Drawing with Typst made easy, providing an API inspired by TikZ and Processing.

I used pgf tikz a lot back in honours (a long time ago now!), a quick google seems to suggest it's still around. At the time I found Geogebra was really handy for knocking things up in a gui (File > Export > Graphics View as PGF/TikZ) and then tweaking afterwards (pre agents of course!) Seems like there's now similar options for typst.

In general, I'm in favour of using this kind of thing to render images for the reasons you describe. At some point we should think a little about what is easiest to integrate into where this image will go (it's preferable for maintenance to try and use one language). If it's going on a mkdoc page (e.g. hive docs, decoding mom6 etc) then mermaid is natively supported but it seems with plugins (1 and 2) things like cetz and pgf tikz are possible too. I'm ping'ing @atteggiani in case he's had any experience on integrating these tools? Or has a wider plan for the access-hive-docs-system? My impression is that mermaid won't be up to this particular kind of task. To get a sense of the kinds of images we'd prefer to text generate, you can see all current assets here:
https://github.com/ACCESS-Community-Hub/decoding-om3/tree/main/documentation/docs/assets

Having said all that, are the new LLM good at moving between languages for this kind of thing? If yes, we can focus on content and then think about the language choice problem later. (I had a quick go of one of Andy's ALE figures, seemed to do a perfect job..)

[briochemc]

This is what I had when I went to bed:
main.pdf

I just wanted something where I would see live updates without having to refresh manually, but I think the end goal should be some markdown document so mermaid could be used, but better would be plain SVGs I think. I was hoping that cetz+typst could output standalone SVGs of the figures. Will try that.

[briochemc]

Mermaid integrates nicely with markdown but I don't think it fits the bill for these diagrams, right? (I just looked at the docs and didn't see matching examples.)

FWIW with typst we can generate the SVGs from small "standalone" files that are easily modified and maintainable (they're not really standalone as they use functions, like cube-cell, defined in a separate file).

The typst file:

#import "standalone.typ": *

#cetz.canvas({
  axes(origin: (0.5, 5.2), axis-len: 1, k-up: false)
  cube-cell(
    (
      none,               "Cv\n[i,J,K]",              "Bu\n[I,J,K]",
      none,               "T\n[i,j,K]\ne",            "Cu\n[I,j,K]",
      none,               none,                       none,

      none,               "Cv\n[i,J,k]\nv\nabove",   "Bu\n[I,J,k]\nq\nleft",
      none,               "T\n[i,j,k]\nh,T,S",       "Cu\n[I,j,k]\nu",
      none,               none,                       none,

      none, none, none,
      none, none, none,
      none, none, none,
    ),
    (
      none,  col-v, col-q,
      none,  col-t, col-u,
      none,  none,  none,

      none,  col-v, col-q,
      none,  col-t, col-u,
      none,  none,  none,

      none, none, none,
      none, none, none,
      none, none, none,
    ),
  )
})

I can export the file above as SVG with a simple call to typst compile:

typst compile nemo-3d.typ mom6-3d.svg

and I get:

I guess we could remove the colors and the label positioning and hardcode these (this is all Claude's doing), leaving us with only the 27 entries for the 3D cube. And then we could actually maintain them as simple 9 line CSVs (with the 27 entries) for each model, and get some pipeline to parse the CSVs and write them in a typst template file to then compile to SVGs, which can then be integrated in any markdown document.

[briochemc]

BTW I'm definitely not married to typst/cetz (I mostly wanted to explore it for fun here). I just don't know what is a better alternative for doing this.

[briochemc]

I put the typst code in https://github.com/briochemc/grid_locations_doc in case someone wants to check it and play with it.

[briochemc]

Oh interesting I hadn't heard of typst, seems like it's based on TikZ...

This is not quite correct, so just to clarify: Typst is for writing documents, like LaTeX (but compiles almost instantly), while Cetz is for drawing stuff, like Tikz or GeoGebra.

[chrisb13]

This is not quite correct, so just to clarify: Typst is for writing documents, like LaTeX (but compiles almost instantly), while Cetz is for drawing stuff, like Tikz or GeoGebra.

Thanks yes, a typo on my part.