List of functions in OrthogonalSphericalShellGrids

a structure to represent a tripolar grid on a spherical shell

TripolarGrid(arch = CPU(), FT::DataType = Float64;
             size,
             southernmost_latitude = -80,
             halo = (4, 4, 4),
             radius = R_Earth,
             z = (0, 1),
             north_poles_latitude = 55,
             first_pole_longitude = 70)

Construct a tripolar grid on a spherical shell.

Positional Arguments

• arch: The architecture to use for the grid. Default is CPU().
• FT::DataType: The data type to use for the grid. Default is Float64.

Keyword Arguments

• size: The number of cells in the (longitude, latitude, vertical) dimensions.
• southernmost_latitude: The southernmost Center latitude of the grid. Default is -80.
• halo: The halo size in the (longitude, latitude, vertical) dimensions. Default is (4, 4, 4).
• radius: The radius of the spherical shell. Default is R_Earth.
• z: The vertical $z$-coordinate range of the grid. Default is (0, 1).
• first_pole_longitude: The longitude of the first "north" singularity. The second singularity is located at first_pole_longitude + 180ᵒ.
• north_poles_latitude: The latitude of the "north" singularities.

Return

An OrthogonalSphericalShellGrid object representing a tripolar grid on the sphere. The north singularities are located at

i = 1, j = Nφ and i = Nλ ÷ 2 + 1, j = Nλ

TripolarGrid(arch::Distributed, FT::DataType = Float64; halo = (4, 4, 4), kwargs...)

Construct a tripolar grid on a distributed architecture. A distributed tripolar grid is supported only on a Y-partitioning configuration, therefore, only splitting the j-direction is supported for the moment.

ZipperBoundaryCondition(sign = 1)

Create a zipper boundary condition specific to the TripolarGrid. A Zipper boundary condition is similar to a periodic boundary condition, but, instead of retrieving the value from the opposite boundary, it splits the boundary in two and retrieves the value from the opposite side of the boundary. It is possible to think of it as a periodic boundary over a folded domain.

When copying in halos, folded velocities need to switch sign, while tracers or similar fields do not.

Note: the Tripolar boundary condition is particular because the last grid point at the north edge is repeated for tracers. For this reason we do not start copying the halo from the last grid point but from the second to last grid point.

Example

Consider the northern edge of a tripolar grid where P indicates the j - location of the poles

                  P                         P
                  |            |            |            |            
 Ny (center) ->   u₁    c₁     u₂    c₂     u₃    c₃     u₄    c₄     
 Ny (face)   ->   |---- v₁ ----|---- v₂ ----|---- v₃ ----|---- v₄ ----
                                                      Nx    Nx
                                                    (face) (center)

The grid ends at Ny because it is periodic in nature, but, given the fold,

c₁ == c₄

and

c₂ == c₃

This is not the case for the v-velocity (or any field on the j-faces) where the last grid point is not repeated. Because of this redundancy, we ensure consistency by substituting the redundant part of fields Centered in x, in the last row.

_compute_tripolar_coordinates!(λFF, φFF, λFC, φFC, λCF, φCF, λCC, φCC, 
                               λᶠᵃᵃ, λᶜᵃᵃ, φᵃᶠᵃ, φᵃᶜᵃ, 
                               first_pole_longitude,
                               focal_distance, Nλ)

Compute the tripolar coordinates for a given set of input parameters. Here, we follow, the formulation described by

Ross J. Murray, (1996). Explicit generation of orthogonal grids for ocean models, Journal of Computational Physics, 126(2), 251-273.

The tripolar grid is built as a set of cofocal ellipsed and perpendicular hyperbolae. The focal_distance argument is the distance from the center of the ellipses to the foci.

The family of ellipses obeys:

\[\frac{x²}{a² \cosh²(ψ)} + \frac{y²}{a² \sinh²(ψ)} = 1\]

While the family of perpendicular hyperbolae obey:

\[\frac{x²}{a² \cosh²(λ)} + \frac{y²}{a² \sinh²(λ)} = 1\]

Where $a$ is the focal_distance to the center, $λ$ is the longitudinal angle, and $ψ$ is the "isometric latitude", defined by Murray (1996) and satisfying:

\[ a \sinh(ψ) = \mathrm{tand}[(90 - φ) / 2]\]

The final $(x, y)$ points that define the stereographic projection of the tripolar coordinates are given by:

\[ \begin{align} x & = a \sinh ψ \cos λ \\ y & = a \sinh ψ \sin λ \end{align}\]

for which it is possible to retrieve the longitude and latitude by:

\[ \begin{align} λ &= - \frac{180}{π} \mathrm{atan}(y / x) \\ φ &= 90 - \frac{360}{π} \mathrm{atan} \sqrt{x² + y²} \end{align}\]