NumLib::StaggeredCoupling Class Reference

Detailed Description

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

Definition at line 46 of file StaggeredCoupling.h.

#include <StaggeredCoupling.h>

Public Member Functions
	StaggeredCoupling (const int global_coupling_max_iterations, std::vector< CouplingNodeVariant > &&coupling_nodes)
	~StaggeredCoupling ()
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 >	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 >	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.
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 56 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 49 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 59 of file StaggeredCoupling.h.

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

~StaggeredCoupling()

NumLib::StaggeredCoupling::~StaggeredCoupling

(

)

Definition at line 23 of file StaggeredCoupling.cpp.

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

References NumLib::GlobalVectorProvider::provider, NumLib::VectorProvider::releaseVector(), 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 72 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 21 of file StaggeredCoupling-impl.h.

{
    auto const [nonlinear_solver_status, coupling_iteration_converged] =
        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);
 
    if (!coupling_iteration_converged)
    {
        WARN(
            "The coupling iterations reaches its maximum number in time step "
            "#{:d} at t = {:g} s",
            timestep_id, t);
    }
 
    return nonlinear_solver_status;
}

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

executeConcrete()

template<typename ProcessData , typename Output >

std::tuple< NumLib::NonlinearSolverStatus, bool > 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 81 of file StaggeredCoupling-impl.h.

{
    setFirstIterationIndicator(coupling_nodes);
 
    NumLib::NonlinearSolverStatus nonlinear_solver_status{true, -1};
 
    bool coupling_iteration_converged = true;
    for (int global_coupling_iteration = 0;
         global_coupling_iteration < max_iterations;
         global_coupling_iteration++,
             resetCouplingConvergenceCriteria(coupling_nodes))
    {
        coupling_iteration_converged = true;
 
        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] =
                    executeSubCoupling(
                        coupling_node, t, dt, timestep_id, process_solutions,
                        process_solutions_prev, per_process_data, outputs,
                        solve_one_time_step_one_process);
 
                if (!local_nonlinear_solver_status.error_norms_met)
                {
                    coupling_iteration_converged = false;
                    return {local_nonlinear_solver_status,
                            coupling_iteration_converged};
                }
 
                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};
            }
 
            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};
}

References checkCouplingConvergence(), BaseLib::RunTime::elapsed(), 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 47 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 > 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 180 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] =
        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};
}

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 31 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::VectorProvider::getVector(), NumLib::GlobalVectorProvider::provider, and solutions_of_last_cpl_iteration_.

resetCouplingConvergenceCriteria()

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

private

Definition at line 59 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 45 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 97 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 105 of file StaggeredCoupling.h.

Referenced by 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 93 of file StaggeredCoupling.h.

Referenced by execute().

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 150 of file StaggeredCoupling.h.

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

---

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

• NumLib/StaggeredCoupling/StaggeredCoupling.h
• NumLib/StaggeredCoupling/StaggeredCoupling-impl.h
• NumLib/StaggeredCoupling/StaggeredCoupling.cpp