Grids now have a topology

[ali-ramadhan]

This PR adds grid topologies: Periodic, Bounded, and Singleton. We should finalize our choice of named before merging.

As topology is now a required kwarg of all grid constructors tons of refactoring was needed. It also does a bit of cleanup: AbstractGrid is now defined in the Grids submodule, and grids no longer have the Tx, Ty, Tz property (total number of grid points).

Documentation should be updated before this PR is merged.

Resolves #446
Resolves #459
Resolves #489

[codecov]

Codecov Report

Merging #614 into master will increase coverage by 0.03%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master     #614      +/-   ##
==========================================
+ Coverage   74.55%   74.59%   +0.03%     
==========================================
  Files         117      118       +1     
  Lines        2209     2220      +11     
==========================================
+ Hits         1647     1656       +9     
- Misses        562      564       +2     

Impacted Files	Coverage Δ
src/BoundaryConditions/boundary_condition_types.jl	100.00% <0.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 11c41e1...3bef9da. Read the comment docs.

[glwagner]

I don’t like “Singleton”: Periodic and Bounded refer to the physical nature of the dimension, while Singleton obliquely references the size of an underlying array of discrete data. A better name would refer to the physical nature of the coordinate; “Uniform” or “Flat” are examples.

It could make sense to make (Periodic, Periodic, Bounded) a default. This is already the default of Model.

[ali-ramadhan]

I don’t like “Singleton”: Periodic and Bounded refer to the physical nature of the dimension, while Singleton obliquely references the size of an underlying array of discrete data. A better name would refer to the physical nature of the coordinate; “Uniform” or “Flat” are examples.

We're setting up a discrete model anyways, but I guess if it's supposed to model some physical system then "Singleton" may not be completely appropriate.

I'd vote for Flat over Uniform then. Uniform could be multiple grid points while Flat strongly implies one grid point (while both imply homogenous dynamics in that dimension).

It could make sense to make (Periodic, Periodic, Bounded) a default. This is already the default of Model.

Yeah I guess we have a choice here: do we want to make horizontally periodic the default or are users now required to specify a grid topology?

I could see benefits either way. Keeping it the default would introduce no breaking changes and simplify the tests, but requiring it would improve the clarity of most scripts (an issue that has been brought up before, see #459). I think most real scripts (not tests) should be specifying a topology for clarity.

[ali-ramadhan]

Another design we can consider is something like:

grid = RegularCartesianGrid(size=(x=128, z=64), x=(-1, 1), z=(-1, 0), topology=(x=Periodic, z=Bounded))

where since y has not been specified, it is assumed to be Flat.

This makes the grid constructors more verbose but has the added benefit of being clearer and not having to specify flat dimensions, i.e. it's an xz-model so y should not even be mentioned.

It would require a lot more refactoring though... but now's the time I guess.

[glwagner]

It would require a lot more refactoring though... but now's the time I guess.

I think explicit is better.

Why do we need to refactor? Why don't we just specify a default topology in the grid constructor? Then, the only refactoring we need to do is for models in the channel domain.

[glwagner]

I'd vote for Flat over Uniform then. Uniform could be multiple grid points while Flat strongly implies one grid point (while both imply homogenous dynamics in that dimension).

I'm fine with Flat. But the topology does not restrict how many grid points one uses. I don't see the point of doing that. We only need this for eliding derivative operations, not restricting user behavior.

[ali-ramadhan]

Why do we need to refactor? Why don't we just specify a default topology in the grid constructor? Then, the only refactoring we need to do is for models in the channel domain.

I'll add a default topology=(Periodic, Periodic, Bounded) then.

The bigger refactor would be if we decided to go with named tuples like size=(x=16, z=32) instead of just tuples size=(16, 1, 32).

I'm fine with Flat.

Flat it is then.

But the topology does not restrict how many grid points one uses. I don't see the point of doing that. We only need this for eliding derivative operations, not restricting user behavior.

True but I don't see the point of running with more than one grid point in a dimension that's supposed to be Singleton or Flat. But I guess users can do many weird things, and this wouldn't be the weirdest.

[glwagner]

Looks great.

[glwagner]

Is this preferred style? Why? I like fewer characters...

[glwagner]

Explicit imports might be nice here for all these physics terms... but we can save this for later.