Block-Structured AMR Software Framework
Loading...
Searching...
No Matches
amrex::HypreMLNodeLap Class Reference

Composite multi-level solve of an MLNodeLaplacian with hypre. More...

#include <AMReX_HypreMLNodeLap.H>

Public Types

using BigInt = HYPRE_BigInt

Public Member Functions

 HypreMLNodeLap (MLNodeLaplacian const &a_linop, std::string a_prefix="hypre_mlnodelap", int a_verbose=0)
 Assemble the composite matrix from a prepared linear operator.
 ~HypreMLNodeLap ()
 HypreMLNodeLap (HypreMLNodeLap const &)=delete
 HypreMLNodeLap (HypreMLNodeLap &&)=delete
HypreMLNodeLap & operator= (HypreMLNodeLap const &)=delete
HypreMLNodeLap & operator= (HypreMLNodeLap &&)=delete
void solve (Vector< MultiFab * > const &a_sol, Vector< MultiFab const * > const &a_rhs, Real a_reltol, Real a_abstol, int a_maxiter)
 Solve the composite system.
void setThrowException (bool t) noexcept
int getNumIters () const
 Iterations and final relative residual of the last solve.
Real getFinalResidualNorm () const
BigInt numUnknowns () const
 Number of composite unknowns.
void updateMatrix ()
 Assemble the matrix again from the operator's current coefficients, for the following solves: the MLNodeLaplacian of the constructor with new values of sigma (the same grids, boundary conditions, masks and EB, so that the matrix pattern is unchanged). With setReuseSolverSetup(true) the values are updated in place and the hypre solver setup, or the AlgMG hierarchy, is kept (see HypreMLABecLap::setReuseSolverSetup); otherwise the setup is redone at the next solve. Collective over the operator's communicator.
void setReuseSolverSetup (bool v)
 Keep the solver setup across updateMatrix() calls, as HypreMLABecLap::setReuseSolverSetup: the kept setup only approximates the updated operator, and a solve with it that does not converge redoes the setup and continues once before failing. Can be set at any time: turned on after a solve, the next updateMatrix() keeps that solve's setup (with the hypre backend it assembles the matrix once more, scaled to the kept setup's; later updates are in place). With reuse on, the setup is redone only after resetSolverSetup() and by the reuse controls below (<prefix>.recompute_preconditioner is off); with reuse off, after every updateMatrix() (and on every solve if that option is on).
Real getMatrixScale () const noexcept
void setReuseSetupMaxIter (int n) noexcept
void setReuseSetupMaxChange (Real f)
void resetSolverSetup ()
 Redo the solver setup (hypre) or the AlgMG hierarchy at the next solve.
void buildMatrix ()
void populateMatrix (Gpu::DeviceVector< BigInt > &rows, Gpu::DeviceVector< BigInt > &cols, Gpu::DeviceVector< Real > &vals)

Detailed Description

Composite multi-level solve of an MLNodeLaplacian with hypre.

The composite operator of MLMG + MLNodeLaplacian is (up to a lumped-mass row scaling and extra fine-equation terms in the coarse/fine rows) the bilinear/trilinear finite-element operator with hanging-node constraints. This class assembles the symmetric form S = Q^T K Q, where K sums the Q1 element matrices of all cells not covered by a finer level and Q maps coarse/fine fine-level nodes to the coarse unknowns by multilinear interpolation. The right-hand side is transformed so that the solution equals MLMG's composite solution (up to a constant for singular problems, which are made consistent with nodal-volume weights; with an inconsistent composite right-hand side this differs slightly from MLMG's correction).

Supports the Sigma coarsening strategy with scalar, constant or mapped (per-direction) sigma, Cartesian coordinates, and refinement ratios 2 and 4; and, in EB builds, the RAP strategy with embedded boundaries, where the element matrices of cut cells are integrated over their fluid part (MLNodeLaplacian's EB integrals), covered cells are skipped, and nodes without fluid are not unknowns. At coarse/fine nodes next to cut cells this composite operator is the consistent finite-element one, whereas MLMG's reflux treats the cells there as regular.

The solver is configured with the HypreIJIface keys under the given ParmParse prefix (default "hypre_mlnodelap"). Further keys:

  • <prefix>.backend = hypre | algmg (default hypre): solve the assembled system with hypre or with AMReX's AlgMG, configured by <prefix>.algmg.* (see composite::algmg_parse_options).
  • <prefix>.dump_matrix = N (default 0): write the systems of the first N solves with this dump prefix (counted over all objects of the run) in Matrix Market format for external analysis: for solve k, <dump_prefix>_<k>_A.mtx, _b.mtx, _x.mtx (matrix, right-hand side, solution) and _rows.txt (per row: level, node index, scaling). The dumped system is the one solved, S' x' = b' with S' = s S s, b' = s b, x = s x'. <prefix>.dump_prefix defaults to the ParmParse prefix. Files with more than <prefix>.dump_gather_max values (matrix entries, or vector and row-map values; default 5e7) are written one per rank, as <file>.<rank>.
  • <prefix>.eb_scaling (default 1): in EB builds, scale the unknowns by 1/sqrt(nodal fluid fraction) so that rows next to small cut cells count in the residual norm.
  • <prefix>.reuse_setup_max_iter, <prefix>.reuse_setup_max_change: the setup reuse controls (setReuseSetupMaxIter, setReuseSetupMaxChange).
  • <prefix>.recompute_preconditioner (default 0): redo the solver setup on every solve (hypre backend; off with setup reuse).

Member Typedef Documentation

◆ BigInt

using amrex::HypreMLNodeLap::BigInt = HYPRE_BigInt

Constructor & Destructor Documentation

◆ HypreMLNodeLap() [1/3]

amrex::HypreMLNodeLap::HypreMLNodeLap ( MLNodeLaplacian const & a_linop,
std::string a_prefix = "hypre_mlnodelap",
int a_verbose = 0 )

Assemble the composite matrix from a prepared linear operator.

Parameters
a_linopMLNodeLaplacian with sigma set and masks built (e.g. after an MLMG solve or MLMG::prepareForSolve).
a_prefixParmParse prefix for the hypre solver options.
a_verboseVerbosity.

◆ ~HypreMLNodeLap()

amrex::HypreMLNodeLap::~HypreMLNodeLap ( )
default

◆ HypreMLNodeLap() [2/3]

amrex::HypreMLNodeLap::HypreMLNodeLap ( HypreMLNodeLap const & )
delete

◆ HypreMLNodeLap() [3/3]

amrex::HypreMLNodeLap::HypreMLNodeLap ( HypreMLNodeLap && )
delete

Member Function Documentation

◆ buildMatrix()

void amrex::HypreMLNodeLap::buildMatrix ( )

Internal: called by the constructor and updateMatrix (public only for CUDA extended lambdas)

◆ getFinalResidualNorm()

Real amrex::HypreMLNodeLap::getFinalResidualNorm ( ) const
inlinenodiscard

◆ getMatrixScale()

Real amrex::HypreMLNodeLap::getMatrixScale ( ) const
inlinenodiscardnoexcept

With setup reuse, the matrix of a later updateMatrix() is scaled to the 2-norm of the one the kept setup was done for, and the right-hand side with it (as for HypreMLABecLap). The factor of the last update.

◆ getNumIters()

int amrex::HypreMLNodeLap::getNumIters ( ) const
inlinenodiscard

Iterations and final relative residual of the last solve.

◆ numUnknowns()

BigInt amrex::HypreMLNodeLap::numUnknowns ( ) const
inlinenodiscard

Number of composite unknowns.

◆ operator=() [1/2]

HypreMLNodeLap & amrex::HypreMLNodeLap::operator= ( HypreMLNodeLap && )
delete

◆ operator=() [2/2]

HypreMLNodeLap & amrex::HypreMLNodeLap::operator= ( HypreMLNodeLap const & )
delete

◆ populateMatrix()

void amrex::HypreMLNodeLap::populateMatrix ( Gpu::DeviceVector< BigInt > & rows,
Gpu::DeviceVector< BigInt > & cols,
Gpu::DeviceVector< Real > & vals )

Internal: the assembled triplets to the backend's matrix (public only for CUDA extended lambdas)

◆ resetSolverSetup()

void amrex::HypreMLNodeLap::resetSolverSetup ( )
inline

Redo the solver setup (hypre) or the AlgMG hierarchy at the next solve.

◆ setReuseSetupMaxChange()

void amrex::HypreMLNodeLap::setReuseSetupMaxChange ( Real f)
inline

Redo the setup at the next solve when the matrix, scaled to the kept setup's, has changed by more than this fraction (2-norm) since that setup (0: never; also <prefix>.reuse_setup_max_change). Keeps a copy of the values of every matrix built while it is set, reuse on or off, so that the matrix of a setup kept later is the reference. Set after the matrix was built (before or after its setup), or after a solve redid the setup, the reference is the matrix of the next updateMatrix().

◆ setReuseSetupMaxIter()

void amrex::HypreMLNodeLap::setReuseSetupMaxIter ( int n)
inlinenoexcept

With setup reuse: redo the setup at the next solve when a solve with a reused setup needs more than n iterations (0: never; this is also <prefix>.reuse_setup_max_iter)

◆ setReuseSolverSetup()

void amrex::HypreMLNodeLap::setReuseSolverSetup ( bool v)

Keep the solver setup across updateMatrix() calls, as HypreMLABecLap::setReuseSolverSetup: the kept setup only approximates the updated operator, and a solve with it that does not converge redoes the setup and continues once before failing. Can be set at any time: turned on after a solve, the next updateMatrix() keeps that solve's setup (with the hypre backend it assembles the matrix once more, scaled to the kept setup's; later updates are in place). With reuse on, the setup is redone only after resetSolverSetup() and by the reuse controls below (<prefix>.recompute_preconditioner is off); with reuse off, after every updateMatrix() (and on every solve if that option is on).

◆ setThrowException()

void amrex::HypreMLNodeLap::setThrowException ( bool t)
inlinenoexcept

Throw std::runtime_error instead of aborting when the solve fails (no convergence, a hypre error, a non-finite residual, AlgMG diverging)

◆ solve()

void amrex::HypreMLNodeLap::solve ( Vector< MultiFab * > const & a_sol,
Vector< MultiFab const * > const & a_rhs,
Real a_reltol,
Real a_abstol,
int a_maxiter )

Solve the composite system.

Parameters
a_solPer-level nodal solution. On input, its values on Dirichlet domain boundaries are the boundary values (as with MLMG); on output it is filled everywhere, including covered and coarse/fine nodes, like MLMG.
a_rhsPer-level nodal right-hand side as produced by MLNodeLaplacian::compRHS (MLMG's composite RHS).
a_reltolRelative tolerance.
a_abstolAbsolute tolerance (<= 0: unused).
a_maxiterIteration limit.

◆ updateMatrix()

void amrex::HypreMLNodeLap::updateMatrix ( )

Assemble the matrix again from the operator's current coefficients, for the following solves: the MLNodeLaplacian of the constructor with new values of sigma (the same grids, boundary conditions, masks and EB, so that the matrix pattern is unchanged). With setReuseSolverSetup(true) the values are updated in place and the hypre solver setup, or the AlgMG hierarchy, is kept (see HypreMLABecLap::setReuseSolverSetup); otherwise the setup is redone at the next solve. Collective over the operator's communicator.


The documentation for this class was generated from the following files: