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

210 lines
9.0 KiB
Groff
Raw Normal View History

.TH "serif::solver::preconditioner" 3 "Version v0.0.1a" "SERiF" \" -*- nroff -*-
.ad l
.nh
.SH NAME
serif::solver::preconditioner
.SH SYNOPSIS
.br
.PP
.SS "Namespaces"
.in +1c
.ti -1c
.RI "namespace \fBbackend\fP"
.br
.ti -1c
.RI "namespace \fBchecks\fP"
.br
.ti -1c
.RI "namespace \fBcomputations\fP"
.br
.ti -1c
.RI "namespace \fBdetail\fP"
.br
.ti -1c
.RI "namespace \fBkeys\fP"
.br
.ti -1c
.RI "namespace \fBstrategies\fP"
.br
.in -1c
.SS "Classes"
.in +1c
.ti -1c
.RI "struct \fBBlockPreconditioner\fP"
.br
.RI "Select a physical equation/unknown pair and the numerical approximation to its inverse\&. "
.ti -1c
.RI "struct \fBBorderedPreconditioner\fP"
.br
.RI "Correct a physical field inverse through its dense constraint Schur system\&. "
.ti -1c
.RI "struct \fBConstraintCoordinates\fP"
.br
.RI "Select arbitrary constraint rows and unknowns, including coupled generated scalars\&. "
.ti -1c
.RI "struct \fBCoupledPreconditioner\fP"
.br
.RI "Compose physical subsystem descriptions without creating an additional preparation owner\&. "
.ti -1c
.RI "struct \fBFailure\fP"
.br
.RI "A recoverable preparation failure, including the numerical reason and how to correct it\&. "
.ti -1c
.RI "class \fBSolver\fP"
.br
.RI "Expose one accepted inverse to MFEM while binding it to exactly its accepted physical Jacobian\&. "
.in -1c
.SS "Concepts"
.in +1c
.ti -1c
.RI "concept \fBPrimalPreconditionerLayout\fP"
.br
.RI "Require density and potential fields with paired optional shape and scalar constraints\&. "
.ti -1c
.RI "concept \fBDisjointSubsystems\fP"
.br
.RI "Require disjoint ownership on both sides rather than silently deduplicating physical coordinates\&. "
.in -1c
.SS "Enumerations"
.in +1c
.ti -1c
.RI "enum class \fBApplicationContract\fP { \fBfixed_linear\fP, \fBvariable\fP }"
.br
.RI "Whether repeated applications represent one fixed linear map or a variable inner solve\&. "
.in -1c
.SS "Functions"
.in +1c
.ti -1c
.RI "template<typename Row, typename Field> auto \fBphysical_block\fP (\fBoperators::backend::mfem::LinearizedBlock\fP block)"
.br
.RI "Name a single accepted physical coupling as an ordinary dependency source\&. "
.ti -1c
.RI "template<typename Recipe> auto \fBmake_preconditioner_computations\fP (const Recipe &choice)"
.br
.RI "Declare a recipe's numerical stages for composition into one model dependency graph\&. "
.ti -1c
.RI "template<typename Recipe> auto \fBmake_preconditioner_graph\fP (const Recipe &choice)"
.br
.RI "Construct the complete preconditioner graph in one place, without preparing any numerical data\&. "
.ti -1c
.RI "template<typename Recipe, discretization::blocks::SystemLayoutType Layout, utils::dependencies::IsComputation\&.\&.\&. Additional> auto \fBmake_preconditioner_computations\fP (const Recipe &choice, const Layout &, Additional\&.\&.\&. additional)"
.br
.RI "Expand a recipe and its coordinate ordering for composition into an existing physical graph\&. "
.ti -1c
.RI "template<typename Recipe, discretization::blocks::SystemLayoutType Layout, utils::dependencies::IsComputation\&.\&.\&. Additional> auto \fBmake_preconditioner_graph\fP (const Recipe &choice, const Layout &layout, Additional\&.\&.\&. additional)"
.br
.RI "Order the inverse in system coordinates, optionally including explicit upstream computations such as reference surface assembly\&. "
.ti -1c
.RI "template<PrimalPreconditionerLayout Layout, typename PotentialInverse = strategies::inverse::FixedAMG> auto \fBmake_primal_preconditioner\fP (const Layout &, PotentialInverse potential_inverse=\fBstrategies::inverse::FixedAMG\fP{\&.cycles=3})"
.br
.RI "Couple scalar density and potential responses, then correct every shape and global constraint together\&. "
.ti -1c
.RI "template<typename Field, typename Row = Field, typename Strategy> auto \fBmake_preconditioner\fP (Strategy inverse)"
.br
.RI "Describe an inverse without preparing matrices or binding runtime state\&. "
.ti -1c
.RI "template<typename Constraints, typename Fields>
.br
requires DisjointSubsystems<Fields, Constraints>auto \fBwith_constraints\fP (Fields fields, \fBstrategies::inverse::DenseDirect\fP inverse={})"
.br
.RI "Attach constraints without a registry of built-in mass, rotation, or central-density providers\&. "
.ti -1c
.RI "template<typename First, typename Second, typename Policy>
.br
requires DisjointSubsystems<First, Second>auto \fBcouple\fP (First first, Second second, Policy coupling)"
.br
.RI "Choose the physical subsystem ordering explicitly; the same algebra serves material/surface and material/gravity\&. "
.in -1c
.SH "Enumeration Type Documentation"
.PP
.SS "enum class \fBserif::solver::preconditioner::ApplicationContract\fP\fR [strong]\fP"
.PP
Whether repeated applications represent one fixed linear map or a variable inner solve\&.
.PP
\fBEnumerator\fP
.in +1c
.TP
\f(BIfixed_linear \fP
.TP
\f(BIvariable \fP
.SH "Function Documentation"
.PP
.SS "template<typename First, typename Second, typename Policy>
.br
requires DisjointSubsystems<First, Second>auto serif::solver::preconditioner::couple (First first, Second second, Policy coupling)\fR [nodiscard]\fP"
.PP
Choose the physical subsystem ordering explicitly; the same algebra serves material/surface and material/gravity\&.
.SS "template<typename Field, typename Row = Field, typename Strategy> auto serif::solver::preconditioner::make_preconditioner (Strategy inverse)\fR [nodiscard]\fP"
.PP
Describe an inverse without preparing matrices or binding runtime state\&.
.SS "template<typename Recipe> auto serif::solver::preconditioner::make_preconditioner_computations (const Recipe & choice)\fR [nodiscard]\fP"
.PP
Declare a recipe's numerical stages for composition into one model dependency graph\&.
.SS "template<typename Recipe, discretization::blocks::SystemLayoutType Layout, utils::dependencies::IsComputation\&.\&.\&. Additional> auto serif::solver::preconditioner::make_preconditioner_computations (const Recipe & choice, const Layout & , Additional\&.\&.\&. additional)\fR [nodiscard]\fP"
.PP
Expand a recipe and its coordinate ordering for composition into an existing physical graph\&.
.SS "template<typename Recipe> auto serif::solver::preconditioner::make_preconditioner_graph (const Recipe & choice)\fR [nodiscard]\fP"
.PP
Construct the complete preconditioner graph in one place, without preparing any numerical data\&.
.PP
\fBNote\fP
.RS 4
Recipes choose physical branches; computation declarations name all edges\&. The dependency engine orders execution\&.
.RE
.PP
.SS "template<typename Recipe, discretization::blocks::SystemLayoutType Layout, utils::dependencies::IsComputation\&.\&.\&. Additional> auto serif::solver::preconditioner::make_preconditioner_graph (const Recipe & choice, const Layout & layout, Additional\&.\&.\&. additional)\fR [nodiscard]\fP"
.PP
Order the inverse in system coordinates, optionally including explicit upstream computations such as reference surface assembly\&.
.PP
\fBNote\fP
.RS 4
Supply \fBkeys::Layout\fP in the preparation context\&. Additional computations must have unique result keys\&.
.RE
.PP
.SS "template<PrimalPreconditionerLayout Layout, typename PotentialInverse = strategies::inverse::FixedAMG> auto serif::solver::preconditioner::make_primal_preconditioner (const Layout & , PotentialInverse potential_inverse = \fR\fBstrategies::inverse::FixedAMG\fP{\&.cycles = 3}\fP)\fR [nodiscard]\fP"
.PP
Couple scalar density and potential responses, then correct every shape and global constraint together\&. Potential responds first and its force contribution then adjusts density\&. The existing dense border retains surface-to-field and field-to-surface responses, including the mean radius mode; shape has no separate mass inverse\&. Density uses its diagonal without regularization because its pressure-force Jacobian includes drift and need not satisfy the positive-diagonal contract of the elliptic AMG strategy used for potential\&.
.PP
\fBNote\fP
.RS 4
The dense border stores one field response per shape/global coordinate and a square border matrix\&. This default targets bounded surface catalogs; large nodal surfaces require an explicitly chosen scalable recipe\&.
.PP
This is an approximate inverse, not a guarantee that the physical constraint Schur system is nonsingular\&.
.RE
.PP
\fBParameters\fP
.RS 4
\fIpotential_inverse\fP Inverse of the potential block: three fixed AMG cycles by default, or for example \fBstrategies::inverse::SparseDirect\fP for an exact factorization of moderate-size blocks\&.
.RE
.PP
.SS "template<typename Row, typename Field> auto serif::solver::preconditioner::physical_block (\fBoperators::backend::mfem::LinearizedBlock\fP block)\fR [nodiscard]\fP"
.PP
Name a single accepted physical coupling as an ordinary dependency source\&.
.SS "template<typename Constraints, typename Fields>
.br
requires DisjointSubsystems<Fields, Constraints>auto serif::solver::preconditioner::with_constraints (Fields fields, \fBstrategies::inverse::DenseDirect\fP inverse = \fR{}\fP)\fR [nodiscard]\fP"
.PP
Attach constraints without a registry of built-in mass, rotation, or central-density providers\&.
.SH "Author"
.PP
Generated automatically by Doxygen for SERiF from the source code\&.