From 4ca86204571b5def519be1702ea9a9d11fce1871 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Thu, 12 Dec 2024 23:11:03 +0000 Subject: [PATCH] build based on 20d9066 --- dev/.documenter-siteinfo.json | 2 +- dev/api/index.html | 14 +++++++------- dev/index.html | 2 +- dev/reference/index.html | 2 +- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 2db7d8b..148b3ac 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.2","generation_timestamp":"2024-12-12T20:39:13","documenter_version":"1.8.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.2","generation_timestamp":"2024-12-12T23:10:57","documenter_version":"1.8.0"}} \ No newline at end of file diff --git a/dev/api/index.html b/dev/api/index.html index 911ed13..e1bdfd7 100644 --- a/dev/api/index.html +++ b/dev/api/index.html @@ -1,10 +1,10 @@ -API · MUMPS.jl
GitHub

API

MUMPS.MUMPS — Module
module MUMPS

Both low-level interface with MUMPS 5.6.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.

source
MUMPS.mumps_definite — Constant
const mumps_definite

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

source
MUMPS.mumps_symmetric — Constant
const mumps_symmetric

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

source
MUMPS.mumps_unsymmetric — Constant
const mumps_unsymmetric

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

source
MUMPS.associate_matrix! — Method
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.

source
MUMPS.associate_matrix! — Method
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!

source
MUMPS.associate_rhs! — Method
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!

source
MUMPS.factorize! — Method
factorize!(mumps,A)

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

source
MUMPS.factorize! — Method
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.

source
MUMPS.get_icntl — Method
get_icntl(;det=false,verbose=false,ooc=false,itref=0)

Obtain an array of integer control parameters.

source
MUMPS.get_solution — Function
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.

source
MUMPS.invoke_mumps! — Method
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!

source
MUMPS.invoke_mumps_unsafe! — Function
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!

source
MUMPS.mumps_det! — Method
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

source
MUMPS.mumps_factorize! — Method
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

source
MUMPS.mumps_select_inv — Function
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!

source
MUMPS.mumps_solve — Function
mumps_solve(A,y) -> x
+API · MUMPS.jl
GitHub
API
MUMPS.MUMPS — Module
module MUMPS
Both low-level interface with MUMPS 5.6.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.
source
MUMPS.mumps_definite — Constant
const mumps_definite
Constant indicating that a symmetric definite matrix will be analyzed and factorized
source
MUMPS.mumps_symmetric — Constant
const mumps_symmetric
Constant indicating that a general symmetric matrix will be analyzed and factorized
source
MUMPS.mumps_unsymmetric — Constant
const mumps_unsymmetric
Constant indicating that a general unsymmetric matrix will be analyzed and factorized
source
MUMPS.associate_matrix! — Method
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.
source
MUMPS.associate_matrix! — Method
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!
source
MUMPS.associate_rhs! — Method
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!
source
MUMPS.factorize! — Method
factorize!(mumps,A)
Combined associate_matrix / factorize. Presume that A is available on all nodes.
source
MUMPS.factorize! — Method
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.
source
MUMPS.get_icntl — Method
get_icntl(;det=false,verbose=false,ooc=false,itref=0)
Obtain an array of integer control parameters.
source
MUMPS.get_solution — Function
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.
source
MUMPS.invoke_mumps! — Method
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!
source
MUMPS.invoke_mumps_unsafe! — Function
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!
source
MUMPS.mumps_det! — Method
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
source
MUMPS.mumps_factorize! — Method
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
source
MUMPS.mumps_select_inv — Function
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!
source
MUMPS.mumps_solve — Function
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!
source
MUMPS.mumps_solve! — Function
mumps_solve!(x,A,y; kwargs...)
+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!
source
MUMPS.mumps_solve! — Function
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
source
MUMPS.set_job! — Method
set_job!(mumps,job)
Set the phase to job. See MUMPS manual for options.
source
MUMPS.solve! — Method
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().
source
MUMPS.solve — Method
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.
source
MUMPS.solve — Method
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.
source
MUMPS.solve — Method
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.
source

+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

source
MUMPS.set_job! — Method
set_job!(mumps,job)

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

source
MUMPS.solve! — Method
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().

source
MUMPS.solve — Method
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.

source
MUMPS.solve — Method
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.

source
MUMPS.solve — Method
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.

source
diff --git a/dev/index.html b/dev/index.html index c10184f..cb4929c 100644 --- a/dev/index.html +++ b/dev/index.html @@ -23,4 +23,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 for more examples.

Constants and Methods Exposed

Constants

The following convenience constants may be used when initializing a Mumps object:

ConstantMeaning
mumps_unsymmetricmatrix is general unsymmetric (or symmetry is unknown)
mumps_definitematrix is symmetric and (positive or negative) definite
mumps_symmetricmatrix is symmetric but indefinite (or definiteness is unknown)
default_icntlarray of default integer parameters
default_cntl32array of default real parameters in single precision
default_cntl64array of default real parameters in double precision

See Section 5 of the MUMPS User's Manual 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 convenience function get_icntl() returns an array of integer parameters corresponding to certain commonly-used options. Its arguments are all optional:

A Mumps object is destroyed by calling the finalize() method. Because finalize still issues MPI commands, it is important to call finalize() before calling MPI.Finalize().

MethodDescription
finalizeFinalize a Mumps object. Must be done before calling MPI.Finalize()
associate_matrix!Register a matrix with the Mumps object. This function makes it possible to define the data on the host only.
factorize!Factorize the matrix registered with the Mumps object.
associate_rhs!Register right-hand sides with the Mumps object. This function makes it possible to define the data on the host only.
solve!Solve the linear system for the given right-hand side.
get_solutionRetrieve the solution from the Mumps object. This function makes it possible for the solution to be assembled on the host only.

Parallel Execution

MPI is controled by way of MPI.jl. Look for the lines that say NUMBER OF WORKING PROCESSES in the output of

mpirun -np 4 julia examples/mumps_mpi.jl

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 the same version of MUMPS as used by the MUMPS_jll artifact is needed.

For example, macOS users may install precompiled MUMPS binaries from the Homebrew tap dpo/mumps-jl as follows:

brew tap dpo/mumps-jl
 brew install mpich-mumps
-export JULIA_MUMPS_LIBRARY_PATH=$(brew --prefix)/opt/mpich-mumps/lib

Apple Silicon users should remember to use arch x86_64 brew to refer to Intel binaries run through Rosetta, as we do not (yet) ship Silicon binaries of MUMPS via Homebrew.

The JULIA_MUMPS_LIBRARY_PATH environment variable may be set permanently in the shell's startup file, or in $HOME/.julia/config/startup.jl.

+export JULIA_MUMPS_LIBRARY_PATH=$(brew --prefix)/opt/mpich-mumps/lib

Apple Silicon users should remember to use arch x86_64 brew to refer to Intel binaries run through Rosetta, as we do not (yet) ship Silicon binaries of MUMPS via Homebrew.

The JULIA_MUMPS_LIBRARY_PATH environment variable may be set permanently in the shell's startup file, or in $HOME/.julia/config/startup.jl.

diff --git a/dev/reference/index.html b/dev/reference/index.html index 00028fd..6d70d19 100644 --- a/dev/reference/index.html +++ b/dev/reference/index.html @@ -1,2 +1,2 @@ -Reference · MUMPS.jl
GitHub

Reference

Index

+Reference · MUMPS.jl
GitHub

Reference

Index