Class mgrid::MultigridBase

ClassList > mgrid > MultigridBase

Abstract base class for the multigrid solvers. More...

#include <multigrid_base.hpp>

Inherited by the following classes: mgrid::LinearMultigrid, mgrid::NonlinearMultigrid

Public Attributes

Type	Name
int	coarsestLevel Level index of the coarsest grid (always 0).
int	finestLevel Level index of the finest grid.

Public Functions

Type	Name
	MultigridBase (const Settings & settings) Builds the solver state from `settings` .
virtual double	differential_operator (Level level, int i, int j) = 0 Evaluates the discrete PDE operator at one grid point.
void	evaluate_operator (Level level, FDArray & result) Evaluates the discrete operator over `result` .
void	evaluate_residual (Level level, FDArray & result) Evaluates the residual `source - operator(solution)` over`result` .
virtual std::string	filename (std::string root="") = 0 Builds the output file name for this problem.
bool	fully_periodic () const True when both axes of the grid hierarchy wrap periodically.
FDArray &	get_result () The current solution on the finest grid.
void	initial_guess (T arg) Sets the finest-level initial guess and flags it as provided.
virtual void	multigrid () Runs the multigrid cycle.
void	relax (Level level, unsigned long n) Smooths `solution[level]` with a fixed number of sweeps.
void	relax (Level level, double tolerance) Smooths `solution[level]` until the relative change falls below`tolerance` or`maxIterations` sweeps have run.
virtual void	relaxation_updater (Level level, int i, int j) = 0 Applies one in-place relaxation update at a single grid point.
virtual void	solve () Solves the problem.
FDArray &	source_term () Accesses the finest-level source term.
void	source_term (T arg) Sets the finest-level source term and flags it as provided.
virtual void	write (int numOfVariables, std::string root="") Writes the finest-level solution (and optional derived fields) to a netCDF-4 file.
virtual	~MultigridBase () = default Defaulted polymorphic destructor.

Protected Attributes

Type	Name
const double	aspect Domain aspect ratio.
const int	cycleType FMG cycle type (V / W / three).
bool	initialIsSet = `{false}` Has an initial guess been provided?
const unsigned long	maxIterations Cap on relax-to-tolerance sweeps.
int	nxfine = `{0}`
int	nzfine = `{0}` Finest-grid extents (rows, columns).
const unsigned long	postRelax Post-correction relaxation sweeps.
const unsigned long	preRelax Pre-correction relaxation sweeps.
const double	residualTolerance Convergence tolerance for the solver.
Stack	solution
Stack	source
bool	sourceIsSet = `{false}` Has a source term been provided?
Stack	temp Solution, source and scratch grid hierarchies.

Protected Functions

Type	Name
void	mark_source_set () Flags the source term as set without touching its array.
virtual void	on_cycle_end (double residual_norm)

Detailed Description

Owns the grid hierarchy (solution, source and scratch Stacks), the scalar solver settings (copied once from Settings and held const), and the smoothing primitives every concrete solver shares: relax, evaluate_operator and evaluate_residual. Concrete solvers supply the discrete PDE by overriding differential_operator, relaxation_updater and filename, and implement the cycle by overriding multigrid (see LinearMultigrid / NonlinearMultigrid).

Note:

Modernised from the 2011 mgrid::MultigridBase: loop macros replaced by the field.hpp iteration helpers, power<2> by a local sq, and maxIterations corrected from double to unsigned long (it is an iteration count).

Public Attributes Documentation

variable coarsestLevel

Level index of the coarsest grid (always 0).

int mgrid::MultigridBase::coarsestLevel;

Note:

Public for the same reason as finestLevel.

variable finestLevel

Level index of the finest grid.

int mgrid::MultigridBase::finestLevel;

Note:

Public so solver subclasses and tests can name the finest level directly (there is no finest() accessor).

Public Functions Documentation

function MultigridBase

Builds the solver state from settings .

explicit mgrid::MultigridBase::MultigridBase (
    const Settings & settings
)

Parameters:

settings solver configuration; supplies the grid geometry for the three Stacks and the scalar parameters copied into the const members.

Postcondition:

finestLevel, coarsestLevel, nxfine and nzfine are read back from the freshly constructed solution stack; no source or initial guess is marked as set.

function differential_operator

Evaluates the discrete PDE operator at one grid point.

virtual double mgrid::MultigridBase::differential_operator (
    Level level,
    int i,
    int j
) = 0

Parameters:

level grid level.
i row index.
j column index.

Returns:

the operator value at (i, j).

Note:

Pure virtual: a concrete solver must define the discrete operator. Non-const because a concrete solver may mutate scratch state during operator evaluation.

function evaluate_operator

Evaluates the discrete operator over result .

void mgrid::MultigridBase::evaluate_operator (
    Level level,
    FDArray & result
)

Parameters:

level grid level whose operator is evaluated.
result destination array; zeroed first, then result(i, j) receives differential_operator(level, i, j) over each axis's Axis::lo() ..hi() range (the interior 1..n-1 on a bounded axis, the full 0..n on a periodic one). Skipped edge entries stay 0.

function evaluate_residual

Evaluates the residual source - operator(solution) overresult .

void mgrid::MultigridBase::evaluate_residual (
    Level level,
    FDArray & result
)

Parameters:

level grid level whose residual is evaluated.
result destination array; zeroed first, then result(i, j) receives source[level](i, j) - differential_operator(level, i, j) over each axis's Axis::lo() ..hi() range (the interior 1..n-1 on a bounded axis, the full 0..n on a periodic one). Skipped edge entries stay 0.

function filename

Builds the output file name for this problem.

virtual std::string mgrid::MultigridBase::filename (
    std::string root=""
) = 0

Parameters:

root optional prefix prepended to the generated name.

Returns:

the file name (without extension).

Note:

Pure virtual: a concrete solver must name its output.

function fully_periodic

True when both axes of the grid hierarchy wrap periodically.

bool mgrid::MultigridBase::fully_periodic () const

Returns:

solution[ coarsestLevel ].x_axis().periodic && solution[ coarsestLevel ].z_axis().periodic.

Note:

A fully-periodic discrete operator has a constant null space, so the smoothers project out the mean each sweep and the operator/residual evaluations run over the whole grid (Axis::lo() ..hi() == 0..n).

function get_result

The current solution on the finest grid.

inline FDArray & mgrid::MultigridBase::get_result ()

Returns:

reference to solution[ finestLevel ].

function initial_guess

Sets the finest-level initial guess and flags it as provided.

template<class T>
inline void mgrid::MultigridBase::initial_guess (
    T arg
)

Template parameters:

T anything assignable to FDArray (scalar, Field2D, FDArray, or a double(double, double) sampling function).

Parameters:

arg value assigned to solution[ finestLevel ].

Postcondition:

initialIsSet is true.

function multigrid

Runs the multigrid cycle.

inline virtual void mgrid::MultigridBase::multigrid ()

Note:

Base implementation does nothing; LinearMultigrid and NonlinearMultigrid override it.

function relax [1/2]

Smooths solution[level] with a fixed number of sweeps.

void mgrid::MultigridBase::relax (
    Level level,
    unsigned long n
)

Parameters:

level grid level to relax.
n number of red-black relaxation sweeps to perform.

Note:

The unsigned long overload is the fixed-iteration-count smoother; each sweep visits the interior in red-black order via relaxation_updater and is followed by update_boundaries().

function relax [2/2]

Smooths solution[level] until the relative change falls belowtolerance ormaxIterations sweeps have run.

void mgrid::MultigridBase::relax (
    Level level,
    double tolerance
)

Parameters:

level grid level to relax.
tolerance stop once sqrt(sum(delta^2)) / sqrt(sum(u^2)) for a sweep is below this value.

Note:

The double overload is the relax-to-tolerance smoother; it caps at maxIterations sweeps.

function relaxation_updater

Applies one in-place relaxation update at a single grid point.

virtual void mgrid::MultigridBase::relaxation_updater (
    Level level,
    int i,
    int j
) = 0

Parameters:

level grid level.
i row index.
j column index.

Note:

Pure virtual: a concrete solver must define the point smoother; it writes the updated value straight into solution[level](i, j).

function solve

Solves the problem.

inline virtual void mgrid::MultigridBase::solve ()

Note:

Base implementation just calls multigrid(); subclasses of the concrete solvers may override for different behaviour.

function source_term [1/2]

Accesses the finest-level source term.

inline FDArray & mgrid::MultigridBase::source_term ()

Returns:

reference to source[ finestLevel ].

function source_term [2/2]

Sets the finest-level source term and flags it as provided.

template<class T>
inline void mgrid::MultigridBase::source_term (
    T arg
)

Template parameters:

T anything assignable to FDArray (scalar, Field2D, FDArray, or a double(double, double) sampling function).

Parameters:

arg value assigned to source[ finestLevel ].

Postcondition:

sourceIsSet is true.

function write

Writes the finest-level solution (and optional derived fields) to a netCDF-4 file.

virtual void mgrid::MultigridBase::write (
    int numOfVariables,
    std::string root=""
)

Parameters:

numOfVariables how many fields to write: always "solution"; plus "gradient" (gradient magnitude) when > 1; plus "log_residual" (base-10 log of the residual) when > 2.
root optional path/prefix; filename() and .nc are appended.

Postcondition:

The file also carries the "x"/"z" axis coordinate variables and a "aspect_ratio" global attribute.

Exception:

netCDF::exceptions::NcException on any netCDF failure.

function ~MultigridBase

Defaulted polymorphic destructor.

virtual mgrid::MultigridBase::~MultigridBase () = default

Protected Attributes Documentation

variable aspect

Domain aspect ratio.

const double mgrid::MultigridBase::aspect;

variable cycleType

FMG cycle type (V / W / three).

const int mgrid::MultigridBase::cycleType;

variable initialIsSet

Has an initial guess been provided?

bool mgrid::MultigridBase::initialIsSet;

variable maxIterations

Cap on relax-to-tolerance sweeps.

const unsigned long mgrid::MultigridBase::maxIterations;

variable nxfine

int mgrid::MultigridBase::nxfine;

variable nzfine

Finest-grid extents (rows, columns).

int mgrid::MultigridBase::nzfine;

variable postRelax

Post-correction relaxation sweeps.

const unsigned long mgrid::MultigridBase::postRelax;

variable preRelax

Pre-correction relaxation sweeps.

const unsigned long mgrid::MultigridBase::preRelax;

variable residualTolerance

Convergence tolerance for the solver.

const double mgrid::MultigridBase::residualTolerance;

variable solution

Stack mgrid::MultigridBase::solution;

variable source

Stack mgrid::MultigridBase::source;

variable sourceIsSet

Has a source term been provided?

bool mgrid::MultigridBase::sourceIsSet;

variable temp

Solution, source and scratch grid hierarchies.

Stack mgrid::MultigridBase::temp;

Protected Functions Documentation

function mark_source_set

Flags the source term as set without touching its array.

inline void mgrid::MultigridBase::mark_source_set ()

Note:

For solver subclasses that fill source[ finestLevel ] directly.

function on_cycle_end

inline virtual void mgrid::MultigridBase::on_cycle_end (
    double residual_norm
)

Called once per V/W-cycle at the finest full-multigrid stage; override to observe the residual-norm history.

The documentation for this class was generated from the following file include/multigrid/multigrid_base.hpp