.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" .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" .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\&.