documentation for averaging

[eclare108213]

• Short (1 sentence) summary of your PR:
  Mathematical description of various averages in space and time
• Developer(s):
  @eclare108213
• Suggest PR reviewers from list in the column to the right.
• Please copy the PR test results link or provide a summary of testing completed below.
  No changes to code, only documentation. See section 4.9.3 in https://cice-consortium-cice--1056.org.readthedocs.build/en/1056/developer_guide/dg_other.html.
• How much do the PR code changes differ from the unmodified code?
  • bit for bit
  • different at roundoff level
  • more substantial
• Does this PR create or have dependencies on Icepack or any other models?
  • Yes
  • No
• Does this PR update the Icepack submodule? If so, the Icepack submodule must point to a hash on Icepack's main branch.
  • Yes
  • No
• Does this PR add any new test cases?
  • Yes
  • No
• Is the documentation being updated? ("Documentation" includes information on the wiki or in the .rst files from doc/source/, which are used to create the online technical docs at https://readthedocs.org/projects/cice-consortium-cice/. A test build of the technical docs will be performed as part of the PR testing.)
  • Yes
  • No, does the documentation need to be updated at a later time?
    • Yes
    • No
• Please document the changes in detail, including why the changes are made. This will become part of the PR commit log.
  There is a great deal of confusion about how various history variables are time-averaged, e.g. SIMIP history output implementation #1038, Fixes for sitemptop, sitempbot, and sitempsnic. #1054. This PR attempts to clarify the situation. These averages are also relevant for conservative coupling.

[eclare108213]

Once this is all written out, it is obvious, but there seems to always be confusion about what is an ice average versus a cell average, when to multiply or divide by ice area when time averaging, what to do with various kinds of tracers, etc, so I think this documentation could be useful to users and developers. It's more detailed than necessary, but some of the confusion is because those details aren't always clear (e.g. sum(a_n) = 1 when summed over the whole grid cell and the grid cell areas cancel, which obfuscates the units).

@dabail10 I did not attempt to insert the 'intrinsic' and 'extrinsic' labels, but we could if it's helpful. I hope these definitions are indeed what SIMIP recommends!

I'm sure you'll all point out typos and other errors...

[anton-seaice]

This look useful - thanks @eclare108213 !

Is it worth having a seperate page now for history output ? (Although this content is a bit more general - its true for all cases of averaging of quantities right ?)

[apcraig]

For those that want to have a look, the updated section in the PR build in readthedocs is

https://cice-consortium-cice--1056.org.readthedocs.build/en/1056/developer_guide/dg_other.html#averages

This looks OK to me, are we ready to merge?

[anton-seaice]

Looks good to me

As @eclare108213 has said - adding some information on averages which are only accumulated when there is sea ice would be good (e.g. the Notz 2016 "intensive" averages)

[eclare108213]

I'll add some comments about intensive / extensive variables. Please, would one of you post (or email to me) the paper that has the definitions in it? I'm not sure I have it anymore. Thanks.

[dabail10]

gmd-9-3427-2016.pdf

[eclare108213]

I've added the intensive/extensive nomenclature to the averaging description, and I'm happy to report that it is consistent with my mathematical derivations. I think this PR is ready to merge but it needs an approving review.

[apcraig]

I did not check the math, but wow, that is complicated. I checked for readability and it seems fine.

[dabail10]

Finally getting around to this.

• I am confused by the very first equation. If capital A is the area, then I am confused by Ai(t). This is supposed to be the total ice area in time? Maybe instead of A for area, we could spell out "area"?
• It also seems like the equations for ice area are kind of redundant. I know you are trying to describe both the grid cell area and the area fraction.
• I get what you are doing by showing the integrals, but this makes the documentation very complicated to me. I wonder if just showing the finite difference equations? It does make sense and the math is consistent from what I can see.

[dabail10]

Also, earlier in the documentation there are references to Notz et al. 2016. I wonder if we should update for CMIP7. There is an article under review now here:

https://egusphere.copernicus.org/preprints/2025/egusphere-2025-3083/

And here is the link to the data request. This has some of the updated variables.

https://wcrp-cmip.org/cmip7-data-request-v1-0/

It has an "air table" which allows one to subset just the SImon and SIday fields.

[eclare108213]

• I am confused by the very first equation. If capital A is the area, then I am confused by Ai(t). This is supposed to be the total ice area in time? Maybe instead of A for area, we could spell out "area"?

A is the grid cell area, Ai is the ice area, both in sq. meters. A is constant in time.

• It also seems like the equations for ice area are kind of redundant. I know you are trying to describe both the grid cell area and the area fraction.

The difference is the units. I wrote them out explicitly so that what happens with the grid cell area is clear -- since ice area fraction is unitless, it's tempting to just multiply by it sometimes, not realizing that it implies a grid cell area too. I tried to clarify this better in the doc.

• I get what you are doing by showing the integrals, but this makes the documentation very complicated to me. I wonder if just showing the finite difference equations? It does make sense and the math is consistent from what I can see.

The finite difference equations obscure the units. Also, the intergrals as I have them written make clear what the averages actually are, e.g. time averaging over all the ice for the whole time interval versus time-averaging the category-averaged quantities. I added some text about that to the doc too.

Also, earlier in the documentation there are references to Notz et al. 2016. I wonder if we should update for CMIP7.

Is it just the reference that would need to be updated, or also the text? Since the new ref is still under review, I'm inclined to use the original ref, especially if the basic definitions are the same and don't affect the doc text as written. But we can add the new ref here (or perhaps better, as part of the history PR).

[apcraig]

I had another quick look at the resolved readthedocs section and it looks OK to me. Is this ready to merge?

[eclare108213]

As far as I'm concerned, yes, it's ready to merge. I'd welcome a review from @dabail10 or @anton-seaice or anyone else.