The `MatrixFields` module has no user documentation

The documentation for MatrixFields gives a high-level description of what the module is about, but does not provide guidance on how to use these objects.

For example, the question I am currently trying to answer is "do I have any NaN in my MatrixFields"? I find myself unable to tackle this question.

I still don't have a mental model of FieldMatrixs are supposed to represent and there are several levels of abstractions to go through.

Another example, I (think) I have a FieldMatrixs that represent an identity. When I print it, I see

myJ[@name(c.ρ), @name(c.ρ)] = ClimaCore.MatrixFields.DiagonalMatrixRow{Float32}-valued Field whose first column corresponds to the Square matrix
 0.0   ⋅    ⋅    ⋅    ⋅    ⋅    ⋅    ⋅    ⋅    ⋅ 
  ⋅   0.0   ⋅    ⋅    ⋅    ⋅    ⋅    ⋅    ⋅    ⋅ 
  ⋅    ⋅   0.0   ⋅    ⋅    ⋅    ⋅    ⋅    ⋅    ⋅ 
  ⋅    ⋅    ⋅   0.0   ⋅    ⋅    ⋅    ⋅    ⋅    ⋅ 
  ⋅    ⋅    ⋅    ⋅   0.0   ⋅    ⋅    ⋅    ⋅    ⋅ 
  ⋅    ⋅    ⋅    ⋅    ⋅   0.0   ⋅    ⋅    ⋅    ⋅ 
  ⋅    ⋅    ⋅    ⋅    ⋅    ⋅   0.0   ⋅    ⋅    ⋅ 
  ⋅    ⋅    ⋅    ⋅    ⋅    ⋅    ⋅   0.0   ⋅    ⋅ 
  ⋅    ⋅    ⋅    ⋅    ⋅    ⋅    ⋅    ⋅   0.0   ⋅

What does this mean? Is "first column" referring to the space? Why a "first column" corresponds to a square matrix?

Osmosys with @dennisYatunin helped me making progress in understanding these objects since I started working with them. One of the misconception I had until a couple of days ago was that they didn't include space information. This misconception was informed by examples like

@. W.matrix[@name(my_var), @name(my_var)] = dtγ * div_matrix() ⋅ grad_matrix() - (LinearAlgebra.I,)

where there is no space information on the right-hand side. (Now, I see how the space comes to be: it is in pre-defining W)

EDIT: The matrix field I thought being an identity was, in fact, not an identity. Now, when I print it, I get

LinearAlgebra.UniformScaling{Bool}
true*I

CliMA / ClimaCore.jl

The `MatrixFields` module has no user documentation #1985