Adding Covariant/Contravariant Vector Documentation and Visualization

[yiyuef]

Hi,

I would like to add some more explanation about covariant components and controvariant components in the docmument.

Meanwhile, following the comments under this issue, I am adding documentations here, visualizing the AxisTensors.

The documentation is with the aim of providing the user with clear and easing understanding of the definition of AxisTensor, and how they are transformed between one another.

Thank you!

[yiyuef]

Hi @Sbozzolo @dennisYatunin !

As discussed in the issue #2234, @charleskawczynski expressed an idea about visualizing the AxisTensor using Makie.jl, as well as how they transform. I am super interested in contributing to this issue!

I just manually ran all the tests here, where I can see how controvariant and covariant vectors are defined. But would you be able to explain a little bit more about the transform itself? Is it like from the cartisian axis to a spherical axis?

Thanks!

[Sbozzolo]

@dennisYatunin

[dennisYatunin]

Hello, @yiyuef. Thank you for offering to contribute to our documentation! The full description of CliMA's dynamical core is available as a preprint here. For background on our generalized coordinates and covariant/contravariant vectors, see Section 4.1. For an overview of how we implement our discretization, see Section 5.1, and for a full detailed explanation see Appendix C. The specific transformation between Cartesian and spherical coordinates that you are referring to is given in Equations C1, C2, and C3.

Please ensure that any documentation you write uses exactly the same notation and jargon as the dycore paper. The current ClimaCore documentation is out-of-date and rather confusing (e.g., what we call CovariantVectors are aligned with the contravariant basis vectors, but have covariant components), so just reference the paper where possible. In several months, I intend to refactor much of ClimaCore's Geometry module to simplify the code and bring the documentation in alignment with the dycore paper, but in the meantime any contributions are still welcome.

Feel free to tag me once you have documentation that is ready for review!

[valeriabarra]

Hi @yiyuef , thank you for your contribution!

Until you delete the unnecessary file YiyueTest/yiyueTest.jl, the JuliaFormatter GitHub Action check will complain.
Please remove it and see if all tests (including the doc build) pass. Thank you!

[valeriabarra]

Hi @yiyuef , it appears like the extra files are still there.

To test the documentation build locally and make sure that it looks how you intended it to look, please refer to the Contributing guide and post screenshots of your local build results here in the PR convo so we can have a quick preview of the docs. Thank you

[yiyuef]

Hi @yiyuef , it appears like the extra files are still there.

To test the documentation build locally and make sure that it looks how you intended it to look, please refer to the Contributing guide and post screenshots of your local build results here in the PR convo so we can have a quick preview of the docs. Thank you

Sorry, I deleted this extra file locally and did git push, I just realized that git push only update commits. Now I just did git rm -r and git pushed this commit. So now it should be good.

[yiyuef]

Hi @dennisYatunin !

Thank you for you explanation and information. Right now I added more illustration and examples about the CovariantVectors and ContravariantVectors to help users better understanding these concepts. I think the polar coordintate example would expecially help.

I am also thinking of re-drawing the figure I captured from the paper. I think I can try to make those bases more "perpendicular" and "tangent"? Would this be a good idea? (Can be a new PR or I can further modify this one). Now I am just using the one from paper in the .md file.

Thanks!

[valeriabarra]

We need to also add a journal entry, otherwise when building the docs, we get the following error:

┌ Error: Entry Yatunin2025 is missing the journal field(s).
└ @ BibInternal ~/.julia/packages/BibInternal/2EG8G/src/bibtex.jl:89

Add:

Suggested change

	publisher = {ESS Open Archive}
	publisher = {ESS Open Archive},
	journal = {Journal of Advances in Modeling Earth Systems}

[yiyuef]

done!

[valeriabarra]

Hi @yiyuef, I still have a question about the notation you used in your figure. To be consistent with the figure above from the paper, shouldn't your covariant components be defined in terms of contravariant bases, i.e., use the superscript for the unitary vectors "e", as in:

Suggested change

	while perpendicular projections would lead to covariant components $b_{1} = \mathbf{b}\cdot \mathbf{e}_1$ and $b_{2} = \mathbf{b}\cdot \mathbf{e}_2$.
	while perpendicular projections would lead to covariant components $b_{1} = \mathbf{b}\cdot \mathbf{e}^1$ and $b_{2} = \mathbf{b}\cdot \mathbf{e}^2$.

?

Therefore, also the unitary "e" vectors in the figure should have superscripts rather than subscripts?
Thank you.

[yiyuef]

Prof. Barra, Sorry for the delay.

So $\mathbf{e}_1$ and $\mathbf{e}_2$ in my figure is exactly covariant basis, thus $a^{1}$ and $a^{2}$ are contravariant components. This is no problem right?

Then, what I want to convey next is that $\mathbf{b}\cdot \mathbf{e}_1$ and $\mathbf{b}\cdot \mathbf{e}_2$ themselves are covariant components. And I didnt specify any contravariant basis related to them.

I am not sure if this would be a clear explanation.

[valeriabarra]

Hi @dennisYatunin , please take a look at this quick documentation PR. If it does look to you and think that might be a useful contribution to the docs, it is fine to merge by me. As far as I am concerned, I am still a bit unsure about the notation used in this figure to match the one in the paper. Thank you!