Better documentation?

[dsm-72]

What are you trying to do?

I am trying to find a good Golang matrix library. One of the alternatives I have found is https://github.com/skelterjohn/go.matrix
which has a lot of useful features but seems dead compared to gonum (https://go.libhunt.com/gonum-alternatives).

Mostly I have found using gonum/mat feels very clunky. Perhaps I don't have good examples of how to use it...

What did you try?

Looked at the official documentation

https://pkg.go.dev/gonum.org/v1/gonum/mat#Dense.T

Notably, I don't see a good example of something like:

matA
matB

Diagonal(matA).MulElem(matA, matB.RawRowView(i))

How does Gonum not allow you to achieve your goal?

Just feels very clunky also vscode autocomplete can't find it under src but that is not on gonum.

What version of Go and Gonum are you using?

go version go1.20.4 darwin/arm64
v13

Is this feature absent from the current master?

yes

Are you able to help contribute the feature?

[kortschak]

Your example would be written as, given matA, an n×n, and matB an m×n, where i<m, and both are *mat.Dense,

var r mat.Dense
r.MulElem(matA.DiagView(), matB.RowView(i))

However, this issue does not really have a concrete issue to address and I'm not sure how we can take it forward, in particular, "clunky" is subjective and not something (irrespective of whether it's justified) can be really used as a working issue.

It's not clear to me what the issue is with the docs on *Dense.T. This is described fully in https://pkg.go.dev/gonum.org/v1/gonum/mat#hdr-The_Matrix_Interfaces and there are godoc examples of its use in https://pkg.go.dev/gonum.org/v1/gonum/mat#example-Cholesky, https://pkg.go.dev/gonum.org/v1/gonum/mat#example-Excerpt, https://pkg.go.dev/gonum.org/v1/gonum/mat#example-GSVD and https://pkg.go.dev/gonum.org/v1/gonum/mat#example-HOGSVD.

To be clear, the API provided by mat is not intended to follow linalg APIs in other languages like python or Julia (to take two examples). The API here is designed to more explicitly describe the machine work and also, significantly, to enable zero-copy implementations in client code where possible. The example above is a zero-copy implementation, and I'd say still really quite clear.

I would suggest that you try to implement what your maths requires and if you have well defined issues, ask at https://groups.google.com/g/gonum-dev, preferably providing the mathematical context (we have found that people often bring other languages' idioms to Gonum which either don't fit Gonum, or worse are mathematically suspect). If it turns out that there are things that you need that cannot be done, then it would be time to file an issue.

For examples, there are runnable examples in the godoc, https://pkg.go.dev/gonum.org/v1/gonum/mat#pkg-examples and descriptions with example syntax in the package-level docs. Further examples can be gleaned by reading the tests, https://github.com/gonum/gonum/tree/v0.13.0/mat.