Shared ocean spherical convergence analysis step

[cbegeman]

This PR introduces a new step class, SphericalConvergenceAnalysis that performs the analysis step for a convergence study, computing the convergence rate and generating a figure. Two error measures are available, L2 and L-infinity. The exact_solution method is set to the initial state, but can easily be modified for test cases by overriding this method in their analysis steps.

I also implemented this step in the cosine_bell case to demonstrate its functionality. cosine_bell is BFB with main, but the convergence rates differ because an area-weighted version of the L2 norm is used instead of the original unweighted L2 norm. I removed the differentiation of convergence rates between QU and icosahedral meshes. In my view, the acceptable convergence rates should be set by the solution methods. This change could be reverted by dropping a commit.

I will update the documentation once I get an initial review of the functionality.

Checklist

• User's Guide has been updated
• Developer's Guide has been updated
• API documentation in the Developer's Guide (api.md) has any new or modified class, method and/or functions listed
• Documentation has been built locally and changes look as expected
• Testing comment in the PR documents testing used to verify the changes
  New tests have been added to a test suite

[cbegeman]

Testing

The cosine bell test cases with viz have been run on Chrys with intel, openmpi.

[xylar]

@cbegeman, I just merged #125. If you can rebase this, that would make the review a little easier. Thank you!

[xylar]

This is going to be amazing to have! It was an excellent idea!

I have a few changes to suggest. And there's obviously some documentation needed.

[xylar]

It's great to know that this works! I think I had had trouble with years lower than around 1600 in the past but maybe this has been fixed. I'm also surprised that the xtime variable can be decoded with decode(). This must be a recent improvement in xarray.

[cbegeman]

This reminds me -- I was wondering if there is another common place this should live in the framework. I could see us invoking this in a lot of analysis steps. Or maybe this should live in MPAS-Tools?

[xylar]

Maybe we could have a polaris.time module and put that there? It would be really handy to have something equivalent for converting from seconds to xtime values, and that could also go there in the future.

[xylar]

I removed the differentiation of convergence rates between QU and icosahedral meshes. In my view, the acceptable convergence rates should be set by the solution methods. This change could be reverted by dropping a commit.

Okay, that makes sense. In which case the min threshold is set by the QU meshes for all practical purposes. Does it make sense to keep the max? I'm not sure anyone will notice the warning if it gets exceeded.

[cbegeman]

I removed the differentiation of convergence rates between QU and icosahedral meshes. In my view, the acceptable convergence rates should be set by the solution methods. This change could be reverted by dropping a commit.

Okay, that makes sense. In which case the min threshold is set by the QU meshes for all practical purposes. Does it make sense to keep the max? I'm not sure anyone will notice the warning if it gets exceeded.

@xylar I don't see a strong reason to keep the max convergence rate. Are you ok with me removing it from the shared analysis step as well as cosine_bell?

[xylar]

Are you ok with me removing it from the shared analysis step as well as cosine_bell?

Yep, go for it!

[cbegeman]

@xylar Thanks for reviewing! I think I've made all the changes you requested. I also finished editing the documentation. Let me know if you spot anything else.

[xylar]

A few more small changes to consider. In the meantime, I'll test this out.

[xylar]

And a few more things that I noticed in running the cosine bell and building the docs.

[xylar]

Okay, @cbegeman, I'm done reviewing for now. If you're okay with some suggested changes, I'll approve and we can get this in! If you want to iterate a bit more, that's fine, too.

[cbegeman]

@xylar I made just about all the changes you suggested. Let me know what you think about the remaining comments.

[xylar]

Looks good! We'll take care of pulling out the one function into polaris.time or something similar in a separate PR.

[xylar]

We might want to use the matplotlib style file that we use in the global viz plots.

We would need these imports (from polaris.viz.globe)

import sys
from typing import TYPE_CHECKING  # noqa: F401

if TYPE_CHECKING or sys.version_info >= (3, 9, 0):
    import importlib.resources as imp_res  # noqa: F401
else:
    # python <= 3.8
    import importlib_resources as imp_res  # noqa: F401
...

and then:

Suggested change

	fig = plt.figure()
	style_filename = str(
	imp_res.files('polaris.viz') / 'polaris.mplstyle')
	plt.style.use(style_filename)
	fig = plt.figure()

Without this, the plots have different font sizes before and after the viz has run:

[xylar]

Let's decide if we want to do this in a separate PR...

[xylar]

I reran all 4 cosine bell tests successfully. Aside from the weird change in font size I noted above for future follow-up, everything is great!