API

module MUMPS

Both low-level interface with MUMPS 5.8.2 parallel direct solver C-library as well as convenient wrappers for some common uses for MUMPS.

The central work is done by the Mumps struct, which mirrors the internal structure used in MUMPS. Manipulations can be done directly on this object and then passed to Mumps via the function invoke_mumps! This mode of operation gives the user complete control as described in the MUMPS manual, though it exposes unsafe operations, so beware.

More convenient are the use of the functions mumps_solve, mumps_factorize, mumps_det, mumps_schur_complement, and mumps_select_inv, which all have mutating counterparts (such as mumps_solve!). These can take matrices and right hand sides directly, so, for example, the equation A*x=y, solved in Base by x=A\y or LinearAlbegra.ldiv!(x,A,y), can be solved with MUMPS as x=mumps_solve(A,y), or mumps_solve!(x,A,y).

The package also extends Base.det, Base.\, LinearAlgebra.ldiv! and LinearAlgebra.inv to work with mumps objects.

Note, unless working with the low-level interace, we discourage setting the JOB parameter manually, as this can lead to unsafe operation.

The goal is to give the advanced user low-level access to MUMPS, while simultaneously giving the ordinary user safe functions that grant access to most of what MUMPS has to offer.

Default single precision real parameters

Default double precision real parameters

Default integer parameters.

const mumps_definite

Constant indicating that a symmetric definite matrix will be analyzed and factorized

const mumps_symmetric

Constant indicating that a general symmetric matrix will be analyzed and factorized

const mumps_unsymmetric

Constant indicating that a general unsymmetric matrix will be analyzed and factorized

mutable struct MUMPSException

Exception type raised in case of error.

Enumeration of MUMPS job types; see MUMPS documentation for details.

Mirror of structre in [sdcz]mumps_c.h.

finalize(mumps)

Terminate a Mumps instance.

associate_matrix!(mumps, n, irow, jcol, vals)

Register the sparse matrix given in coordinate format with the Mumps object mumps. This function makes it possible to define the matrix on the host only. If the matrix is defined on all nodes, there is no need to use this function.

associate_matrix!(mumps,A; unsafe=false)

Register the square matrix A to a mumps object. It internally converts A to be consistent with the ICNTL[5] setting.

If needed, it tries to convert element type of A to be consistent with type of mumps, throwing a warning in this case.

Note that by default this function makes a copy of A. If you do not want to make a copy, pass unsafe=true. If the type of A needs to be converted, this function may copy A twice - to avoid this use unsafe=true.

When unsafe=true is passed, if the type of A is already consistent with the type of mumps, then pointers to A's memory are passed directly to MUMPS, so modifying A will modify the matrix in mumps. If A is not already consistent, a copy will be made when the type is converted. Warning: A dense, symmetric matrix will always be copied when it is converted to MUMPS's internal representation.

See also: associate_rhs!

associate_rhs!(mumps, rhs; unsafe=false)

Register a dense or sparse RHS matrix or vector rhs to a mumps object. It internally converts rhs to be consistent with the ICNTL[20] setting, and additionally allocates mumps.rhs according to the ICNTL[21] setting.

If needed, it tries to convert element type of rhs to be consistent with type of mumps, throwing a warning in this case.

Note that this function makes a copy of rhs. If you do not want to make a copy, pass unsafe=false. If the type of rhs needs to be converted, this function may copy rhs twice - to avoid this use unsafe=false.

When unsafe=false is passed, if the type of rhs is already consistent with the type of mumps, then pointers to rhs's memory are passed directly to MUMPS, so modifying rhs will modify the rhs in mumps. If rhs is not already consistent, a copy will be made when the type is converted.

See also: associate_matrix!

default_icntl!(mumps)

reset ICNTL to its default

display_cntl(mumps)

Show the complete CNTL real array of mumps, with descriptions

See also: set_cntl!

display_icntl(mumps)

Show the complete ICNTL integer array of mumps, with descriptions

See also: set_icntl!

factorize!(mumps,A)

Combined associate_matrix / factorize. Presume that A is available on all nodes.

factorize!(mumps)

Factorize the matrix registered with the Mumps instance. The matrix must have been previously registered with associate_matrix(). After the factorization, the determinant, if requested, is stored in mumps.det. The MUMPS error code is stored in mumps.err.

finalize!(mumps)

Release the pointers contained in mumps

See also: initialize!

get_icntl(;det=false,verbose=false,ooc=false,itref=0,user_perm=false)

Obtain an array of integer control parameters.

get_rhs!(x,mumps)

Retrieve right hand side from mumps, storing it in pre-allocated x

See also: get_rhs, get_sol!, get_sol

get_rhs(mumps) -> y

Retrieve right hand side from mumps

See also: get_rhs!, get_sol!, get_sol

get_schur_complement!(S,mumps)

Retrieve Schur complement matrix from mumps into pre-allocated S

See also: get_schur_complement, mumps_schur_complement!, mumps_schur_complement

get_schur_complement(mumps) -> S

Retrieve Schur complement matrix S from mumps

See also: get_schur_complement!, mumps_schur_complement!, mumps_schur_complement

get_sol!(x,mumps)

Retrieve solution x from mumps into pre-allocated array.

See also: get_rhs!, get_rhs, get_sol

get_sol(mumps) -> x

Retrieve solution from mumps

See also: get_rhs!, get_rhs, get_sol!

get_solution(mumps) -> x

Retrieve the solution of the system solved by solve(). This function makes it possible to ask MUMPS to assemble the final solution on the host only, and to retrieve it there.

initialize!(mumps)

Reinitialize mumps, regardless of its current state

See also: finalize

invoke_mumps!(mumps)

Call the appropriate mumps C-library, passing to it the Mumps object mumps, but checking to make sure mumps has been initialized first, so that it's safe.

This is a low-level function, meaning that you have complete control over what operations are done, based on the MUMPS manual.

Be warned, a direct call can crash Julia if mumps is not appropriately initialized.

See also: invoke_mumps_unsafe!

invoke_mumps_unsafe!(mumps)

Call the appropriate mumps C-library, passing to it the Mumps object mumps.

This is a low-level function, meaning that you have complete control over what operations are done, based on the MUMPS manual.

Be warned, a direct call can crash Julia if mumps is not appropriately initialized.

See also: invoke_mumps!

mumps_det!(mumps; discard=true)

Compute determinant of A, which has been previously provided to mumps.

Determinant can be computed from mutated mumps by just det(mumps) [must have loaded LinearAlgebra].

Optional keyward discard controls whether LU factors are discarded via ICNTL[31]. This is useful if you only care about the determinant and don't want to do any further computation with mumps. Use discard=2 to throw away only L.

See also: mumps_det

mumps_det(A) -> det

Compute determinant of A.

See also: mumps_det!

mumps_factorize!(mumps)

LU factorize A previously provided to mump. LU stored in mumps, but not in a particularly accessible way. Useful for doing repeated solves downstream.

See also: mumps_factorize

mumps_factorize(A) -> mumps

LU factorize A. LU stored in mumps, but not in a particularly accessible way. Useful for doing repeated solves downstream.

See also: mumps_factorize!

mumps_schur_complement!(mumps, schur_inds)
mumps_schur_complement!(mumps, x)

schur_inds is integer array of Schur indices. If x is sparse, Schur indices determined from populated rows of x

See also: mumps_schur_complement, get_schur_complement!, get_schur_complement

mumps_schur_complement(A,schur_inds) -> S
mumps_schur_complement(A,x) -> S

schur_inds is integer array x is sparse, populated rows are Schur indices S is Schur complement matrix.

See also: mumps_schur_complement!

mumps_select_inv(A,x) -> A⁻¹
mumps_select_inv(A,I,J) -> A⁻¹

Compute selected elements of A⁻¹. If two arguments are passed, the second must be sparse, and its sparsity pattern determines the entries of the inverse. If three arguments are passed, the integer arrays I and J specify which entries via i(k),j(k) = I[k],J[k].

See also: mumps_select_inv!

mumps_select_inv!(x,mumps)
mumps_select_inv!(x,A)

Compute selected elements of A⁻¹ with same sparsity pattern as x, stored in x. If passed mumps, must have previously been provided with matrix A.

See also: mumps_select_inv, get_rhs!, get_rhs

mumps_solve(A,y) -> x
mumps_solve(mumps,y) -> x
mumps_solve(mumps) -> x

Solve A*x=y If mumps is given, must have previously been provided a matrix A. If only input is mumps must also have been provided y.

See also: mumps_solve!

mumps_solve!(x,A,y; kwargs...)
mumps_solve!(x,mumps)
mumps_solve!(x,mumps,y)

Solve A*x=y, saving result in pre-allocated x. If mumps is given, must have previously been provided a matrix A. If y is not given, mumps must have previously been provided y

See also: mumps_solve, get_sol!, get_sol

set_cntl!(mumps,i,val; [displaylevel=1])

Set the real/complex control parameters according to CNTL[i]=val

See also: display_cntl

set_icntl!(mumps,i,val; [displaylevel=1])

Set the integer control parameters according to ICNTL[i]=val

See also: display_icntl

set_job!(mumps,job::Integer)

Reverse compatible version of set_job! that accepts an integer job code.

set_job!(mumps,job)

Set the phase to job. See MUMPS manual for options.

set_save_dir!(mumps,dir)

set name of directory in which to store out-of-core files.

set_save_prefix!(mumps,dir)

prefix for out-of-core files.

set_schur_centralized_by_column!(mumps,schur_inds)

Set up Schur complement matrix calculation for the "centralized by column" method suggested in the MUMPS manual

See also: mumps_schur_complement!, mumps_schur_complement

set_user_perm!(mumps, perm; unsafe=false)

Provide a user-supplied permutation vector perm to the mumps object for reordering during analysis. This sets ICNTL[7] = 1 to indicate that a user-provided permutation should be used.

The permutation vector perm should be a 1-based integer vector of length n (the matrix dimension) containing a permutation of the integers 1 through n.

If needed, it tries to convert element type of perm to be consistent with MUMPS_INT type, throwing a warning in this case.

Note that by default this function makes a copy of perm. If you do not want to make a copy, pass unsafe=true. If the type of perm needs to be converted, this function may copy perm twice - to avoid this use unsafe=true.

When unsafe=true is passed, if the type of perm is already consistent with MUMPS_INT, then pointers to perm's memory are passed directly to MUMPS, so modifying perm will modify the permutation in mumps. If perm is not already consistent, a copy will be made when the type is converted.

See also: associate_matrix!, set_icntl!

solve!(mumps;transposed=false)

Solve the system registered with the Mumps object mumps. The matrix and right-hand side(s) must have been previously registered with associate_matrix() and associate_rhs(). The optional keyword argument transposed indicates whether the user wants to solve the forward or transposed system. The solution is stored internally and must be retrieved with get_solution().

solve(mumps, A, rhs; transposed=false)

Combined analyze / factorize / solve. Presume that A and rhs are available on all nodes. The optional keyword argument transposed indicates whether the user wants to solve the forward or transposed system. The solution is retrieved and returned.

solve(mumps, rhs; transposed=false)

Combined associate_rhs / solve. Presume that rhs is available on all nodes. The optional keyword argument transposed indicates whether the user wants to solve the forward or transposed system. The solution is retrieved and returned.

solve(A, rhs; sym=mumps_unsymmetric)

Combined initialize / analyze / factorize / solve. Presume that A and rhs are available on all nodes. The optional keyword argument sym indicates the symmetry of A. The solution is retrieved and returned.