|
Teko Version of the Day
|
The Inverse Library (Teko::InverseLibrary) is the naming and dispatch engine that lets one line of configuration — "Inverse Type" = "MyThing" — resolve to a direct solve, a Krylov solver, an algebraic multigrid preconditioner, or another Teko block preconditioner. Understanding it is what makes the rest of Teko's options composable.
Every sublist inside "Inverse Factory Library" is one entry. Its name is a label you choose, and it must contain a "Type" key that names a backend (InverseLibrary::addInverse, src/Teko_InverseLibrary.cpp). Everything else in the entry is forwarded to that backend.
You then reference the label wherever an inverse is expected: at the top level ("Inverse Type" = "MyILU") or inside a block preconditioner ("Inverse Type 1" = "MyILU").
"Type" is matched, in this order, against the Stratimikos preconditioner list, the Stratimikos solver list, and then Teko's block-preconditioner list. When a live Stratimikos::DefaultLinearSolverBuilder is supplied, the first two lists come from the solver and preconditioner types enabled in that Trilinos build.
| Class | Typical names | What Teko builds | Extra settings are… |
|---|---|---|---|
| Stratimikos preconditioner | commonly Ifpack2, MueLu, Neumann Series | a PreconditionerInverseFactory wrapping a Thyra::PreconditionerFactoryBase | that backend's own preconditioner parameters |
| Stratimikos solver | commonly Belos, Amesos2 | a SolveInverseFactory (a full linear solve used as the inverse) | that solver's parameters (plus "Use Preconditioner", below) |
| Teko block preconditioner | Block Jacobi, Block Gauss-Seidel, NS SIMPLE, NS LSC, Block LU2x2, … | the corresponding block factory | that factory's options (reference) |
The Stratimikos columns above are examples, not a hard-coded promise: when an InverseLibrary is constructed from a live Stratimikos builder, Teko asks that builder for the solver and preconditioner names enabled in the current Trilinos configuration.
If a "Type" matches none of the three, or a referenced label does not exist, getInverseFactory prints the list of available names and aborts — a useful way to discover what is registered.
There are two ways to obtain a library:
Teko::InverseLibrary::buildFromStratimikos()** — auto-registers every Stratimikos solver and preconditioner under its own name. After this you can immediately ask for getInverseFactory("Amesos2"), getInverseFactory("Ifpack2"), etc. with no library entries at all. This is what the strided-operator examples use.Teko::InverseLibrary::buildFromParameterList(pl, builder)** — builds the named entries from pl (the "Inverse Factory Library" sublist). Because you pass the Stratimikos builder, the built-in Stratimikos names remain available in addition to your entries, so entries can reference "Ifpack2" / "Amesos2" directly without defining them.When Teko runs inside Stratimikos (the XML path), StratimikosFactory calls buildFromParameterList on the "Inverse Factory Library" sublist for you — you never construct the library by hand.
Any parameter whose value is a label is resolved by calling getInverseFactory(label) on the same library. These parameters include, among others:
"Inverse Type", "Inverse Type <N>", "Inverse Velocity Type", "Inverse Pressure Type", "Inverse F Type", "Inverse Laplace Type", "Preconditioner Type", "Preconditioner Type <N>", "Inverse Factory", "Preconditioner A", "Preconditioner B", "Use Preconditioner".
This is why a block preconditioner can point each of its sub-block solves at a different entry — and those entries can themselves be block preconditioners, to any depth.
Inside a Stratimikos solver entry (e.g. Type = "Belos"), the key "Use Preconditioner" names another library entry to attach as that solver's preconditioner. This is how you build a "preconditioned Krylov inverse" for a block:
Inside a Stratimikos preconditioner entry, a "Required Parameters" sublist is stripped out before the backend sees it and re-supplied at build time through the RequestHandler. Use it to hand a backend operators/data that only the application can provide (e.g. coordinates or a nullspace for MueLu).
Because any inverse-valued parameter can name another library entry, you can make each sub-block of a block preconditioner be solved by a full Krylov solver that is itself preconditioned — i.e. a genuine nested solve. The example below configures a Block Gauss-Seidel whose two diagonal blocks are each solved by GMRES (Belos), and that inner GMRES is preconditioned by Ifpack2 RILUK:
The resolution chain is GS → (per block) PrecGMRES → (its preconditioner) ILU. To use a different inner solver per block, point "Inverse Type 1" and "Inverse Type 2" at distinct entries. The same pattern nests arbitrarily: a PrecGMRES entry could name another block preconditioner as its "Use Preconditioner", and so on.
The XML/ParameterList path is preferred, but the same entries can be built directly. Two convenience helpers exist:
Once you have an InverseFactory, Teko::buildInverse(*inv, A) produces the inverse operator (and Teko::rebuildInverse(*inv, A, invOp) refreshes an existing one in place — see Advanced Topics for reuse).
1.9.8