RectilinearGrid metrics are described wrong in the docstring

[navidcy]

There is a mismatch between what the docstring of the RectilinearGrid claims for what the metrics (e.g., Δxᶜᵃᵃ or Δxᶠᵃᵃ) are and what the metrics actually correspond to.

The docstring says that, e.g., Δxᶜᵃᵃ is the distances between cell centers. I think this is wrong. First of all, this is not uniquely defined as, e.g., the distance between a cell center and the adjacent cell centers may be different on each side of the cell. I believe that Δxᶜᵃᵃ is, instead, the length of the corresponding cell that is centered at caa, or equivalently, is the distances between the adjacent faces of each cell's center. Note that for a regularly-spaced grid what I claim to be correct and what the docstring mentions are equivalent (and possibly this is what lead to the current docstring?). However, for a variably-spaced grid they are not equivalent. Here's an example:

julia> Nx = 3;  grid = RectilinearGrid(size = Nx, topology = (Bounded, Flat, Flat), x = [0, 1, 2, 10])
3×1×1 RectilinearGrid{Float64, Bounded, Flat, Flat} on CPU with 3×0×0 halo
├── Bounded  x ∈ [0.0, 10.0]      variably spaced with min(Δx)=1.0, max(Δx)=8.0
├── Flat y
└── Flat z

julia> grid.xᶜᵃᵃ[1:Nx]
3-element Vector{Float64}:
 0.5
 1.5
 6.0

julia> grid.xᶠᵃᵃ[1:Nx+1]
4-element Vector{Float64}:
  0.0
  1.0
  2.0
 10.0

julia> grid.Δxᶜᵃᵃ[1:Nx]
3-element Vector{Float64}:
 1.0
 1.0
 8.0

julia> grid.Δxᶠᵃᵃ[1:Nx+1]
4-element Vector{Float64}:
 1.0
 1.0
 4.5
 8.0

A schematic of the cell faces and centers together with the corresponding values for Δx is below:

             F    C     F     C      F           C            F

 xᶠᵃᵃ        0          1            2                       10
 xᶜᵃᵃ            0.5         1.5                6.0


Δxᶠᵃᵃ        1          1           4.5                       8
Δxᶜᵃᵃ             1           1                  8

I am pretty sure that what we want is what the code actually does. In this case, what's left to be done is simply to fix the docstring. Am I right?

(P.S.: I stumbled upon this while trying to fill the halos properly for #3239.)

[glwagner]

Δxᶜᵃᵃ is the distance between face nodes (located at centers), while Δxᶠᵃᵃ is the distance between centers (located at faces)

[navidcy]

Yes. That’s what I’m saying. The docstring says otherwise. Ok!

[glwagner]

Let's fix it!