Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README.md #89

Merged
merged 3 commits into from
Aug 22, 2022
Merged

Update README.md #89

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dc1e58e
Update README.md
amontoison Aug 20, 2022
b882296
Apply suggestions from code review
amontoison Aug 22, 2022
26d9bea
Update README.md
amontoison Aug 22, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Project.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
name = "MUMPS"
uuid = "55d2b088-9f4e-11e9-26c0-150b02ea6a46"
authors = ["Dominique Orban <dominique.orban@gmail.com>","William R Sweeney <wrsweeney2@gmail.com>"]
authors = ["Dominique Orban <dominique.orban@gmail.com>","William R Sweeney <wrsweeney2@gmail.com>", "Alexis Montoison <alexis.montoison@polymtl.ca >"]
version = "1.2.1"

[deps]
Expand Down
190 changes: 77 additions & 113 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,96 +1,57 @@
# A [Julia](http://julialang.org) Interface to [MUMPS](http://mumps.enseeiht.fr)

OSX and Linux: [![CI](https://github.com/JuliaSmoothOptimizers/MUMPS.jl/actions/workflows/ci.yml/badge.svg)](https://github.com/JuliaSmoothOptimizers/MUMPS.jl/actions/workflows/ci.yml)
[![](https://img.shields.io/badge/docs-latest-3f51b5.svg)](https://JuliaSmoothOptimizers.github.io/MUMPS.jl/latest)
[![Coverage Status](https://coveralls.io/repos/JuliaSmoothOptimizers/MUMPS.jl/badge.svg?branch=main&service=github)](https://coveralls.io/github/JuliaSmoothOptimizers/MUMPS.jl?branch=main)

MUMPS is a library for the solution of large linear systems using a
# A [Julia](http://julialang.org) Interface to [MUMPS](https://graal.ens-lyon.fr/MUMPS/index.php?page=home)

[![docs-stable][docs-stable-img]][docs-stable-url]
[![docs-dev][docs-dev-img]][docs-dev-url]
[![build-gh][build-gh-img]][build-gh-url]
[![build-cirrus][build-cirrus-img]][build-cirrus-url]
[![codecov][codecov-img]][codecov-url]
[![doi][doi-img]][doi-url]

[docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg
[docs-stable-url]: https://JuliaSmoothOptimizers.github.io/MUMPS.jl/stable
[docs-dev-img]: https://img.shields.io/badge/docs-dev-purple.svg
[docs-dev-url]: https://JuliaSmoothOptimizers.github.io/MUMPS.jl/dev
[build-gh-img]: https://github.com/JuliaSmoothOptimizers/MUMPS.jl/workflows/CI/badge.svg?branch=main
[build-gh-url]: https://github.com/JuliaSmoothOptimizers/MUMPS.jl/actions
[build-cirrus-img]: https://img.shields.io/cirrus/github/JuliaSmoothOptimizers/MUMPS.jl?logo=Cirrus%20CI
[build-cirrus-url]: https://cirrus-ci.com/github/JuliaSmoothOptimizers/MUMPS.jl
[codecov-img]: https://codecov.io/gh/JuliaSmoothOptimizers/MUMPS.jl/branch/main/graph/badge.svg
[codecov-url]: https://app.codecov.io/gh/JuliaSmoothOptimizers/MUMPS.jl
[doi-img]: https://img.shields.io/badge/DOI-10.5281%2Fzenodo.3271646-blue.svg
[doi-url]: https://doi.org/10.5281/zenodo.3271646

MUMPS is a library for the solution of large square linear systems using a
factorization. Structure can be exploited, such as symmetry, or symmetry and
definiteness. The factorization and solve phases can be performed in parallel
via MPI by way of [MPI.jl](https://github.com/JuliaParallel/MPI.jl).
In our experience, MPICH works more reliably than OpenMPI with MPI.jl.

## How to Install

### Prerequisites

Currently, MUMPS must be installed outside of Julia.
On macOS and Linux, we recommend using [Homebrew](https://brew.sh).

The commands to install MUMPS are:
```bash
$ brew tap brewsci/num
$ brew tap dpo/mumps-jl
$ brew install mpich-mumps # use brew options mpich-mumps for build options
```

Note: on Linux, `apt-get install libmumps-dev` installs a version of OpenMPI that is too old for MPI.jl, and installation will fail.
See the Troubleshooting section below.
## How to Cite

### Building MUMPS.jl
If you use MUMPS.jl in your work, please cite using the format given in [`CITATION.bib`](https://github.com/JuliaSmoothOptimizers/MUMPS.jl/blob/main/CITATION.bib)

If MUMPS and SCALAPACK are not in standard locations, you can help by setting the environment variables `MUMPS_PREFIX` and `SCALAPACK_PREFIX`.

The Homebrew method above installs MUMPS and SCALAPACK in nonstandard locations.
You can define
```JULIA
julia> prefix = chomp(String(read(`brew --prefix`)))
julia> ENV["MUMPS_PREFIX"] = joinpath(prefix, "opt", "mpich-mumps")
julia> ENV["SCALAPACK_PREFIX"] = joinpath(prefix, "opt", "mpich-scalapack")
```

At the Julia prompt, type
## How to Install

```JULIA
```julia
julia> ]
pkg> add MUMPS
pkg> build MUMPS
pkg> test MUMPS
```

## Troubleshooting

On macOS or Linux, if you see the error message
```
[ 11%] Building Fortran object CMakeFiles/gen_constants.dir/gen_constants.f90.o
│ /home/ubuntu/.julia/packages/MPI/U5ujD/deps/gen_constants.f90:43:43:
│
│ call output("MPI_NO_OP ", MPI_NO_OP)
│ 1
│ Error: Symbol ‘mpi_no_op’ at (1) has no IMPLICIT type
```
your OpenMPI library is [too old](https://github.com/JuliaParallel/MPI.jl/issues/39#issuecomment-441093933).

If you are running macOS and see error messages of the form
```
PMIx has detected a temporary directory name that results in a path that is too long for the Unix domain socket:

Temp dir:
/var/folders/rq/p5nq9tv17p5drlk49755jjz80000gn/T/openmpi-sessions-501@your_computer_name_0/44473

Try setting your TMPDIR environmental variable to point to something shorter in length
```
simply exit Julia and set the environment variable `TMPDIR` to, e.g., `\tmp`:
```bash
$ export TMPDIR=/tmp
```
The issue has to do with OpenMPI and is [documented in their faq](https://www.open-mpi.org/faq/?category=osx#startup-errors-with-open-mpi-2.0.x).

## How to Use

The main data type holding information on a factorization is `Mumps`. Remember
to initialize MPI before attempting to create a `Mumps` object. A simple
session is as follows:

````JULIA
julia> using MUMPS
julia> using MPI
julia> MPI.Init()
julia> A = sprand(10, 10, .2) + speye(10); rhs = rand(10)
julia> x = solve(A, rhs) # Mumps object is created and destroyed
julia> norm(x - A \ rhs) / norm(x)
2.640677159735313e-16
julia> MPI.Finalize() # if you're finished
````
```julia
using MUMPS, MPI, SparseArrays
MPI.Init()
A = sprand(10, 10, 0.2) + I
rhs = rand(10)
x = solve(A, rhs)
norm(x - A \ rhs) / norm(x)
MPI.Finalize()
```

It is possible to separate the initialization, the analysis/factorization,
and the solve phases. It is also possible to access the information reported by
Expand All @@ -99,23 +60,24 @@ MUMPS after the factorization and solve phases, and to modify this information

When creating an instance of a `Mumps` object explicitly, it is important to
specify in advance what arithmetic should be used. Single and double precision
real (`Float32` and `Float64`) and complex (`Complex64` and `Complex128`)
real (`Float32` and `Float64`) and complex (`ComplexF32` and `ComplexF64`)
arithmetics are supported.

For instance,

````JULIA
julia> MPI.Init()
julia> mumps = Mumps{Float64}(mumps_unsymmetric, default_icntl, default_cntl64) # Real, general unsymmetric
julia> A = sparse(rand(4,4)); rhs = rand(4) # Happens on all cores
julia> associate_matrix!(mumps, A)
julia> factorize!(mumps)
julia> associate_rhs!(mumps, rhs)
julia> solve!(mumps)
julia> x = get_solution(mumps)
julia> finalize(mumps)
julia> MPI.Finalize()
````
```julia
MPI.Init()
mumps = Mumps{Float64}(mumps_unsymmetric, default_icntl, default_cntl64)
A = sparse(rand(4,4))
rhs = rand(4)
associate_matrix!(mumps, A)
factorize!(mumps)
associate_rhs!(mumps, rhs)
solve!(mumps)
x = get_solution(mumps)
finalize(mumps)
MPI.Finalize()
```

Once the arithmetic of the `Mumps` instance has been specified, it cannot be
changed. The module is flexible in that various data types may be used to
Expand All @@ -125,11 +87,12 @@ converted to sparse format.

For intance,

```JULIA
julia> mumps = Mumps{Complex128}(mumps_unsymmetric, default_icntl, default_cntl64)
julia> A = rand(Int16, 4, 4); rhs = rand(Float32, 4)
julia> associate_matrix!(mumps, A) # A is converted to a sparse Complex128 matrix
julia> associate_rhs!(mumps, rhs) # rhs is converted to a Complex128 array
```julia
mumps = Mumps{ComplexF64}(mumps_unsymmetric, default_icntl, default_cntl64)
A = rand(Int16, 4, 4)
rhs = rand(Float32, 4)
associate_matrix!(mumps, A) # A is converted to a sparse ComplexF64 matrix
associate_rhs!(mumps, rhs) # rhs is converted to a Complex64 vector
```

See [test](https://github.com/JuliaSmoothOptimizers/MUMPS.jl/tree/main/test) for more examples.
Expand All @@ -150,15 +113,15 @@ Constant | Meaning
`default_cntl32` | array of default real parameters in single precision
`default_cntl64` | array of default real parameters in double precision

See Sections 5.1 and 5.2 of the [MUMPS User's Manual](http://mumps.enseeiht.fr/index.php?page=doc) for a description of the integer and real control arrays.
See Section 5 of the [MUMPS User's Manual](https://graal.ens-lyon.fr/MUMPS/index.php?page=doc) for a description of the integer and real control arrays.

### Methods

A `Mumps` object is created using the default constructor, which must be
supplied with:

* the data type for the arithmetic to be used, as a type parameter, i.e.,
`Mumps{Float64}(...)` or `Mumps{Complex128}(...)`
`Mumps{Float64}(...)` or `Mumps{ComplexF64}(...)`
* `sym`: one of the constants `mumps_unsymmetric`, `mumps_definite` or
`mumps_symmetric`. Note that there is no support for Hermitian complex
matrices in MUMPS. Therefore, we recommend to always use `mumps_unsymmetric`
Expand Down Expand Up @@ -191,23 +154,24 @@ Method | Description

## Parallel Execution

MPI is controled by way of [MPI.jl](https://github.com/lcw/MPI.jl).
MPI is controled by way of [MPI.jl](https://github.com/JuliaParallel/MPI.jl).
Look for the lines that say `NUMBER OF WORKING PROCESSES` in the output of

````
```shell
mpirun -np 4 julia examples/mumps_mpi.jl
````

## To Do (Pull Requests Welcome!)

* [X] Support double precision complex arithmetic (in [99c23fe](https://github.com/JuliaSmoothOptimizers/MUMPS.jl/commit/99c23fe87e7c985fe3062d78ab7664b82a6b8dba))
* [X] Support single precision real and complex arithmetic (in [654814a](https://github.com/JuliaSmoothOptimizers/MUMPS.jl/commit/654814a5e5800260011d2f26f7fb6de179609cfa))
* [ ] Support distributed matrices / vectors
* [ ] User-selected permutation
* [X] Out-of-core option (in [73e829b](https://github.com/JuliaSmoothOptimizers/MUMPS.jl/commit/73e829b52fe3d20c70c2733607ba9820cda03ed6#diff-d41d8cd98f00b204e9800998ecf8427e))
* [X] Determinant (in [73e829b](https://github.com/JuliaSmoothOptimizers/MUMPS.jl/commit/73e829b52fe3d20c70c2733607ba9820cda03ed6#diff-d41d8cd98f00b204e9800998ecf8427e))
* [X] Compute entries of the inverse (in [002b34eb](https://github.com/JuliaSmoothOptimizers/MUMPS.jl/commit/002b34eb861657118c05fa08f2b0eb5aababe22c))
* [X] Control iterative refinement (in [73e829b](https://github.com/JuliaSmoothOptimizers/MUMPS.jl/commit/73e829b52fe3d20c70c2733607ba9820cda03ed6#diff-d41d8cd98f00b204e9800998ecf8427e))
* [X] Obtain a Schur complement (in [002b34eb](https://github.com/JuliaSmoothOptimizers/MUMPS.jl/commit/002b34eb861657118c05fa08f2b0eb5aababe22c))
* [X] Solve with sparse right-hand sides (in [002b34eb](https://github.com/JuliaSmoothOptimizers/MUMPS.jl/commit/002b34eb861657118c05fa08f2b0eb5aababe22c))
* [ ] Sequential, version with no MPI requirement
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I opened issues to replace this list.

```

## Custom Installation

**Note: MUMPS is already precompiled with Yggdrasil for all platforms except Windows.**

To use your custom MUMPS, set the environment variable `JULIA_MUMPS_LIBRARY_PATH`
to point to the shared library before `using MUMPS`. Note that MUMPS version 5.5.1 is needed.

For example:
```julia
ENV["JULIA_MUMPS_LIBRARY_PATH"] = "~/Applications/MUMPS_5.5.1/lib"
using MUMPS
```

Alternatively, you can create an entry in `.julia/config/startup.jl` or set these permanently through your operating system.