The `MatrixFields` module has no user documentation
- Dominant language
- Julia
- Stars
- 117
- Forks
- 19
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 41
Description
The [documentation for MatrixFields](https://clima.github.io/ClimaCore.jl/dev/matrix_fields/#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 `FieldMatrix`s are supposed to represent and there are several levels of abstractions to go through.
Another example, I (think) I have a `FieldMatrix`s 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
```
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the linked MatrixFields documentation and the MatrixFields and FieldMatrix concepts named in the issue. Define a user-oriented mental model, explain how space information is represented, clarify printed representations such as DiagonalMatrixRow and UniformScaling, and include guidance for checking NaN values; done means users can answer these questions from the documentation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- julia
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100