From 0e80427e3f8b1955be1b50b34ff1f8dbadf90a09 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Thu, 28 Jul 2022 15:33:42 +0000 Subject: [PATCH] build based on 5251b2f --- dev/index.html | 2 +- dev/libhypre/index.html | 2 +- dev/matrix-vector/index.html | 4 +-- dev/search/index.html | 2 +- dev/search_index.js | 2 +- dev/solvers-preconditioners/index.html | 44 ++++++++++++++++++++++++++ 6 files changed, 50 insertions(+), 6 deletions(-) create mode 100644 dev/solvers-preconditioners/index.html diff --git a/dev/index.html b/dev/index.html index 7e104f0..3376fd4 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · HYPRE.jl
GitHub

HYPRE.jl

HYPRE.jl is a Julia wrapper for the HYPRE library, which provide parallel solvers for sparse linear systems.

High level interface

HYPRE.jl provide a high level interface to the HYPRE library. The goal of this interface is that the style and API should feel natural to most Julia programmers (it is "Julian"). In particular, you can use standard sparse matrices together with HYPRE's solvers through this interface.

The high level interface does not (currently) provide access to all of HYPREs functionality, but it can easily be combined with the low level interface when necessary.

Low level interface

HYPRE.jl also provide a low level interface for interacting with HYPRE. The goal of this interface is to stay close to the HYPRE C API. In fact, this interface is automatically generated based on HYPRE's header files, so this API maps one-to-one with the C API, see LibHYPRE C API for more details.

+Home · HYPRE.jl
GitHub

HYPRE.jl

HYPRE.jl is a Julia wrapper for the HYPRE library, which provide parallel solvers for sparse linear systems.

High level interface

HYPRE.jl provide a high level interface to the HYPRE library. The goal of this interface is that the style and API should feel natural to most Julia programmers (it is "Julian"). In particular, you can use standard sparse matrices together with HYPRE's solvers through this interface.

The high level interface does not (currently) provide access to all of HYPREs functionality, but it can easily be combined with the low level interface when necessary.

Low level interface

HYPRE.jl also provide a low level interface for interacting with HYPRE. The goal of this interface is to stay close to the HYPRE C API. In fact, this interface is automatically generated based on HYPRE's header files, so this API maps one-to-one with the C API, see LibHYPRE C API for more details.

diff --git a/dev/libhypre/index.html b/dev/libhypre/index.html index 63b80ee..6ce0e4a 100644 --- a/dev/libhypre/index.html +++ b/dev/libhypre/index.html @@ -1,2 +1,2 @@ -LibHYPRE C API · HYPRE.jl
GitHub

LibHYPRE C API

The submodule HYPRE.LibHYPRE contains auto-generated bindings to the HYPRE library and give access to the HYPRE C API directly[1]. The module exports all HYPRE_* symbols. Function names and arguments are identical to the C-library – refer to the HYPRE manual for details.

The example program examples/ex5.jl is an (almost) line-to-line translation of the corresponding example program examples/ex5.c written in C, and showcases how HYPRE.jl can be used to interact with the HYPRE library directly.

Functions from the LibHYPRE submodule can be used together with the high level interface. This is useful when you need some functionality from the library which isn't exposed in the high level interface. Many functions require passing a reference to a matrix/vector or a solver. These can be obtained as follows:

C type signatureArgument to pass
HYPRE_IJMatrixA.ijmatrix where A::HYPREMatrix
HYPRE_ParCSRMatrixA.parmatrix where A::HYPREMatrix
HYPRE_IJVectorb.ijvector where b::HYPREVector
HYPRE_ParVectorb.parvector where b::HYPREVector
HYPRE_Solvers.solver where s::HYPRESolver
+LibHYPRE C API · HYPRE.jl
GitHub

LibHYPRE C API

The submodule HYPRE.LibHYPRE contains auto-generated bindings to the HYPRE library and give access to the HYPRE C API directly[1]. The module exports all HYPRE_* symbols. Function names and arguments are identical to the C-library – refer to the HYPRE manual for details.

The example program examples/ex5.jl is an (almost) line-to-line translation of the corresponding example program examples/ex5.c written in C, and showcases how HYPRE.jl can be used to interact with the HYPRE library directly.

Functions from the LibHYPRE submodule can be used together with the high level interface. This is useful when you need some functionality from the library which isn't exposed in the high level interface. Many functions require passing a reference to a matrix/vector or a solver. These can be obtained as follows:

C type signatureArgument to pass
HYPRE_IJMatrixA.ijmatrix where A::HYPREMatrix
HYPRE_ParCSRMatrixA.parmatrix where A::HYPREMatrix
HYPRE_IJVectorb.ijvector where b::HYPREVector
HYPRE_ParVectorb.parvector where b::HYPREVector
HYPRE_Solvers.solver where s::HYPRESolver
diff --git a/dev/matrix-vector/index.html b/dev/matrix-vector/index.html index 13919c8..ac19a0f 100644 --- a/dev/matrix-vector/index.html +++ b/dev/matrix-vector/index.html @@ -1,5 +1,5 @@ -Matrix/vector representation · HYPRE.jl
GitHub

Matrix/vector representation

HYPRE.jl defines the structs HYPREMatrix and HYPREVector representing HYPREs datastructures. Specifically it uses the IJ System Interface which can be used for general sparse matrices.

HYPRE.jl defines conversion methods from standard Julia datastructures to HYPREMatrix and HYPREVector, respectively. See the following sections for details:

    PartitionedArrays.jl (multi-process)

    HYPRE.jl integrates seemlessly with PSparseMatrix and PVector from the PartitionedArrays.jl package. These can be passed directly to solve and solve!. Internally this will construct a HYPREMatrix and HYPREVectors and then convert the solution back to a PVector.

    The HYPREMatrix constructor support both SparseMatrixCSC and SparseMatrixCSR as storage backends for the PSparseMatrix. However, since HYPREs internal storage is also CSR based it can be slightly more resource efficient to use SparseMatrixCSR.

    The constructors also support both PartitionedArrays.jl backends: When using the MPI backend the communicator of the PSparseMatrix/PVector is used also for the HYPREMatrix/HYPREVector, and when using the Sequential backend it is assumed to be a single-process setup, and the MPI.COMM_SELF communicator is used.

    Example pseudocode

    # Assemble linear system (see documentation for PartitionedArrays)
+Matrix/vector representation · HYPRE.jl
    GitHub
    Matrix/vector representation
    HYPRE.jl defines the structs HYPREMatrix and HYPREVector representing HYPREs datastructures. Specifically it uses the IJ System Interface which can be used for general sparse matrices.
    HYPRE.jl defines conversion methods from standard Julia datastructures to HYPREMatrix and HYPREVector, respectively. See the following sections for details:
      PartitionedArrays.jl (multi-process)
      HYPRE.jl integrates seemlessly with PSparseMatrix and PVector from the PartitionedArrays.jl package. These can be passed directly to solve and solve!. Internally this will construct a HYPREMatrix and HYPREVectors and then convert the solution back to a PVector.
      The HYPREMatrix constructor support both SparseMatrixCSC and SparseMatrixCSR as storage backends for the PSparseMatrix. However, since HYPREs internal storage is also CSR based it can be slightly more resource efficient to use SparseMatrixCSR.
      The constructors also support both PartitionedArrays.jl backends: When using the MPI backend the communicator of the PSparseMatrix/PVector is used also for the HYPREMatrix/HYPREVector, and when using the Sequential backend it is assumed to be a single-process setup, and the MPI.COMM_SELF communicator is used.
      Example pseudocode
      # Assemble linear system (see documentation for PartitionedArrays)
 A = PSparseMatrix(...)
 b = PVector(...)
 
@@ -30,4 +30,4 @@ x = solve(solver, A, b)
 
 # Inplace solve with x as initial guess
 x = zeros(length(b))
-solve!(solver, x, A, b)
      SparseMatrixCSC / SparseMatrixCSR (multi-process)
      Warning
      This interface isn't finalized yet and is therefore not documented since it is subject to change.
      
+solve!(solver, x, A, b)

      SparseMatrixCSC / SparseMatrixCSR (multi-process)

      Warning

      This interface isn't finalized yet and is therefore not documented since it is subject to change.

      diff --git a/dev/search/index.html b/dev/search/index.html index 4961ce5..b9947ef 100644 --- a/dev/search/index.html +++ b/dev/search/index.html @@ -1,2 +1,2 @@ -Search · HYPRE.jl
      GitHub

      Loading search...

        +Search · HYPRE.jl
        GitHub

        Loading search...

          diff --git a/dev/search_index.js b/dev/search_index.js index 478eee7..c470ca9 100644 --- a/dev/search_index.js +++ b/dev/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"matrix-vector/#Matrix/vector-representation","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"","category":"section"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"HYPRE.jl defines the structs HYPREMatrix and HYPREVector representing HYPREs datastructures. Specifically it uses the IJ System Interface which can be used for general sparse matrices.","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"HYPRE.jl defines conversion methods from standard Julia datastructures to HYPREMatrix and HYPREVector, respectively. See the following sections for details:","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"Pages = [\"hypre-matrix-vector.md\"]\nDepth = 2:2","category":"page"},{"location":"matrix-vector/#PartitionedArrays.jl-(multi-process)","page":"Matrix/vector representation","title":"PartitionedArrays.jl (multi-process)","text":"","category":"section"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"HYPRE.jl integrates seemlessly with PSparseMatrix and PVector from the PartitionedArrays.jl package. These can be passed directly to solve and solve!. Internally this will construct a HYPREMatrix and HYPREVectors and then convert the solution back to a PVector.","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"The HYPREMatrix constructor support both SparseMatrixCSC and SparseMatrixCSR as storage backends for the PSparseMatrix. However, since HYPREs internal storage is also CSR based it can be slightly more resource efficient to use SparseMatrixCSR.","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"The constructors also support both PartitionedArrays.jl backends: When using the MPI backend the communicator of the PSparseMatrix/PVector is used also for the HYPREMatrix/HYPREVector, and when using the Sequential backend it is assumed to be a single-process setup, and the MPI.COMM_SELF communicator is used.","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"Example pseudocode","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"# Assemble linear system (see documentation for PartitionedArrays)\nA = PSparseMatrix(...)\nb = PVector(...)\n\n# Solve with zero initial guess\nx = solve(solver, A, b)\n\n# Inplace solve with x as initial guess\nx = PVector(...)\nsolve!(solver, x, A, b)","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"It is also possible to construct the arrays explicitly. This can save some resources when performing multiple consecutive solves (multiple time steps, Newton iterations, etc). To copy data back and forth between PSparseMatrix/PVector and HYPREMatrix/HYPREVector use the copy! function.","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"Example pseudocode","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"A = PSparseMatrix(...)\nx = PVector(...)\nb = PVector(...)\n\n# Construct the HYPRE arrays\nA_h = HYPREMatrix(A)\nx_h = HYPREVector(x)\nb_h = HYPREVector(b)\n\n# Solve\nsolve!(solver, x_h, A_h, b_h)\n\n# Copy solution back to x\ncopy!(x, x_h)","category":"page"},{"location":"matrix-vector/#SparseMatrixCSC-/-SparseMatrixCSR-(single-process)","page":"Matrix/vector representation","title":"SparseMatrixCSC / SparseMatrixCSR (single-process)","text":"","category":"section"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"HYPRE.jl also support working directly with SparseMatrixCSC (from the SparseArrays.jl standard library) and SparseMatrixCSR (from the SparseMatricesCSR.jl package). This makes it possible to use solvers and preconditioners even for single-process problems. When using these type of spars matrices it is assumed that the right hand side and solution vectors are regular Julia Vectors.","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"Just like when using the PartitionedArrays.jl package, it is possible to pass sparse matrices directly to solve and solve!, but it is also possible to create HYPREMatrix and HYPREVector explicitly, possibly saving some resources when doing multiple consecutive linear solves (see previous section).","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"Example pseudocode","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"A = SparseMatrixCSC(...)\nx = Vector(...)\nb = Vector(...)\n\n# Solve with zero initial guess\nx = solve(solver, A, b)\n\n# Inplace solve with x as initial guess\nx = zeros(length(b))\nsolve!(solver, x, A, b)","category":"page"},{"location":"matrix-vector/#SparseMatrixCSC-/-SparseMatrixCSR-(multi-process)","page":"Matrix/vector representation","title":"SparseMatrixCSC / SparseMatrixCSR (multi-process)","text":"","category":"section"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"warning: Warning\nThis interface isn't finalized yet and is therefore not documented since it is subject to change.","category":"page"},{"location":"#HYPRE.jl","page":"Home","title":"HYPRE.jl","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"HYPRE.jl is a Julia wrapper for the HYPRE library, which provide parallel solvers for sparse linear systems.","category":"page"},{"location":"","page":"Home","title":"Home","text":"","category":"page"},{"location":"#High-level-interface","page":"Home","title":"High level interface","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"HYPRE.jl provide a high level interface to the HYPRE library. The goal of this interface is that the style and API should feel natural to most Julia programmers (it is \"Julian\"). In particular, you can use standard sparse matrices together with HYPRE's solvers through this interface.","category":"page"},{"location":"","page":"Home","title":"Home","text":"The high level interface does not (currently) provide access to all of HYPREs functionality, but it can easily be combined with the low level interface when necessary.","category":"page"},{"location":"","page":"Home","title":"Home","text":"","category":"page"},{"location":"#Low-level-interface","page":"Home","title":"Low level interface","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"HYPRE.jl also provide a low level interface for interacting with HYPRE. The goal of this interface is to stay close to the HYPRE C API. In fact, this interface is automatically generated based on HYPRE's header files, so this API maps one-to-one with the C API, see LibHYPRE C API for more details.","category":"page"},{"location":"libhypre/#LibHYPRE-C-API","page":"LibHYPRE C API","title":"LibHYPRE C API","text":"","category":"section"},{"location":"libhypre/","page":"LibHYPRE C API","title":"LibHYPRE C API","text":"The submodule HYPRE.LibHYPRE contains auto-generated bindings to the HYPRE library and give access to the HYPRE C API directly[1]. The module exports all HYPRE_* symbols. Function names and arguments are identical to the C-library – refer to the HYPRE manual for details.","category":"page"},{"location":"libhypre/","page":"LibHYPRE C API","title":"LibHYPRE C API","text":"The example program examples/ex5.jl is an (almost) line-to-line translation of the corresponding example program examples/ex5.c written in C, and showcases how HYPRE.jl can be used to interact with the HYPRE library directly.","category":"page"},{"location":"libhypre/","page":"LibHYPRE C API","title":"LibHYPRE C API","text":"Functions from the LibHYPRE submodule can be used together with the high level interface. This is useful when you need some functionality from the library which isn't exposed in the high level interface. Many functions require passing a reference to a matrix/vector or a solver. These can be obtained as follows:","category":"page"},{"location":"libhypre/","page":"LibHYPRE C API","title":"LibHYPRE C API","text":"C type signature Argument to pass\nHYPRE_IJMatrix A.ijmatrix where A::HYPREMatrix\nHYPRE_ParCSRMatrix A.parmatrix where A::HYPREMatrix\nHYPRE_IJVector b.ijvector where b::HYPREVector\nHYPRE_ParVector b.parvector where b::HYPREVector\nHYPRE_Solver s.solver where s::HYPRESolver","category":"page"},{"location":"libhypre/","page":"LibHYPRE C API","title":"LibHYPRE C API","text":"[1]: Bindings are generated using Clang.jl, see gen/generator.jl.","category":"page"}] +[{"location":"matrix-vector/#Matrix/vector-representation","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"","category":"section"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"HYPRE.jl defines the structs HYPREMatrix and HYPREVector representing HYPREs datastructures. Specifically it uses the IJ System Interface which can be used for general sparse matrices.","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"HYPRE.jl defines conversion methods from standard Julia datastructures to HYPREMatrix and HYPREVector, respectively. See the following sections for details:","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"Pages = [\"hypre-matrix-vector.md\"]\nDepth = 2:2","category":"page"},{"location":"matrix-vector/#PartitionedArrays.jl-(multi-process)","page":"Matrix/vector representation","title":"PartitionedArrays.jl (multi-process)","text":"","category":"section"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"HYPRE.jl integrates seemlessly with PSparseMatrix and PVector from the PartitionedArrays.jl package. These can be passed directly to solve and solve!. Internally this will construct a HYPREMatrix and HYPREVectors and then convert the solution back to a PVector.","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"The HYPREMatrix constructor support both SparseMatrixCSC and SparseMatrixCSR as storage backends for the PSparseMatrix. However, since HYPREs internal storage is also CSR based it can be slightly more resource efficient to use SparseMatrixCSR.","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"The constructors also support both PartitionedArrays.jl backends: When using the MPI backend the communicator of the PSparseMatrix/PVector is used also for the HYPREMatrix/HYPREVector, and when using the Sequential backend it is assumed to be a single-process setup, and the MPI.COMM_SELF communicator is used.","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"Example pseudocode","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"# Assemble linear system (see documentation for PartitionedArrays)\nA = PSparseMatrix(...)\nb = PVector(...)\n\n# Solve with zero initial guess\nx = solve(solver, A, b)\n\n# Inplace solve with x as initial guess\nx = PVector(...)\nsolve!(solver, x, A, b)","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"It is also possible to construct the arrays explicitly. This can save some resources when performing multiple consecutive solves (multiple time steps, Newton iterations, etc). To copy data back and forth between PSparseMatrix/PVector and HYPREMatrix/HYPREVector use the copy! function.","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"Example pseudocode","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"A = PSparseMatrix(...)\nx = PVector(...)\nb = PVector(...)\n\n# Construct the HYPRE arrays\nA_h = HYPREMatrix(A)\nx_h = HYPREVector(x)\nb_h = HYPREVector(b)\n\n# Solve\nsolve!(solver, x_h, A_h, b_h)\n\n# Copy solution back to x\ncopy!(x, x_h)","category":"page"},{"location":"matrix-vector/#SparseMatrixCSC-/-SparseMatrixCSR-(single-process)","page":"Matrix/vector representation","title":"SparseMatrixCSC / SparseMatrixCSR (single-process)","text":"","category":"section"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"HYPRE.jl also support working directly with SparseMatrixCSC (from the SparseArrays.jl standard library) and SparseMatrixCSR (from the SparseMatricesCSR.jl package). This makes it possible to use solvers and preconditioners even for single-process problems. When using these type of spars matrices it is assumed that the right hand side and solution vectors are regular Julia Vectors.","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"Just like when using the PartitionedArrays.jl package, it is possible to pass sparse matrices directly to solve and solve!, but it is also possible to create HYPREMatrix and HYPREVector explicitly, possibly saving some resources when doing multiple consecutive linear solves (see previous section).","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"Example pseudocode","category":"page"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"A = SparseMatrixCSC(...)\nx = Vector(...)\nb = Vector(...)\n\n# Solve with zero initial guess\nx = solve(solver, A, b)\n\n# Inplace solve with x as initial guess\nx = zeros(length(b))\nsolve!(solver, x, A, b)","category":"page"},{"location":"matrix-vector/#SparseMatrixCSC-/-SparseMatrixCSR-(multi-process)","page":"Matrix/vector representation","title":"SparseMatrixCSC / SparseMatrixCSR (multi-process)","text":"","category":"section"},{"location":"matrix-vector/","page":"Matrix/vector representation","title":"Matrix/vector representation","text":"warning: Warning\nThis interface isn't finalized yet and is therefore not documented since it is subject to change.","category":"page"},{"location":"solvers-preconditioners/#Solvers-and-preconditioners","page":"Solvers and preconditioners","title":"Solvers and preconditioners","text":"","category":"section"},{"location":"solvers-preconditioners/","page":"Solvers and preconditioners","title":"Solvers and preconditioners","text":"HYPRE.jl wraps most of HYPREs ParCSR solvers and preconditioners.","category":"page"},{"location":"solvers-preconditioners/","page":"Solvers and preconditioners","title":"Solvers and preconditioners","text":"The synopsis for HYPRE.jl's wrappers is the same for all solvers:","category":"page"},{"location":"solvers-preconditioners/","page":"Solvers and preconditioners","title":"Solvers and preconditioners","text":"# Setup up linear system (see previous section)\nA = HYPREMatrix(...)\nb = HYPREVector(...)\n\n# Create a solver\nsolver = HYPRESolver(; settings...)\n\n# Solve A x = b\nx = HYPRE.solve(solver, A, b)","category":"page"},{"location":"solvers-preconditioners/","page":"Solvers and preconditioners","title":"Solvers and preconditioners","text":"Settings are passed as keyword arguments, with the names matching directly to HYPRE_SolverSetXXX calls from the HYPRE C API (see example below). Most settings are passed directly to HYPRE, for example Tol = 1e-9 would be passed directly to HYPRE_SolverSetTol for the correponding solver.","category":"page"},{"location":"solvers-preconditioners/","page":"Solvers and preconditioners","title":"Solvers and preconditioners","text":"Setting a preconditioner can be done by passing a HYPRESolver directly with the Precond keyword argument, without any need to also pass the corresponding HYPRE_SolverSetup and HYPRE_SolverSolve as must be done in the C API. In addition, solvers that have required settings when used as a preconditioner will have those applied automatically.","category":"page"},{"location":"solvers-preconditioners/","page":"Solvers and preconditioners","title":"Solvers and preconditioners","text":"HYPRE.jl adds finalizers to the solvers, which takes care of calling the their respective HYPRE_SolverDestroy function when the solver is garbage collected.","category":"page"},{"location":"solvers-preconditioners/#Example:-Conjugate-gradient-with-algebraic-multigrid-preconditioner","page":"Solvers and preconditioners","title":"Example: Conjugate gradient with algebraic multigrid preconditioner","text":"","category":"section"},{"location":"solvers-preconditioners/","page":"Solvers and preconditioners","title":"Solvers and preconditioners","text":"Here is an example of creating a PCG (conjugate gradient) solver with BoomerAMG (algebraic multigrid) as preconditioner:","category":"page"},{"location":"solvers-preconditioners/","page":"Solvers and preconditioners","title":"Solvers and preconditioners","text":"# Setup up linear system\nA = HYPREMatrix(...)\nb = HYPREVector(...)\n\n# Preconditioner\nprecond = HYPRE.BoomerAMG(; RelaxType = 6, CoarsenType = 6)\n\n# Solver\nsolver = HYPRE.PCG(; MaxIter = 1000, Tol = 1e-9, Precond = precond)\n\n# Solve\nx = HYPRE.solve(solver, A, b)","category":"page"},{"location":"solvers-preconditioners/","page":"Solvers and preconditioners","title":"Solvers and preconditioners","text":"Note that Tol = 0.0 and MaxIter = 1 are required settings when using BoomerAMG as a preconditioner. These settings are added automatically since it is passed as a preconditioner to the PCG solver.","category":"page"},{"location":"solvers-preconditioners/","page":"Solvers and preconditioners","title":"Solvers and preconditioners","text":"not: Corresponding C code\nFor comparison, here is the corresponding C code for setting up the solver above:/* Setup linear system */\nHYPRE_IJMatrix A;\nHYPRE_IJVector b, x;\n\n/* Preconditioner */\nHYPRE_Solver precond;\nHYPRE_BoomerAMGCreate(&precond);\nHYPRE_BoomerAMGSetCoarsenType(precond, 6);\nHYPRE_BoomerAMGSetRelaxType(precond, 6);\nHYPRE_BoomerAMGSetTol(precond, 0.0);\nHYPRE_BoomerAMGSetMaxIter(precond, 1);\n\n/* Solver */\nHYPRE_Solver solver;\nHYPRE_ParCSRPCGCreate(MPI_COMM_WORLD, &solver);\nHYPRE_PCGSetMaxIter(solver, 1000);\n\n/* Add preconditioner */\nHYPRE_PCGSetPrecond(solver, (HYPRE_PtrToSolverFcn) HYPRE_BoomerAMGSolve,\n (HYPRE_PtrToSolverFcn) HYPRE_BoomerAMGSetup, precond);\n\n/* Solve */\nHYPRE_ParCSRPCGSetup(solver, A, b, x);\nHYPRE_ParCSRPCGSolve(solver, A, b, x);","category":"page"},{"location":"#HYPRE.jl","page":"Home","title":"HYPRE.jl","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"HYPRE.jl is a Julia wrapper for the HYPRE library, which provide parallel solvers for sparse linear systems.","category":"page"},{"location":"","page":"Home","title":"Home","text":"","category":"page"},{"location":"#High-level-interface","page":"Home","title":"High level interface","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"HYPRE.jl provide a high level interface to the HYPRE library. The goal of this interface is that the style and API should feel natural to most Julia programmers (it is \"Julian\"). In particular, you can use standard sparse matrices together with HYPRE's solvers through this interface.","category":"page"},{"location":"","page":"Home","title":"Home","text":"The high level interface does not (currently) provide access to all of HYPREs functionality, but it can easily be combined with the low level interface when necessary.","category":"page"},{"location":"","page":"Home","title":"Home","text":"","category":"page"},{"location":"#Low-level-interface","page":"Home","title":"Low level interface","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"HYPRE.jl also provide a low level interface for interacting with HYPRE. The goal of this interface is to stay close to the HYPRE C API. In fact, this interface is automatically generated based on HYPRE's header files, so this API maps one-to-one with the C API, see LibHYPRE C API for more details.","category":"page"},{"location":"libhypre/#LibHYPRE-C-API","page":"LibHYPRE C API","title":"LibHYPRE C API","text":"","category":"section"},{"location":"libhypre/","page":"LibHYPRE C API","title":"LibHYPRE C API","text":"The submodule HYPRE.LibHYPRE contains auto-generated bindings to the HYPRE library and give access to the HYPRE C API directly[1]. The module exports all HYPRE_* symbols. Function names and arguments are identical to the C-library – refer to the HYPRE manual for details.","category":"page"},{"location":"libhypre/","page":"LibHYPRE C API","title":"LibHYPRE C API","text":"The example program examples/ex5.jl is an (almost) line-to-line translation of the corresponding example program examples/ex5.c written in C, and showcases how HYPRE.jl can be used to interact with the HYPRE library directly.","category":"page"},{"location":"libhypre/","page":"LibHYPRE C API","title":"LibHYPRE C API","text":"Functions from the LibHYPRE submodule can be used together with the high level interface. This is useful when you need some functionality from the library which isn't exposed in the high level interface. Many functions require passing a reference to a matrix/vector or a solver. These can be obtained as follows:","category":"page"},{"location":"libhypre/","page":"LibHYPRE C API","title":"LibHYPRE C API","text":"C type signature Argument to pass\nHYPRE_IJMatrix A.ijmatrix where A::HYPREMatrix\nHYPRE_ParCSRMatrix A.parmatrix where A::HYPREMatrix\nHYPRE_IJVector b.ijvector where b::HYPREVector\nHYPRE_ParVector b.parvector where b::HYPREVector\nHYPRE_Solver s.solver where s::HYPRESolver","category":"page"},{"location":"libhypre/","page":"LibHYPRE C API","title":"LibHYPRE C API","text":"[1]: Bindings are generated using Clang.jl, see gen/generator.jl.","category":"page"}] } diff --git a/dev/solvers-preconditioners/index.html b/dev/solvers-preconditioners/index.html new file mode 100644 index 0000000..73f26f0 --- /dev/null +++ b/dev/solvers-preconditioners/index.html @@ -0,0 +1,44 @@ + +Solvers and preconditioners · HYPRE.jl
          GitHub

          Solvers and preconditioners

          HYPRE.jl wraps most of HYPREs ParCSR solvers and preconditioners.

          The synopsis for HYPRE.jl's wrappers is the same for all solvers:

          # Setup up linear system (see previous section)
+A = HYPREMatrix(...)
+b = HYPREVector(...)
+
+# Create a solver
+solver = HYPRESolver(; settings...)
+
+# Solve A x = b
+x = HYPRE.solve(solver, A, b)

          Settings are passed as keyword arguments, with the names matching directly to HYPRE_SolverSetXXX calls from the HYPRE C API (see example below). Most settings are passed directly to HYPRE, for example Tol = 1e-9 would be passed directly to HYPRE_SolverSetTol for the correponding solver.

          Setting a preconditioner can be done by passing a HYPRESolver directly with the Precond keyword argument, without any need to also pass the corresponding HYPRE_SolverSetup and HYPRE_SolverSolve as must be done in the C API. In addition, solvers that have required settings when used as a preconditioner will have those applied automatically.

          HYPRE.jl adds finalizers to the solvers, which takes care of calling the their respective HYPRE_SolverDestroy function when the solver is garbage collected.

          Example: Conjugate gradient with algebraic multigrid preconditioner

          Here is an example of creating a PCG (conjugate gradient) solver with BoomerAMG (algebraic multigrid) as preconditioner:

          # Setup up linear system
+A = HYPREMatrix(...)
+b = HYPREVector(...)
+
+# Preconditioner
+precond = HYPRE.BoomerAMG(; RelaxType = 6, CoarsenType = 6)
+
+# Solver
+solver = HYPRE.PCG(; MaxIter = 1000, Tol = 1e-9, Precond = precond)
+
+# Solve
+x = HYPRE.solve(solver, A, b)

          Note that Tol = 0.0 and MaxIter = 1 are required settings when using BoomerAMG as a preconditioner. These settings are added automatically since it is passed as a preconditioner to the PCG solver.

          Corresponding C code

          For comparison, here is the corresponding C code for setting up the solver above:

          /* Setup linear system */
+HYPRE_IJMatrix A;
+HYPRE_IJVector b, x;
+
+/* Preconditioner */
+HYPRE_Solver precond;
+HYPRE_BoomerAMGCreate(&precond);
+HYPRE_BoomerAMGSetCoarsenType(precond, 6);
+HYPRE_BoomerAMGSetRelaxType(precond, 6);
+HYPRE_BoomerAMGSetTol(precond, 0.0);
+HYPRE_BoomerAMGSetMaxIter(precond, 1);
+
+/* Solver */
+HYPRE_Solver solver;
+HYPRE_ParCSRPCGCreate(MPI_COMM_WORLD, &solver);
+HYPRE_PCGSetMaxIter(solver, 1000);
+
+/* Add preconditioner */
+HYPRE_PCGSetPrecond(solver, (HYPRE_PtrToSolverFcn) HYPRE_BoomerAMGSolve,
+                            (HYPRE_PtrToSolverFcn) HYPRE_BoomerAMGSetup, precond);
+
+/* Solve */
+HYPRE_ParCSRPCGSetup(solver, A, b, x);
+HYPRE_ParCSRPCGSolve(solver, A, b, x);