Incorporate a Reference Coordinate System for the CubeSphere Spatial Discretization

[cfangwen-uofm]

Description

I have added a reference coordinate system for the incoming cubesphere horizontal fluid solver. The reference coordinate system includes generation of the coordinates from lat-lon coordinates and a radius of the earth (inferred from the (0,0) position of each CubeSphere faces); the system also includes transformation matrices ($A$, $A^{-1}$, $g^{ij}$, $\sqrt{g}$) and metrics that is used to convert between spherical vectors and reference (contravariant) vectors.

Along with the new coordinate system implemented under Grid class, there are also multiple tool additions under tool.h/.cpp: 1) a struct for 2x2 matrix that is partitioned into 4 arma_cubes which has the size of the spatial discretization. 2) is_approx_equal() family to check whether two arma_vec/arma Row vector are the same. 3) is_approx_constant() to check whether the vector (no arma_cube overload currently) is a constant vector using statistical variance as evaluating factor. 4) Two generic vector transformation functions sphvect2ref() and refvect2sph().

Also included in edu/examples/Advection is a toy code for the CubeSphere FVM method on one face.

CMakeList.txt is altered to allow addition of a main() executable for unit testing.

The new addition may cause other module to not work correctly, but was not found on the PR initiator's behalf.

Type of change

• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

How Has This Been Tested?

A series of unit tests are performed in MPI multiprocessing environment. The unit test can be invoked by setting CMake variable TEST_COORD to be true and turning off all other unit test boolean variable. The unit test must be ran with exactly 6 processes because there is a check for the range of the reference coordinate system generated, or the unit test would throw an exception.

The following unit tests are performed on the new reference coordinate system for every processes (CubeSphere face): 1) The reference coordinate system must be equidistant (and the condition that rows of y must be the same, cols of x must be the same is a prerequisite for this test) 2) The reference coordinate system (edge coordinates) must range exactly from -a to a, where a = R/sqrt(3). It cannot range from a to -a. 3) Transformation matrices must have the following properties:

1. $(A^{-1}A^{-T}) = g^{ij}$
2. $(A^T A) = g{ij} = {g^{ij}}^{-1}$ where $A$, $A^{-1}, g^{ij}$ are computed natively using formulas (see pending Aether documentation), not with the properties above. 4) det(g) computed with formula must match with $g{ij} = {g^{ij}}^{-1}$ computed with $A$ matrix. 5) sphvect2ref() and refvect2sph() can convert vector inputs back and forth with $A$ and $A^{-1}$.

Test configuration

• Operating system: Pop!_OS 21.10 (Linux 5.18.10)
• Compiler, version number: gcc (Ubuntu 11.2.0-7ubuntu2) 11.2.0

Checklist:

• [x] Make sure you are merging into the develop (not master) branch
• [ ] My code follows the style guidelines of this project -> Did not run cpplint
• [x] I have performed a self-review of my own code
• [x] I have commented my code, particularly in hard-to-understand areas
• [x] I have made corresponding changes to the documentation
• [x] My changes generate no new warnings
• [x] I have added tests that prove my fix is effective or that my feature works
• [x] New and existing unit tests pass locally with my changes
• [ ] Any dependent changes have been merged and published in downstream modules
• [N/A] Add a note to CHANGELOG.md, summarizing the changes

[cfangwen-uofm]

sphvect2ref() and refvect2sph() can probably be boiled down to a generic function since both just utilizes a 2x2 transformation matrix to convert vectors back and forth. Can add a patch on that.