CliMA / CliMA/ClimaCore.jl

The `MatrixFields` module has no user documentation

Open
#1,985 1 comment 0 reactions 0 assignees View on GitHub
bug 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.