dimforge / dimforge/nalgebra

Imprecise documentation for solving linear equations.

Open
#978 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
4.8k
Forks
565
PR merge metrics
No merged PRs in 30d

Description

Hi, thanks for the crate. I'm new to Rust, so this request might not have much sense. I was looking for some linear solvers but encountered the following problem.

In the description of the functions `.solve()` and `.solve_mut()` on the [website](https://nalgebra.org/docs/user_guide/decompositions_and_lapack/) omitted conditions on the matrix `A` which has firstly to be decomposed. “where `A` is represented by `self` and `x` the unknown”, `self` is more likely to be understood as a matrix itself rather than its factorization. If one tried to read the [documetation](https://docs.rs/nalgebra/0.29.0/nalgebra/base/struct.Matrix.html) for details, then it is not clear where to find a `.solve()` method. After implementing the method to the matrix directly, the only received message is “no method is found for this struct”.

# Request

It would be helpful to see:
1) a mention on the [userguide website](https://nalgebra.org/docs/user_guide/decompositions_and_lapack/) of the decomposition as a requirement.
2) Alternatively (or in addition), a default decomposition could be implemented for a `matrix.solve(&vector)` with a warning from the compiler that the decomposition is default or is required.
3) Also, to add a mention of these methods on the [website](https://docs.rs/nalgebra/0.29.0/nalgebra/base/struct.Matrix.html) since it is not clear where to look for them.

# Details
Here are the default choices for the decomposition in other languages:
- Julia
- [LU default](https://docs.julialang.org/en/v1/stdlib/LinearAlgebra/#Base.:\\)
- Python numpy
- [No idea, reference to LAPACK](https://numpy.org/doc/stable/reference/generated/numpy.linalg.solve.html?highlight=solve#numpy.linalg.solve)
- R
- [No idea, reference to Fortran](https://www.rdocumentation.org/packages/base/versions/3.6.2/topics/solve)
- ndarray
- [only LU (and by default)](https://docs.rs/ndarray-linalg/0.14.1/ndarray_linalg/solve/index.html)

# Help
I would be happy to help making any changes to make the description more understandable.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.