JuliaPhysics / JuliaPhysics/Unitful.jl

Diagonal example in documentation

Open
#343 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Julia
Stars
675
Forks
124
Avg merge
3h 38m
Merged PRs (30d)
1

Description

The documentation includes the following example (in highlights.md):
> ```julia
> julia> Diagonal([-1.0u"c^2", 1.0, 1.0, 1.0])
> 4×4 Diagonal{Unitful.Quantity{Float64,D,U}}:
> -1.0 c^2 ⋅ ⋅ ⋅
> ⋅ 1.0 ⋅ ⋅
> ⋅ ⋅ 1.0 ⋅
> ⋅ ⋅ ⋅ 1.0
> ```

However, this does not actually work:
```julia
julia> using Unitful

julia> using LinearAlgebra: Diagonal

julia> Diagonal([-1.0u"c^2", 1.0, 1.0, 1.0])
4×4 Diagonal{Quantity{Float64,D,U} where U where D,Array{Quantity{Float64,D,U} where U where D,1}}:
Error showing value of type Diagonal{Quantity{Float64,D,U} where U where D,Array{Quantity{Float64,D,U} where U where D,1}}:
ERROR: ArgumentError: zero(Quantity{Float64,D,U} where U where D) not defined.
[...]
```

I’m not sure why the display method needs the `zero` element. However, even if the `show` method would be “fixed” to not use `zero`, the off-diagonal elements of the matrix can still not be accessed:
```julia
julia> a = Diagonal([-1.0u"c^2", 1.0, 1.0, 1.0]);

julia> a[1,2]
ERROR: ArgumentError: zero(Quantity{Float64,D,U} where U where D) not defined.
```

Since a lot of methods are specialized for `Diagonal`, the off-diagonal elements will probably not be accessed that often. So this could still be kept as an example, even if the off-diagonal elements of the matrix are not defined.

Therefore, I see two options:
* Change the `show` methods for `Diagonal` (in LinearAlgebra, not Unitful) to not use `zero`. The problem that the off-diagonal cannot be accessed would still exist.
* Change or remove the example in the Unitful documentation.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading the Diagonal example in highlights.md and reproducing the documented Julia commands with Unitful and LinearAlgebra. Confirm the displayed failure, then update or remove the example so the documentation no longer presents a non-working example; verify the revised documentation example behaves as described.

Written by the indexing model from the issue text.

Assessment

Tech stack
julia
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.