r
/
HYPRE.jl
mirror of https://github.com/fredrikekre/HYPRE.jl
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Add documentation for all the solvers.

pull/5/head v1.0.0
Fredrik Ekre 3 years ago
parent
5251b2fe68
commit
27fdb9b35b
5 changed files with 132 additions and 9 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 1
      docs/make.jl
  2. 26
      docs/src/api.md
  3. 41
      docs/src/solvers-preconditioners.md
  4. 2
      src/HYPRE.jl
  5. 71
      src/solvers.jl

1
docs/make.jl
Unescape View File

@ -19,6 +19,7 @@ makedocs(
"matrix-vector.md", "matrix-vector.md",
"solvers-preconditioners.md", "solvers-preconditioners.md",
"libhypre.md", "libhypre.md",
"api.md",
], ],
draft = liveserver, draft = liveserver,
) )

26
docs/src/api.md
Unescape View File

@ -0,0 +1,26 @@
# API
## Initialization and configuration
```@docs
HYPRE.Init
```
## Solvers and preconditioners
```@docs
HYPRE.solve!
HYPRE.solve
```
```@docs
HYPRE.HYPRESolver
HYPRE.BiCGSTAB
HYPRE.BoomerAMG
HYPRE.FlexGMRES
HYPRE.GMRES
HYPRE.Hybrid
HYPRE.ILU
HYPRE.PCG
HYPRE.ParaSails
```

41
docs/src/solvers-preconditioners.md
Unescape View File

@ -3,24 +3,45 @@
HYPRE.jl wraps most of HYPREs [ParCSR solvers and HYPRE.jl wraps most of HYPREs [ParCSR solvers and
preconditioners](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html). preconditioners](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html).
The synopsis for HYPRE.jl's wrappers is the same for all solvers: The synopsis for creating and using HYPRE.jl's solver wrappers is the same for all solvers:
1. Set up the linear system (see [Matrix/vector representation](@ref))
2. (Optional) Configure a preconditioner
3. Configure a solver
4. Use [`HYPRE.solve`](@ref) or [`HYPRE.solve!`](@ref) to solve the system
Here is the corresponding pseudo-code:
```julia ```julia
# Setup up linear system (see previous section) # 1. Setup up linear system
A = HYPREMatrix(...) A = HYPREMatrix(...)
b = HYPREVector(...) b = HYPREVector(...)
# Create a solver # 2. Configure a preconditioner
solver = HYPRESolver(; settings...) precond = HYPRESolver(; settings...)
# Solve A x = b # 3. Configure a solver
solver = HYPRESolver(; Precond = precond, settings...)
# 4. Solve the system
x = HYPRE.solve(solver, A, b) x = HYPRE.solve(solver, A, b)
``` ```
The following solvers/preconditioners are currently available:
- [`HYPRE.BiCGSTAB`](@ref)
- [`HYPRE.BoomerAMG`](@ref)
- [`HYPRE.FlexGMRES`](@ref)
- [`HYPRE.GMRES`](@ref)
- [`HYPRE.Hybrid`](@ref)
- [`HYPRE.ILU`](@ref)
- [`HYPRE.ParaSails`](@ref)
- [`HYPRE.PCG`](@ref)
### Solver configuration
Settings are passed as keyword arguments, with the names matching directly to 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 `HYPRE_SolverSet*` calls from the HYPRE C API (see example below). Most settings are passed
passed directly to HYPRE, for example `Tol = 1e-9` would be passed directly to directly to HYPRE, for example `Tol = 1e-9` would be passed directly to `HYPRE_SolverSetTol`
`HYPRE_SolverSetTol` for the correponding solver. for the correponding solver.
Setting a preconditioner can be done by passing a `HYPRESolver` directly with the `Precond` 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 keyword argument, without any need to also pass the corresponding `HYPRE_SolverSetup` and
@ -30,6 +51,7 @@ 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.jl adds finalizers to the solvers, which takes care of calling the their respective
`HYPRE_SolverDestroy` function when the solver is garbage collected. `HYPRE_SolverDestroy` function when the solver is garbage collected.
#### Example: Conjugate gradient with algebraic multigrid preconditioner #### Example: Conjugate gradient with algebraic multigrid preconditioner
Here is an example of creating a `PCG` (conjugate gradient) solver with `BoomerAMG` Here is an example of creating a `PCG` (conjugate gradient) solver with `BoomerAMG`
@ -55,7 +77,8 @@ preconditioner. These settings are added automatically since it is passed as a
preconditioner to the `PCG` solver. preconditioner to the `PCG` solver.
!!! not "Corresponding C code" !!! not "Corresponding C code"
For comparison, here is the corresponding C code for setting up the solver above: For comparison between the APIs, here is the corresponding C code for setting up the
solver above:
```c ```c
/* Setup linear system */ /* Setup linear system */
HYPRE_IJMatrix A; HYPRE_IJMatrix A;

2
src/HYPRE.jl
Unescape View File

@ -26,6 +26,8 @@ include("Internals.jl")
Wrapper around `HYPRE_Init`. If `finalize_atexit` is `true` a Julia exit hook is added, Wrapper around `HYPRE_Init`. If `finalize_atexit` is `true` a Julia exit hook is added,
which calls `HYPRE_Finalize`. This method will also call `MPI.Init` unless MPI is already which calls `HYPRE_Finalize`. This method will also call `MPI.Init` unless MPI is already
initialized. initialized.
**Note**: This function *must* be called before using HYPRE functions.
""" """
function Init(; finalize_atexit=true) function Init(; finalize_atexit=true)
if !(MPI.Initialized()) if !(MPI.Initialized())

71
src/solvers.jl
Unescape View File

@ -91,6 +91,14 @@ end
# (ParCSR)BiCGSTAB # # (ParCSR)BiCGSTAB #
#################### ####################
"""
BiCGSTAB(; settings...)
Create a `BiCGSTAB` solver. See HYPRE API reference for details and supported settings.
**External links**
- [BiCGSTAB API reference](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html#breathe-section-title-parcsr-bicgstab-solver)
"""
mutable struct BiCGSTAB <: HYPRESolver mutable struct BiCGSTAB <: HYPRESolver
comm::MPI.Comm comm::MPI.Comm
solver::HYPRE_Solver solver::HYPRE_Solver
@ -131,6 +139,16 @@ end
# BoomerAMG # # BoomerAMG #
############# #############
"""
BoomerAMG(; settings...)
Create a `BoomerAMG` solver/preconditioner. See HYPRE API reference for details and
supported settings.
**External links**
- [BoomerAMG documentation](https://hypre.readthedocs.io/en/latest/solvers-boomeramg.html)
- [BoomerAMG API reference](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html#breathe-section-title-parcsr-boomeramg-solver-and-preconditioner)
"""
mutable struct BoomerAMG <: HYPRESolver mutable struct BoomerAMG <: HYPRESolver
solver::HYPRE_Solver solver::HYPRE_Solver
function BoomerAMG(; kwargs...) function BoomerAMG(; kwargs...)
@ -166,6 +184,14 @@ end
# FlexGMRES # # FlexGMRES #
############# #############
"""
FlexGMRES(; settings...)
Create a `FlexGMRES` solver. See HYPRE API reference for details and supported settings.
**External links**
- [FlexGMRES API reference](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html#breathe-section-title-parcsr-flexgmres-solver)
"""
mutable struct FlexGMRES <: HYPRESolver mutable struct FlexGMRES <: HYPRESolver
comm::MPI.Comm comm::MPI.Comm
solver::HYPRE_Solver solver::HYPRE_Solver
@ -241,6 +267,14 @@ end
# GMRES # # GMRES #
######### #########
"""
GMRES(; settings...)
Create a `GMRES` solver. See HYPRE API reference for details and supported settings.
**External links**
- [GMRES API reference](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html#breathe-section-title-parcsr-gmres-solver)
"""
mutable struct GMRES <: HYPRESolver mutable struct GMRES <: HYPRESolver
comm::MPI.Comm comm::MPI.Comm
solver::HYPRE_Solver solver::HYPRE_Solver
@ -279,6 +313,15 @@ end
# Hybrid # # Hybrid #
########## ##########
"""
Hybrid(; settings...)
Create a `Hybrid` solver. See HYPRE API reference for details and supported settings.
**External links**
- [Hybrid documentation](https://hypre.readthedocs.io/en/latest/solvers-hybrid.html)
- [Hybrid API reference](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html#breathe-section-title-parcsr-hybrid-solver)
"""
mutable struct Hybrid <: HYPRESolver mutable struct Hybrid <: HYPRESolver
solver::HYPRE_Solver solver::HYPRE_Solver
function Hybrid(; kwargs...) function Hybrid(; kwargs...)
@ -318,6 +361,16 @@ end
# ILU # # ILU #
####### #######
"""
ILU(; settings...)
Create a `ILU` solver/preconditioner. See HYPRE API reference for details and supported
settings.
**External links**
- [ILU documentation](https://hypre.readthedocs.io/en/latest/solvers-hypre-ilu.html)
- [ILU API reference](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html#breathe-section-title-parcsr-ilu-solver)
"""
mutable struct ILU <: HYPRESolver mutable struct ILU <: HYPRESolver
solver::HYPRE_Solver solver::HYPRE_Solver
function ILU(; kwargs...) function ILU(; kwargs...)
@ -353,6 +406,16 @@ end
# (ParCSR)ParaSails # # (ParCSR)ParaSails #
##################### #####################
"""
ParaSails(comm=MPI.COMM_WORLD; settings...)
Create a `ParaSails` preconditioner. See HYPRE API reference for details and supported
settings.
**External links**
- [ParaSails documentation](https://hypre.readthedocs.io/en/latest/solvers-parasails.html)
- [ParaSails API reference](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html#breathe-section-title-parcsr-parasails-preconditioner)
"""
mutable struct ParaSails <: HYPRESolver mutable struct ParaSails <: HYPRESolver
comm::MPI.Comm comm::MPI.Comm
solver::HYPRE_Solver solver::HYPRE_Solver
@ -380,6 +443,14 @@ Internals.solve_func(::ParaSails) = HYPRE_ParCSRParaSailsSolve
# (ParCSR)PCG # # (ParCSR)PCG #
############### ###############
"""
PCG(; settings...)
Create a `PCG` solver. See HYPRE API reference for details and supported settings.
**External links**
- [PCG API reference](https://hypre.readthedocs.io/en/latest/api-sol-parcsr.html#breathe-section-title-parcsr-pcg-solver)
"""
mutable struct PCG <: HYPRESolver mutable struct PCG <: HYPRESolver
comm::MPI.Comm comm::MPI.Comm
solver::HYPRE_Solver solver::HYPRE_Solver

Write Preview
Loading…
Cancel
Save