229 lines
12 KiB
Groff
229 lines
12 KiB
Groff
|
|
.TH "serif::solver::preconditioner::backend::mfem" 3 "Version v0.0.1a" "SERiF" \" -*- nroff -*-
|
||
|
|
.ad l
|
||
|
|
.nh
|
||
|
|
.SH NAME
|
||
|
|
serif::solver::preconditioner::backend::mfem
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.br
|
||
|
|
.PP
|
||
|
|
.SS "Namespaces"
|
||
|
|
|
||
|
|
.in +1c
|
||
|
|
.ti -1c
|
||
|
|
.RI "namespace \fBdetail\fP"
|
||
|
|
.br
|
||
|
|
.in -1c
|
||
|
|
.SS "Classes"
|
||
|
|
|
||
|
|
.in +1c
|
||
|
|
.ti -1c
|
||
|
|
.RI "struct \fBInverse\fP"
|
||
|
|
.br
|
||
|
|
.RI "An owning approximate inverse and the application guarantee required by its compositions\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "class \fBSolver\fP"
|
||
|
|
.br
|
||
|
|
.RI "Expose one accepted inverse to MFEM while binding it to exactly its accepted physical Jacobian\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "class \fBSparseDirectCache\fP"
|
||
|
|
.br
|
||
|
|
.RI "The symbolic analysis (fill-reducing ordering) of the last matrix factored through this cache\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "struct \fBTwoBlockCouplings\fP"
|
||
|
|
.br
|
||
|
|
.RI "The two Jacobian actions between independently ordered equation and unknown groups\&. "
|
||
|
|
.in -1c
|
||
|
|
.SS "Typedefs"
|
||
|
|
|
||
|
|
.in +1c
|
||
|
|
.ti -1c
|
||
|
|
.RI "using \fBOperatorHandle\fP = std::shared_ptr<const ::mfem::Operator>"
|
||
|
|
.br
|
||
|
|
.in -1c
|
||
|
|
.SS "Enumerations"
|
||
|
|
|
||
|
|
.in +1c
|
||
|
|
.ti -1c
|
||
|
|
.RI "enum class \fBSERiFErrorCode\fP "
|
||
|
|
.br
|
||
|
|
.ti -1c
|
||
|
|
.RI "enum class \fBCouplingOrder\fP "
|
||
|
|
.br
|
||
|
|
.RI "Choose how the two groups of physical unknowns respond to each other's corrections\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "enum class \fBSERiFErrorCode\fP "
|
||
|
|
.br
|
||
|
|
.ti -1c
|
||
|
|
.RI "enum class \fBSERiFErrorCode\fP "
|
||
|
|
.br
|
||
|
|
.in -1c
|
||
|
|
.SS "Functions"
|
||
|
|
|
||
|
|
.in +1c
|
||
|
|
.ti -1c
|
||
|
|
.RI "std::expected< \fBInverse\fP, \fBFailure\fP > \fBtry_bordered_inverse\fP (\fBInverse\fP fields, \fBTwoBlockCouplings\fP couplings, \fBOperatorHandle\fP border_diagonal, const \fBstrategies::inverse::DenseDirect\fP &options={})"
|
||
|
|
.br
|
||
|
|
.RI "Probe and factor the complete small border Schur complement, retaining nonzero border-to-border couplings\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "std::expected< \fBOperatorHandle\fP, \fBFailure\fP > \fBtry_restrict_operator\fP (\fBOperatorHandle\fP operation, std::span< const int > rows, std::span< const int > columns)"
|
||
|
|
.br
|
||
|
|
.RI "Select equation rows and unknown columns without assuming their coordinate orders coincide\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "std::expected< \fBInverse\fP, \fBFailure\fP > \fBtry_coupled_inverse\fP (\fBInverse\fP first, \fBInverse\fP second, \fBTwoBlockCouplings\fP couplings, \fBstrategies::coupling::CouplingOrder\fP order)"
|
||
|
|
.br
|
||
|
|
.RI "Compose two inverses with the requested treatment of their cross couplings\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "std::expected< \fBOperatorHandle\fP, \fBFailure\fP > \fBtry_schur_operator\fP (\fBOperatorHandle\fP retained_diagonal, \fBInverse\fP eliminated, \fBTwoBlockCouplings\fP couplings)"
|
||
|
|
.br
|
||
|
|
.RI "Form the retained Jacobian minus its response through a fixed linear eliminated inverse\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "std::expected< \fBInverse\fP, \fBFailure\fP > \fBtry_amg_inverse\fP (std::shared_ptr< const ::mfem::SparseMatrix > matrix, const \fBstrategies::inverse::FixedAMG\fP &options={})"
|
||
|
|
.br
|
||
|
|
.RI "Prepare fixed-cycle BoomerAMG on this process; MPI must already be initialized and remains caller-owned\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "std::expected< \fBInverse\fP, \fBFailure\fP > \fBtry_dense_inverse\fP (const ::mfem::DenseMatrix &matrix, const \fBstrategies::inverse::DenseDirect\fP &options={})"
|
||
|
|
.br
|
||
|
|
.RI "Copy and scale a dense matrix, check its pivoted LU and infinity-norm reciprocal condition, then own the factorization\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "std::expected< \fBInverse\fP, \fBFailure\fP > \fBtry_diagonal_inverse\fP (std::span< const double > diagonal)"
|
||
|
|
.br
|
||
|
|
.RI "Own the reciprocal of every finite nonzero entry, including signed diagonals\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "std::string_view \fBsparse_direct_backend\fP () noexcept"
|
||
|
|
.br
|
||
|
|
.RI "The sparse LU backend compiled into this library (Meson option sparse_direct): "accelerate", "umfpack" or "none"\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "bool \fBsparse_direct_available\fP () noexcept"
|
||
|
|
.br
|
||
|
|
.RI "True when SparseDirect can be prepared on this machine; with "none", or Accelerate before macOS 15\&.5, it cannot\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "std::expected< \fBInverse\fP, \fBFailure\fP > \fBtry_sparse_direct_inverse\fP (std::shared_ptr< const ::mfem::SparseMatrix > matrix, const \fBstrategies::inverse::SparseDirect\fP &options={}, \fBSparseDirectCache\fP *cache=nullptr)"
|
||
|
|
.br
|
||
|
|
.RI "Factor a finalized square sparse matrix with a pivoted sparse LU; every application is one exact solve\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "std::expected< \fBInverse\fP, \fBFailure\fP > \fBtry_coupled_inverse\fP (\fBInverse\fP first, \fBInverse\fP second, \fBTwoBlockCouplings\fP couplings, \fBCouplingOrder\fP order)"
|
||
|
|
.br
|
||
|
|
.ti -1c
|
||
|
|
.RI "template<\fButils::errors::SERiFErrorCode\fP Code, typename\&.\&.\&. Arguments> std::unexpected< \fBFailure\fP > \fBfailure\fP (const std::string_view message, Arguments\&.\&.\&. arguments)"
|
||
|
|
.br
|
||
|
|
.RI "Keep preparation failures typed while using the common SERiF diagnostic formatter\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "template<\fButils::errors::SERiFErrorCode\fP Code, typename\&.\&.\&. Arguments> std::unexpected< \fBFailure\fP > \fBfailure\fP (const std::string_view message, Arguments\&.\&.\&. arguments)"
|
||
|
|
.br
|
||
|
|
.RI "Keep preparation failures typed while using the common SERiF diagnostic formatter\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "template<\fButils::errors::SERiFErrorCode\fP Code, typename\&.\&.\&. Arguments> std::unexpected< \fBFailure\fP > \fBfailure\fP (const std::string_view message, Arguments\&.\&.\&. arguments)"
|
||
|
|
.br
|
||
|
|
.RI "Keep preparation failures typed while using the common SERiF diagnostic formatter\&. "
|
||
|
|
.in -1c
|
||
|
|
.SH "Typedef Documentation"
|
||
|
|
.PP
|
||
|
|
.SS "using \fBserif::solver::preconditioner::backend::mfem::OperatorHandle\fP = std::shared_ptr<const ::mfem::Operator>"
|
||
|
|
|
||
|
|
.SH "Enumeration Type Documentation"
|
||
|
|
.PP
|
||
|
|
.SS "enum class \fBserif::solver::preconditioner::strategies::coupling::CouplingOrder\fP\fR [strong]\fP"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
Choose how the two groups of physical unknowns respond to each other's corrections\&.
|
||
|
|
.SS "enum class \fBserif::utils::errors::SERiFErrorCode\fP : uint16_t\fR [strong]\fP"
|
||
|
|
|
||
|
|
.SS "enum class \fBserif::utils::errors::SERiFErrorCode\fP : uint16_t\fR [strong]\fP"
|
||
|
|
|
||
|
|
.SS "enum class \fBserif::utils::errors::SERiFErrorCode\fP : uint16_t\fR [strong]\fP"
|
||
|
|
|
||
|
|
.SH "Function Documentation"
|
||
|
|
.PP
|
||
|
|
.SS "template<\fButils::errors::SERiFErrorCode\fP Code, typename\&.\&.\&. Arguments> std::unexpected< \fBFailure\fP > serif::solver::preconditioner::backend::mfem::detail::failure (const std::string_view message, Arguments\&.\&.\&. arguments)\fR [nodiscard]\fP"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
Keep preparation failures typed while using the common SERiF diagnostic formatter\&.
|
||
|
|
.SS "template<\fButils::errors::SERiFErrorCode\fP Code, typename\&.\&.\&. Arguments> std::unexpected< \fBFailure\fP > serif::solver::preconditioner::backend::mfem::detail::failure (const std::string_view message, Arguments\&.\&.\&. arguments)\fR [nodiscard]\fP"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
Keep preparation failures typed while using the common SERiF diagnostic formatter\&.
|
||
|
|
.SS "template<\fButils::errors::SERiFErrorCode\fP Code, typename\&.\&.\&. Arguments> std::unexpected< \fBFailure\fP > serif::solver::preconditioner::backend::mfem::detail::failure (const std::string_view message, Arguments\&.\&.\&. arguments)\fR [nodiscard]\fP"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
Keep preparation failures typed while using the common SERiF diagnostic formatter\&.
|
||
|
|
.SS "bool serif::solver::preconditioner::backend::mfem::sparse_direct_available ()\fR [nodiscard]\fP, \fR [noexcept]\fP"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
True when SparseDirect can be prepared on this machine; with "none", or Accelerate before macOS 15\&.5, it cannot\&.
|
||
|
|
.SS "std::string_view serif::solver::preconditioner::backend::mfem::sparse_direct_backend ()\fR [nodiscard]\fP, \fR [noexcept]\fP"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
The sparse LU backend compiled into this library (Meson option sparse_direct): "accelerate", "umfpack" or "none"\&.
|
||
|
|
.SS "std::expected< \fBInverse\fP, \fBFailure\fP > serif::solver::preconditioner::backend::mfem::try_amg_inverse (std::shared_ptr< const ::mfem::SparseMatrix > matrix, const \fBstrategies::inverse::FixedAMG\fP & options = \fR{}\fP)\fR [nodiscard]\fP"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
Prepare fixed-cycle BoomerAMG on this process; MPI must already be initialized and remains caller-owned\&.
|
||
|
|
.SS "std::expected< \fBInverse\fP, \fBFailure\fP > serif::solver::preconditioner::backend::mfem::try_bordered_inverse (\fBInverse\fP fields, \fBTwoBlockCouplings\fP couplings, \fBOperatorHandle\fP border_diagonal, const \fBstrategies::inverse::DenseDirect\fP & options = \fR{}\fP)\fR [nodiscard]\fP"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
Probe and factor the complete small border Schur complement, retaining nonzero border-to-border couplings\&.
|
||
|
|
.PP
|
||
|
|
\fBNote\fP
|
||
|
|
.RS 4
|
||
|
|
The first group contains fields; the second contains the border unknowns\&. Fixed linear field inverses cache their responses\&. Variable inverses solve the corrected field right-hand side afresh\&. Empty borders return the field inverse unchanged\&. Child actions must remain fixed throughout preparation\&.
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
|
||
|
|
.SS "std::expected< \fBInverse\fP, \fBFailure\fP > serif::solver::preconditioner::backend::mfem::try_coupled_inverse (\fBInverse\fP first, \fBInverse\fP second, \fBTwoBlockCouplings\fP couplings, \fBCouplingOrder\fP order)"
|
||
|
|
|
||
|
|
.SS "std::expected< \fBInverse\fP, \fBFailure\fP > serif::solver::preconditioner::backend::mfem::try_coupled_inverse (\fBInverse\fP first, \fBInverse\fP second, \fBTwoBlockCouplings\fP couplings, \fBstrategies::coupling::CouplingOrder\fP order)\fR [nodiscard]\fP"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
Compose two inverses with the requested treatment of their cross couplings\&.
|
||
|
|
.PP
|
||
|
|
\fBNote\fP
|
||
|
|
.RS 4
|
||
|
|
For lower_diagonal_upper the second inverse approximates the Schur complement\&. The returned action owns its prerequisites and reuses scratch; serialize applications to one instance\&. Inputs and outputs must be preallocated; overlapping buffers are supported\&.
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
|
||
|
|
.SS "std::expected< \fBInverse\fP, \fBFailure\fP > serif::solver::preconditioner::backend::mfem::try_dense_inverse (const ::mfem::DenseMatrix & matrix, const \fBstrategies::inverse::DenseDirect\fP & options = \fR{}\fP)\fR [nodiscard]\fP"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
Copy and scale a dense matrix, check its pivoted LU and infinity-norm reciprocal condition, then own the factorization\&.
|
||
|
|
.SS "std::expected< \fBInverse\fP, \fBFailure\fP > serif::solver::preconditioner::backend::mfem::try_diagonal_inverse (std::span< const double > diagonal)\fR [nodiscard]\fP"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
Own the reciprocal of every finite nonzero entry, including signed diagonals\&.
|
||
|
|
.SS "std::expected< \fBOperatorHandle\fP, \fBFailure\fP > serif::solver::preconditioner::backend::mfem::try_restrict_operator (\fBOperatorHandle\fP operation, std::span< const int > rows, std::span< const int > columns)\fR [nodiscard]\fP"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
Select equation rows and unknown columns without assuming their coordinate orders coincide\&.
|
||
|
|
.PP
|
||
|
|
\fBNote\fP
|
||
|
|
.RS 4
|
||
|
|
This owns the operator and copied indices; it borrows no caller index arrays or numerical vectors\&. Applications require preallocated vectors and support overlapping input and output\&.
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
|
||
|
|
.SS "std::expected< \fBOperatorHandle\fP, \fBFailure\fP > serif::solver::preconditioner::backend::mfem::try_schur_operator (\fBOperatorHandle\fP retained_diagonal, \fBInverse\fP eliminated, \fBTwoBlockCouplings\fP couplings)\fR [nodiscard]\fP"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
Form the retained Jacobian minus its response through a fixed linear eliminated inverse\&.
|
||
|
|
.PP
|
||
|
|
\fBNote\fP
|
||
|
|
.RS 4
|
||
|
|
The eliminated group is first and the retained group second: D - C K B\&. This prepares an owning action, without probing or assembling its entries\&.
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
|
||
|
|
.SS "std::expected< \fBInverse\fP, \fBFailure\fP > serif::solver::preconditioner::backend::mfem::try_sparse_direct_inverse (std::shared_ptr< const ::mfem::SparseMatrix > matrix, const \fBstrategies::inverse::SparseDirect\fP & options = \fR{}\fP, \fBSparseDirectCache\fP * cache = \fRnullptr\fP)\fR [nodiscard]\fP"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
Factor a finalized square sparse matrix with a pivoted sparse LU; every application is one exact solve\&.
|
||
|
|
.PP
|
||
|
|
\fBNote\fP
|
||
|
|
.RS 4
|
||
|
|
With a cache, the symbolic analysis is reused while the sparsity pattern is unchanged\&. ArrayMult solves a batch of right-hand sides together, which agrees with Mult to rounding (not bit for bit) on Accelerate\&.
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
|
||
|
|
.SH "Author"
|
||
|
|
.PP
|
||
|
|
Generated automatically by Doxygen for SERiF from the source code\&.
|