Note for now much of the docs is LLM written. This was done to save time and focus on code development. The docs have been LOOSLEY reviewed. However, the code itself has been either fully written by hand or fully reviewed. Therefore, the docs should at the moment be seen as a loose resource rather than authoratiative (and this is on top of the general ability for docs to drift)
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\&.
|