### 9 releases

new 0.2.6 | Oct 22, 2021 |
---|---|

0.2.5 | Oct 13, 2021 |

0.2.3 | Sep 19, 2021 |

0.1.1 | Sep 4, 2021 |

#**184** in Math

**54** downloads per month

**MIT**license

395KB

7.5K
SLoC

# Russell Sparse - Sparse matrix tools and solvers

*This crate is part of Russell - Rust Scientific Library*

This repository contains tools for handling sparse matrices and functions to solve large sparse systems.

Documentation:

## Installation

Install some libraries:

`sudo`` apt-get install \`
`liblapacke-dev`` \`
`libmumps-seq-dev`` \`
`libopenblas-dev`` \`
`libsuitesparse-dev`

Add this to your Cargo.toml (choose the right version):

`[``dependencies``]`
`russell_sparse ``=` `"`*`"`

### Optional: Use a locally compiled MUMPS library

The standard Debian

does not come with Metis or OpenMP that may lead to faster calculations. Therefore, it may be advantageous to use a locally compiled MUMPS library.`libmumps-seq-dev`

We just need the include files in

and a library file named `/usr/local/include/mumps`

in `libdmumps_open_seq_omp`

.`/usr/local/lib/mumps`

Follow the instructions from https://github.com/cpmech/script-install-mumps and then set the environment variable

:`USE_LOCAL_MUMPS``=``1`

`export` `USE_LOCAL_MUMPS``=``1`

### Number of threads

By default OpenBLAS will use all available threads, including Hyper-Threads that make the performance worse. Thus, it is best to set the following environment variable:

`export` `OPENBLAS_NUM_THREADS``=``<`real-core-count`>`

Furthermore, if working on a multi-threaded application, it is recommended to set:

`export` `OPENBLAS_NUM_THREADS``=``1`

## Examples

### Solve a sparse linear system

`use` `russell_lab``::``*``;`
`use` `russell_sparse``::``*``;`
`fn` `main``(``)`` ``->` `Result``<``(``)`, `&``'static` `str``>` `{`
`//` allocate a square matrix
`let` `mut` trip `=` `SparseTriplet``::`new`(``3``,` `3``,` `5``,` `Symmetry``::`No`)``?``;`
trip`.``put``(``0``,` `0``,` `0.``2``)``;`
trip`.``put``(``0``,` `1``,` `0.``2``)``;`
trip`.``put``(``1``,` `0``,` `0.``5``)``;`
trip`.``put``(``1``,` `1``,` `-``0.``25``)``;`
trip`.``put``(``2``,` `2``,` `0.``25``)``;`
`//` print matrix
`let` `(`m`,` n`)` `=` trip`.``dims``(``)``;`
`let` `mut` a `=` `Matrix``::`new`(`m`,` n`)``;`
trip`.``to_matrix``(``&``mut` a`)``?``;`
`let` correct `=` `"`┌ ┐`\n``\`
│ 0.2 0.2 0 │`\n``\`
│ 0.5 -0.25 0 │`\n``\`
│ 0 0 0.25 │`\n``\`
└ ┘`"``;`
`assert_eq!``(``format!``(``"``{}``"``,` a`)``,` correct`)``;`
`//` allocate rhs
`let` rhs1 `=` `Vector``::`from`(``&``[``1.``0``,` `1.``0``,` `1.``0``]``)``;`
`let` rhs2 `=` `Vector``::`from`(``&``[``2.``0``,` `2.``0``,` `2.``0``]``)``;`
`//` calculate solution
`let` config `=` `ConfigSolver``::`new`(``)``;`
`let` `(``mut` solver`,` x1`)` `=` `Solver``::`compute`(`config`,` `&`trip`,` `&`rhs1`)``?``;`
`let` correct1 `=` `"`┌ ┐`\n``\`
│ 3 │`\n``\`
│ 2 │`\n``\`
│ 4 │`\n``\`
└ ┘`"``;`
`assert_eq!``(``format!``(``"``{}``"``,` x1`)``,` correct1`)``;`
`//` solve again
`let` `mut` x2 `=` `Vector``::`new`(`trip`.``dims``(``)``.``0``)``;`
solver`.``solve``(``&``mut` x2`,` `&`rhs2`)``?``;`
`let` correct2 `=` `"`┌ ┐`\n``\`
│ 6 │`\n``\`
│ 4 │`\n``\`
│ 8 │`\n``\`
└ ┘`"``;`
`assert_eq!``(``format!``(``"``{}``"``,` x2`)``,` correct2`)``;`
`Ok``(``(``)``)`
`}`

## Sparse solvers

We wrap two direct sparse solvers: UMFPACK (aka **UMF**) and MUMPS (aka **MMP**). The default solver is UMF; however UMF may run out of memory for large matrices, whereas MMP still may work. The MMP solver is **not** thread-safe and thus must be used in single-threaded applications.

## Tools

This crate includes a tool named

to study the performance of the available sparse solvers (currently MMP and UMF). The `solve_mm_build`

suffix is to disable the coverage tool.`_build`

reads a Matrix Market file and solves the linear system:`solve_mm_build`

`a ⋅ x = rhs
`

with a right-hand-side containing only ones.

The data directory contains an example of Matrix Market file named

and you may download more matrices from https://sparse.tamu.edu/`bfwb62 .mtx`

Run the command:

`cargo`` run`` --`release` --`bin solve_mm_build` --`` data/matrix_market/bfwb62.mtx`

Or

`cargo`` run`` --`release` --`bin solve_mm_build` --`` --help`

for more options.

#### Dependencies

~**18MB**

~206K SLoC