JuliaPhysics / JuliaPhysics/Unitful.jl
Diagonal example in documentation
- 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