Files
MeanField_SERiF/docs/man/man3/serif_solver_preconditioner_backend_mfem.3

229 lines
12 KiB
Groff
Raw Normal View History

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