NumLib::StaggeredCoupling Class Reference

Detailed Description

A class designed to manage the solution of coupled equations using the staggered method.

Definition at line 38 of file StaggeredCoupling.h.

#include <StaggeredCoupling.h>

Public Member Functions
	StaggeredCoupling (const int global_coupling_max_iterations, std::vector< CouplingNodeVariant > &&coupling_nodes)
	~StaggeredCoupling ()
int	lastNumberOfCouplingIterations () const
void	initializeCoupledSolutions (std::vector< GlobalVector * > const &process_solutions)
template<typename ProcessData, typename Output>
NumLib::NonlinearSolverStatus	execute (const double t, const double dt, const std::size_t timestep_id, std::vector< GlobalVector * > &process_solutions, std::vector< GlobalVector * > const &process_solutions_prev, std::vector< std::unique_ptr< ProcessData > > const &per_process_data, std::vector< Output > const &outputs, ProcessSolver< ProcessData, Output > const &solve_one_time_step_one_process)

Private Types
template<typename ProcessData, typename Output>
using	ProcessSolver
using	CouplingNodeVariant = std::variant<CouplingNode, RootCouplingNode>

Private Member Functions
template<typename ProcessData, typename Output>
std::tuple< NumLib::NonlinearSolverStatus, bool, int >	executeConcrete (std::vector< CouplingNodeVariant > &coupling_nodes, const int max_iterations, const double t, const double dt, const std::size_t timestep_id, std::vector< GlobalVector * > &process_solutions, std::vector< GlobalVector * > const &process_solutions_prev, std::vector< std::unique_ptr< ProcessData > > const &per_process_data, std::vector< Output > const &outputs, ProcessSolver< ProcessData, Output > const &solve_one_time_step_one_process)
template<typename ProcessData, typename Output>
std::tuple< NumLib::NonlinearSolverStatus, bool, int >	executeSubCoupling (CouplingNodeVariant &coupling_node, const double t, const double dt, const std::size_t timestep_id, std::vector< GlobalVector * > &process_solutions, std::vector< GlobalVector * > const &process_solutions_prev, std::vector< std::unique_ptr< ProcessData > > const &per_process_data, std::vector< Output > const &outputs, ProcessSolver< ProcessData, Output > const &solve_one_time_step_one_process)
template<typename ProcessData, typename Output>
NumLib::NonlinearSolverStatus	executeSingleIteration (int const global_coupling_iteration, CouplingNode const &regular_coupling_node, const double t, const double dt, const std::size_t timestep_id, std::vector< GlobalVector * > &process_solutions, std::vector< GlobalVector * > const &process_solutions_prev, std::vector< std::unique_ptr< ProcessData > > const &per_process_data, std::vector< Output > const &outputs, ProcessSolver< ProcessData, Output > const &solve_one_time_step_one_process)
void	setFirstIterationIndicator (std::vector< CouplingNodeVariant > const &coupling_nodes)
	Set the indicator of the first staggered coupling iteration be true.
void	resetCouplingConvergenceCriteria (std::vector< CouplingNodeVariant > const &coupling_nodes)
bool	checkCouplingConvergence (const bool convergence_of_last_process, CouplingNode const &coupling_node, GlobalVector const &x) const
void	updatePreviousSolution (int const process_id, GlobalVector const &x)

Private Attributes
const int	global_coupling_max_iterations_
	Maximum iteration number of the coupling loop of the staggered scheme.
int	number_of_global_coupling_iterations_ = 0
std::vector< CouplingNodeVariant >	coupling_nodes_
std::vector< GlobalVector * >	solutions_of_last_cpl_iteration_

Member Typedef Documentation

CouplingNodeVariant

using NumLib::StaggeredCoupling::CouplingNodeVariant = std::variant<CouplingNode, RootCouplingNode>

private

Definition at line 48 of file StaggeredCoupling.h.

ProcessSolver

template<typename ProcessData, typename Output>

using NumLib::StaggeredCoupling::ProcessSolver

private

Initial value:

 std::function<NumLib::NonlinearSolverStatus(
        std::vector<GlobalVector*>& ,
        std::vector<GlobalVector*> const& ,
        std::size_t const , double const ,
        double const , ProcessData const& ,
        std::vector<Output> const& )>

Definition at line 41 of file StaggeredCoupling.h.

Constructor & Destructor Documentation

StaggeredCoupling()

NumLib::StaggeredCoupling::StaggeredCoupling ( const int global_coupling_max_iterations, std::vector< CouplingNodeVariant > && coupling_nodes )

inline

Definition at line 51 of file StaggeredCoupling.h.

        : global_coupling_max_iterations_(global_coupling_max_iterations),
          coupling_nodes_(std::move(coupling_nodes))
    {
    }

References coupling_nodes_, and global_coupling_max_iterations_.

~StaggeredCoupling()

NumLib::StaggeredCoupling::~StaggeredCoupling

(

)

Definition at line 16 of file StaggeredCoupling.cpp.

{
    for (auto* x : solutions_of_last_cpl_iteration_)
    {
        NumLib::GlobalVectorProvider::provider.releaseVector(*x);
    }
}

References NumLib::GlobalVectorProvider::provider, and solutions_of_last_cpl_iteration_.

Member Function Documentation

checkCouplingConvergence()

bool NumLib::StaggeredCoupling::checkCouplingConvergence ( const bool convergence_of_last_process, CouplingNode const & coupling_node, GlobalVector const & x ) const

private

Definition at line 65 of file StaggeredCoupling.cpp.

{
    bool is_coupling_iteration_converged = convergence_of_last_process;
 
    auto& x_old = *solutions_of_last_cpl_iteration_[coupling_node.process_id];
    // Since x_old can be immediately refreshed after computing dx,
    // it is assigned with dx to save memory usage
    MathLib::LinAlg::axpy(x_old, -1.0, x);  // save dx = x - x_old to x_old.
    INFO(
        "------- Checking convergence criterion for coupled "
        "solution of process {:s} with ID {:d} -------",
        coupling_node.process_name, coupling_node.process_id);
    // Note: x_old stores dx
    coupling_node.convergence_criterion->checkDeltaX(x_old, x);
 
    is_coupling_iteration_converged =
        is_coupling_iteration_converged &&
        coupling_node.convergence_criterion->isSatisfied();
 
    return is_coupling_iteration_converged;
}

References MathLib::LinAlg::axpy(), NumLib::CouplingNode::convergence_criterion, INFO(), NumLib::CouplingNode::process_id, NumLib::CouplingNode::process_name, and solutions_of_last_cpl_iteration_.

Referenced by executeConcrete().

execute()

template<typename ProcessData, typename Output>

NumLib::NonlinearSolverStatus NumLib::StaggeredCoupling::execute	(	const double	t,
		const double	dt,
		const std::size_t	timestep_id,
		std::vector< GlobalVector * > &	process_solutions,
		std::vector< GlobalVector * > const &	process_solutions_prev,
		std::vector< std::unique_ptr< ProcessData > > const &	per_process_data,
		std::vector< Output > const &	outputs,
		ProcessSolver< ProcessData, Output > const &	solve_one_time_step_one_process )

It solves the equations of all coupled processes by the staggered method, and it returns nonlinear solver status.

Definition at line 16 of file StaggeredCoupling-impl.h.

{
    auto [nonlinear_solver_status, coupling_iteration_converged,
          number_of_coupling_iterations] =
        executeConcrete(coupling_nodes_, global_coupling_max_iterations_, t, dt,
                        timestep_id, process_solutions, process_solutions_prev,
                        per_process_data, outputs,
                        solve_one_time_step_one_process);
 
    number_of_global_coupling_iterations_ = number_of_coupling_iterations;
 
    // A failed per-process nonlinear solver is already reported as such and
    // leaves the coupling loop early with unmet error norms. Reaching the
    // iteration limit with all processes converged individually is the
    // remaining failure mode: the coupling residuum is not converged, hence
    // the solution must not be accepted.
    if (!coupling_iteration_converged &&
        nonlinear_solver_status.error_norms_met)
    {
        WARN(
            "The coupling iterations reached their maximum number {:d} in time "
            "step #{:d} at t = {:g} s. The time step will be rejected.",
            global_coupling_max_iterations_, timestep_id, t);
 
        nonlinear_solver_status.error_norms_met = false;
        // The time loop decides on the acceptance of the time step by means of
        // the per-process nonlinear solver states.
        for (auto const& process_data : per_process_data)
        {
            process_data->nonlinear_solver_status.error_norms_met = false;
        }
    }
 
    return nonlinear_solver_status;
}

References coupling_nodes_, executeConcrete(), global_coupling_max_iterations_, number_of_global_coupling_iterations_, and WARN().

executeConcrete()

template<typename ProcessData, typename Output>

std::tuple< NumLib::NonlinearSolverStatus, bool, int > NumLib::StaggeredCoupling::executeConcrete ( std::vector< CouplingNodeVariant > & coupling_nodes, const int max_iterations, const double t, const double dt, const std::size_t timestep_id, std::vector< GlobalVector * > & process_solutions, std::vector< GlobalVector * > const & process_solutions_prev, std::vector< std::unique_ptr< ProcessData > > const & per_process_data, std::vector< Output > const & outputs, ProcessSolver< ProcessData, Output > const & solve_one_time_step_one_process )

private

It solves the equation of each coupling process (treated as a coupling node) via function recursion, and it returns nonlinear solver status, and an indicator of coupling iteration convergence.

Definition at line 93 of file StaggeredCoupling-impl.h.

{
    setFirstIterationIndicator(coupling_nodes);
 
    NumLib::NonlinearSolverStatus nonlinear_solver_status{true, -1};
 
    bool coupling_iteration_converged = true;
    int number_of_coupling_iterations = 0;
    // Maximum number of coupling iterations over all nested sub-couplings.
    int number_of_sub_coupling_iterations = 0;
    for (int global_coupling_iteration = 0;
         global_coupling_iteration < max_iterations;
         global_coupling_iteration++,
             resetCouplingConvergenceCriteria(coupling_nodes))
    {
        coupling_iteration_converged = true;
        number_of_coupling_iterations = global_coupling_iteration + 1;
 
        INFO("Global coupling iteration #{:d} started.",
             global_coupling_iteration);
        BaseLib::RunTime coupling_iteration_timer;
        coupling_iteration_timer.start();
 
        for (auto& coupling_node : coupling_nodes)
        {
            // For the dummy root node, perform sub-coupling computation.
            if (std::holds_alternative<RootCouplingNode>(coupling_node))
            {
                auto const [local_nonlinear_solver_status,
                            local_coupling_iteration_converged,
                            local_number_of_coupling_iterations] =
                    executeSubCoupling(
                        coupling_node, t, dt, timestep_id, process_solutions,
                        process_solutions_prev, per_process_data, outputs,
                        solve_one_time_step_one_process);
 
                number_of_sub_coupling_iterations =
                    std::max(number_of_sub_coupling_iterations,
                             local_number_of_coupling_iterations);
 
                if (!local_nonlinear_solver_status.error_norms_met)
                {
                    coupling_iteration_converged = false;
                    return {local_nonlinear_solver_status,
                            coupling_iteration_converged,
                            std::max(number_of_coupling_iterations,
                                     number_of_sub_coupling_iterations)};
                }
 
                coupling_iteration_converged =
                    coupling_iteration_converged &&
                    local_coupling_iteration_converged;
                continue;
            }
 
            CouplingNode const& regular_coupling_node =
                std::get<CouplingNode>(coupling_node);
 
            nonlinear_solver_status = executeSingleIteration(
                global_coupling_iteration, regular_coupling_node, t, dt,
                timestep_id, process_solutions, process_solutions_prev,
                per_process_data, outputs, solve_one_time_step_one_process);
 
            if (!nonlinear_solver_status.error_norms_met)
            {
                WARN(
                    "The nonlinear solver failed in time step #{:d} at t = "
                    "{:g} s for process {:s}.",
                    timestep_id, t, regular_coupling_node.process_name);
                coupling_iteration_converged = false;
                return {nonlinear_solver_status, coupling_iteration_converged,
                        std::max(number_of_coupling_iterations,
                                 number_of_sub_coupling_iterations)};
            }
 
            auto const& x =
                *process_solutions[regular_coupling_node.process_id];
 
            // It is unnecessary to check convergence for a process at the first
            // iteration
            if (global_coupling_iteration > 0)
            {
                coupling_iteration_converged = checkCouplingConvergence(
                    coupling_iteration_converged, regular_coupling_node, x);
            }
 
            updatePreviousSolution(regular_coupling_node.process_id, x);
 
        }  // end of for (auto& process_data : _per_process_data)
 
        // At least to run two coupling iterations, meaning that the coupling
        // has at least two coupling nodes.
        INFO("Global coupling iteration #{:d} took {:g} s.",
             global_coupling_iteration, coupling_iteration_timer.elapsed());
        if (coupling_iteration_converged && global_coupling_iteration > 0)
        {
            break;
        }
    }
 
    return {nonlinear_solver_status, coupling_iteration_converged,
            std::max(number_of_coupling_iterations,
                     number_of_sub_coupling_iterations)};
}

References checkCouplingConvergence(), BaseLib::RunTime::elapsed(), NumLib::NonlinearSolverStatus::error_norms_met, executeSingleIteration(), executeSubCoupling(), INFO(), NumLib::CouplingNode::process_id, NumLib::CouplingNode::process_name, resetCouplingConvergenceCriteria(), setFirstIterationIndicator(), BaseLib::RunTime::start(), updatePreviousSolution(), and WARN().

Referenced by execute(), and executeSubCoupling().

executeSingleIteration()

template<typename ProcessData, typename Output>

NumLib::NonlinearSolverStatus NumLib::StaggeredCoupling::executeSingleIteration ( int const global_coupling_iteration, CouplingNode const & regular_coupling_node, const double t, const double dt, const std::size_t timestep_id, std::vector< GlobalVector * > & process_solutions, std::vector< GlobalVector * > const & process_solutions_prev, std::vector< std::unique_ptr< ProcessData > > const & per_process_data, std::vector< Output > const & outputs, ProcessSolver< ProcessData, Output > const & solve_one_time_step_one_process )

private

Definition at line 59 of file StaggeredCoupling-impl.h.

{
    BaseLib::RunTime time_timestep_process;
    time_timestep_process.start();
 
    auto const process_id = regular_coupling_node.process_id;
    auto const& process_name = regular_coupling_node.process_name;
    INFO("Solve process #{:d} (named as {:s})", process_id, process_name);
 
    auto& process_data = *(per_process_data[process_id]);
 
    process_data.nonlinear_solver_status = solve_one_time_step_one_process(
        process_solutions, process_solutions_prev, timestep_id, t, dt,
        process_data, outputs);
 
    INFO(
        "[time] Solving process #{:d} (named as {:s}) took {:g} s in "
        "time step #{} coupling iteration #{}.",
        process_id, process_name, time_timestep_process.elapsed(), timestep_id,
        global_coupling_iteration);
 
    return process_data.nonlinear_solver_status;
}

References BaseLib::RunTime::elapsed(), INFO(), NumLib::CouplingNode::process_id, NumLib::CouplingNode::process_name, and BaseLib::RunTime::start().

Referenced by executeConcrete().

executeSubCoupling()

template<typename ProcessData, typename Output>

std::tuple< NumLib::NonlinearSolverStatus, bool, int > NumLib::StaggeredCoupling::executeSubCoupling ( CouplingNodeVariant & coupling_node, const double t, const double dt, const std::size_t timestep_id, std::vector< GlobalVector * > & process_solutions, std::vector< GlobalVector * > const & process_solutions_prev, std::vector< std::unique_ptr< ProcessData > > const & per_process_data, std::vector< Output > const & outputs, ProcessSolver< ProcessData, Output > const & solve_one_time_step_one_process )

private

Definition at line 207 of file StaggeredCoupling-impl.h.

{
    INFO("--- Execute sub-coupling:");
    RootCouplingNode& root_coupling_node =
        std::get<RootCouplingNode>(coupling_node);
    const int local_max_iterations =
        std::get<CouplingNode>(root_coupling_node.sub_coupling_nodes.front())
            .max_iterations;
 
    auto const [sub_nonlinear_solver_status, sub_coupling_iteration_converged,
                sub_number_of_coupling_iterations] =
        executeConcrete<ProcessData, Output>(
            root_coupling_node.sub_coupling_nodes, local_max_iterations, t, dt,
            timestep_id, process_solutions, process_solutions_prev,
            per_process_data, outputs, solve_one_time_step_one_process);
 
    INFO("--- End sub-coupling.");
    return {sub_nonlinear_solver_status, sub_coupling_iteration_converged,
            sub_number_of_coupling_iterations};
}

References executeConcrete(), INFO(), and NumLib::RootCouplingNode::sub_coupling_nodes.

Referenced by executeConcrete().

initializeCoupledSolutions()

void NumLib::StaggeredCoupling::initializeCoupledSolutions

(

std::vector< GlobalVector * > const &

process_solutions

)

This function fills the vector of solutions of coupled processes of processes, solutions_of_coupled_processes_, and initializes the vector of solutions of the previous coupling iteration, _solutions_of_last_cpl_iteration.

Definition at line 24 of file StaggeredCoupling.cpp.

{
    for (auto const* const x : process_solutions)
    {
        // Create a vector to store the solution of the last coupling iteration
        auto& x0 = NumLib::GlobalVectorProvider::provider.getVector(*x);
        MathLib::LinAlg::copy(*x, x0);
 
        // append a solution vector of suitable size
        solutions_of_last_cpl_iteration_.emplace_back(&x0);
    }
}

References MathLib::LinAlg::copy(), NumLib::GlobalVectorProvider::provider, and solutions_of_last_cpl_iteration_.

lastNumberOfCouplingIterations()

int NumLib::StaggeredCoupling::lastNumberOfCouplingIterations ( ) const

inline

Number of global coupling iterations performed in the last solved time step. Used to drive the time step size control in the staggered scheme.

Definition at line 62 of file StaggeredCoupling.h.

    {
        return number_of_global_coupling_iterations_;
    }

References number_of_global_coupling_iterations_.

resetCouplingConvergenceCriteria()

void NumLib::StaggeredCoupling::resetCouplingConvergenceCriteria ( std::vector< CouplingNodeVariant > const & coupling_nodes )

private

Definition at line 52 of file StaggeredCoupling.cpp.

{
    auto is_regular_node = [](const CouplingNodeVariant& node)
    { return std::holds_alternative<CouplingNode>(node); };
 
    for (auto& coupling_node :
         coupling_nodes | ranges::views::filter(is_regular_node))
    {
        std::get<CouplingNode>(coupling_node).convergence_criterion->reset();
    }
}

Referenced by executeConcrete().

setFirstIterationIndicator()

void NumLib::StaggeredCoupling::setFirstIterationIndicator ( std::vector< CouplingNodeVariant > const & coupling_nodes )

private

Set the indicator of the first staggered coupling iteration be true.

Definition at line 38 of file StaggeredCoupling.cpp.

{
    auto is_regular_node = [](const CouplingNodeVariant& node)
    { return std::holds_alternative<CouplingNode>(node); };
 
    for (auto const& coupling_node :
         coupling_nodes | ranges::views::filter(is_regular_node))
    {
        std::get<CouplingNode>(coupling_node)
            .convergence_criterion->preFirstIteration();
    }
}

Referenced by executeConcrete().

updatePreviousSolution()

void NumLib::StaggeredCoupling::updatePreviousSolution ( int const process_id, GlobalVector const & x )

private

Definition at line 90 of file StaggeredCoupling.cpp.

{
    auto& x_old = *solutions_of_last_cpl_iteration_[process_id];
    MathLib::LinAlg::copy(x, x_old);
}

References MathLib::LinAlg::copy(), and solutions_of_last_cpl_iteration_.

Referenced by executeConcrete().

Member Data Documentation

coupling_nodes_

std::vector<CouplingNodeVariant> NumLib::StaggeredCoupling::coupling_nodes_

private

Coupling graph for the staggered scheme. It looks like:

x ... x o o / \ / \ / \ / \ x ... x x ... x

where x represents a coupling node, and o represents a dummy root coupling node.

Definition at line 108 of file StaggeredCoupling.h.

Referenced by StaggeredCoupling(), and execute().

global_coupling_max_iterations_

const int NumLib::StaggeredCoupling::global_coupling_max_iterations_

private

Maximum iteration number of the coupling loop of the staggered scheme.

Definition at line 92 of file StaggeredCoupling.h.

Referenced by StaggeredCoupling(), and execute().

number_of_global_coupling_iterations_

int NumLib::StaggeredCoupling::number_of_global_coupling_iterations_ = 0

private

Number of global coupling iterations performed in the last solved time step.

Definition at line 96 of file StaggeredCoupling.h.

Referenced by execute(), and lastNumberOfCouplingIterations().

solutions_of_last_cpl_iteration_

std::vector<GlobalVector*> NumLib::StaggeredCoupling::solutions_of_last_cpl_iteration_

private

Solutions of the previous coupling iteration for the convergence criteria of the coupling iteration.

Definition at line 153 of file StaggeredCoupling.h.

Referenced by ~StaggeredCoupling(), checkCouplingConvergence(), initializeCoupledSolutions(), and updatePreviousSolution().

---

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

• StaggeredCoupling.h
• StaggeredCoupling-impl.h
• StaggeredCoupling.cpp