LinearFVGradientManager Class Reference

Registration, update, and allocation logic for linear finite-volume cell gradients. More...

#include <LinearFVGradientManager.h>

Inheritance diagram for LinearFVGradientManager:

Classes
struct	LinearFVGradientContainer
	Gradient values for all variables using the same gradient method. More...

Public Member Functions
	LinearFVGradientManager (SystemBase &sys)
const FVGradientMethod &	resolveFVGradientMethod (const GradientMethodName &method_name)
	Resolve a named gradient method, constructing a built-in method when needed.
LinearFVGradientReader	registerFVGradient (unsigned int variable_number, const FVGradientMethod &method, unsigned int oldest_state=0)
	Register a variable for gradient values produced by a method object.

Protected Types
using	GradientContainer = LinearFVGradientReader::GradientContainer
	Non-owning view with one vector per spatial component of a cell-centered gradient field.
using	GradientStateContainer = LinearFVGradientReader::GradientStateContainer
	Gradient fields indexed by solution time state.
using	OwnedGradientContainer = std::vector< std::unique_ptr< libMesh::NumericVector< libMesh::Number > > >
	Owned vectors used for the current gradient and its replacement.

Protected Member Functions
void	computeGradients ()
	Compute and finalize all registered linear FV gradient fields.
void	updateFVGradient (const LinearFVGradientReader &reader)
	Update a registered gradient reader explicitly.
void	initializeLinearFVGradientStorage ()
	Initialize private current and replacement gradient storage.
void	initializeLinearFVGradientHistoryStorage ()
	Register named system vectors for requested historical gradient states.
void	rebuildLinearFVGradientStorage ()
	Rebuild cached gradient values and reusable scratch storage after mesh/DOF changes.
void	copyPreviousGradientStates (Moose::SolutionIterationType iteration_type, bool skip_current_to_old)
	Copy published gradient values into requested older states.
void	restoreGradientStates ()
	Restore current gradients from state one after a failed timestep.
bool	hasLinearFVGradients () const
	Whether any linear finite-volume gradient fields have been registered to this object.
void	initializeContainer (OwnedGradientContainer &container) const
	Allocate one zeroed vector per spatial component for gradient storage.
void	resizeGradientStateStorage (LinearFVGradientContainer &container, unsigned int oldest_state)
	Ensure that a method container stores every requested time state.
void	setCurrentGradientState (LinearFVGradientContainer &container) const
	Set solution state zero to the current gradient.
void	checkRestartedGradientHistory (const FVGradientMethod &method, LinearFVGradientContainer &container)
	Validate and mark gradient history loaded during restart or recovery.
void	initializeGradientStatesForTimeAdvance ()
	Compute and publish uninitialized gradients before their first time-state advancement.
LinearFVGradientContainer &	computeLinearFVGradientContainer (const FVGradientMethod &method)
	Compute replacement field values for a registered gradient method.
void	finalizeLinearFVGradientContainer (LinearFVGradientContainer &container)
	Replace the current gradient storage with the freshly computed new gradients.

Static Protected Member Functions
static std::string	gradientStateVectorName (const FVGradientMethod &method, unsigned int state, unsigned int component)
	Return the stable system-vector name for one old gradient component.

Protected Attributes
SystemBase &	_sys
	Reference to the system object.
std::unordered_map< const FVGradientMethod *, LinearFVGradientContainer >	_linear_fv_gradient_container_by_method
	Gradient containers keyed by the method object that produces them.

Detailed Description

Registration, update, and allocation logic for linear finite-volume cell gradients.

This interface should be inherited by system classes that may own linear finite-volume variables

Definition at line 38 of file LinearFVGradientManager.h.

Member Typedef Documentation

GradientContainer

using LinearFVGradientManager::GradientContainer = LinearFVGradientReader::GradientContainer

protected

Non-owning view with one vector per spatial component of a cell-centered gradient field.

Definition at line 65 of file LinearFVGradientManager.h.

GradientStateContainer

using LinearFVGradientManager::GradientStateContainer = LinearFVGradientReader::GradientStateContainer

protected

Gradient fields indexed by solution time state.

Definition at line 68 of file LinearFVGradientManager.h.

OwnedGradientContainer

using LinearFVGradientManager::OwnedGradientContainer = std::vector<std::unique_ptr<libMesh::NumericVector<libMesh::Number> >>

protected

Owned vectors used for the current gradient and its replacement.

Definition at line 71 of file LinearFVGradientManager.h.

Constructor & Destructor Documentation

LinearFVGradientManager()

LinearFVGradientManager::LinearFVGradientManager ( SystemBase &  sys )

inline

Parameters

sys	System that owns registered linear finite-volume gradient fields.

Definition at line 44 of file LinearFVGradientManager.h.

: _sys(sys) {}

Member Function Documentation

checkRestartedGradientHistory()

void LinearFVGradientManager::checkRestartedGradientHistory ( const FVGradientMethod &  method, LinearFVGradientContainer &  container  )

protected

Validate and mark gradient history loaded during restart or recovery.

Definition at line 237 of file LinearFVGradientManager.C.

{
  if (container.has_checked_restart_history)
    return;
 
  container.has_checked_restart_history = true;
  if (container.state_values.size() <= 1)
    return;
 
  const auto & app = _sys.feProblem().getMooseApp();
  if (!app.isRestarting() && !app.isRecovering())
    return;
 
  const auto & restartable_equation_systems = _sys.feProblem().getRestartableEquationSystems();
  for (const auto state : make_range(std::size_t(1), container.state_values.size()))
    for (const auto component : index_range(container.state_values[state]))
    {
      const auto vector_name = gradientStateVectorName(method, state, component);
      for (const auto variable_number : container.variable_numbers)
      {
        const auto & variable = _sys.getVariable(0, variable_number);
        if (!restartable_equation_systems.isVariableRestored(
                _sys.name(), vector_name, variable.name()))
          mooseError("Linear FV gradient state ",
                     state,
                     " for variable '",
                     variable.name(),
                     "' using gradient method '",
                     method.name(),
                     "' was requested on system '",
                     _sys.name(),
                     "', but vector '",
                     vector_name,
                     "' was not available in the restart data.");
      }
    }
 
  container.has_initialized_history = true;
}

Referenced by initializeLinearFVGradientStorage().

computeGradients()

void LinearFVGradientManager::computeGradients ( )

protected

Compute and finalize all registered linear FV gradient fields.

Definition at line 110 of file LinearFVGradientManager.C.

{
  if (_linear_fv_gradient_container_by_method.empty() || !_sys.solutionStatesInitialized())
    return;
 
  auto * const perf_graph_interface = dynamic_cast<PerfGraphInterface *>(&_sys);
  mooseAssert(perf_graph_interface,
              "LinearFVGradientManager requires its owning system to implement "
              "PerfGraphInterface.");
  const auto perf_id = perf_graph_interface->registerTimedSection("LinearVariableFV_Gradients", 3);
  mooseAssert(!Threads::in_threads, "PerfGraph timing cannot be used within threaded sections");
  PerfGuard time_guard(perf_graph_interface->perfGraph(), perf_id);
 
  // Keep current values unchanged until every replacement has been computed so boundary
  // conditions consistently use gradients from the previous update.
  // BCs may use cell gradients to compute the boundary face value, which is itself used to
  // compute cell gradients
  for (auto & method_container_pair : _linear_fv_gradient_container_by_method)
    computeLinearFVGradientContainer(*method_container_pair.first);
 
  for (auto & method_container_pair : _linear_fv_gradient_container_by_method)
    finalizeLinearFVGradientContainer(method_container_pair.second);
}

Referenced by AuxiliarySystem::compute().

computeLinearFVGradientContainer()

LinearFVGradientManager::LinearFVGradientContainer & LinearFVGradientManager::computeLinearFVGradientContainer ( const FVGradientMethod &  method )

protected

Compute replacement field values for a registered gradient method.

Parameters

method

Gradient method used to compute the replacement values.

Returns

Method container whose replacement values were computed.

Definition at line 279 of file LinearFVGradientManager.C.

{
  // Gradient requests can be registered before the current solution vector exists, so the current
  // and replacement fields cannot always be created when the request is recorded. These fields
  // must be zero clones of the solution vector to inherit its finalized layout and parallel type.
  // Requests can also arrive after the normal initialization phase. Initializing immediately
  // before computation handles both cases, while the empty checks make repeated calls harmless.
  initializeLinearFVGradientStorage();
 
  auto & container = libmesh_map_find(_linear_fv_gradient_container_by_method, &method);
 
  mooseAssert(!container.state_values.empty(),
              "Gradient state storage must contain a current state.");
  mooseAssert(!container.state_values[0].empty(),
              "Gradient storage must be initialized before gradient computation.");
  mooseAssert(!container.next_values.empty(),
              "Replacement gradient storage must be initialized before gradient computation.");
  mooseAssert(container.next_values.size() == container.current_values.size(),
              "Next and current gradient containers must have the same size.");
 
  method.computeGradient(_sys, container.next_values, container.variable_numbers);
 
  return container;
}

Referenced by computeGradients(), initializeGradientStatesForTimeAdvance(), and updateFVGradient().

copyPreviousGradientStates()

void LinearFVGradientManager::copyPreviousGradientStates ( Moose::SolutionIterationType  iteration_type, bool  skip_current_to_old  )

protected

Copy published gradient values into requested older states.

Non-time histories are ignored because only time gradient states are currently stored.

Parameters

iteration_type	Type of solution history being advanced.
skip_current_to_old	Whether state zero should not overwrite state one while deeper states still shift, matching the owning system's solution-state advancement.

Definition at line 364 of file LinearFVGradientManager.C.

{
  mooseAssert(iteration_type != Moose::SolutionIterationType::Nonlinear,
              "Linear FV gradient storage does not support nonlinear iteration states.");
  if (iteration_type != Moose::SolutionIterationType::Time)
    return;
 
  mooseAssert(!Threads::in_threads, "Linear FV gradient state copying is not thread-safe.");
  initializeGradientStatesForTimeAdvance();
 
  for (auto & [_, container] : _linear_fv_gradient_container_by_method)
  {
    const auto number_of_states = container.state_values.size();
    if (number_of_states <= 1)
      continue;
 
    mooseAssert(container.has_computed_gradient,
                "Current gradient state must be initialized before advancing time states.");
    // Mirror solution-state advancement: some restore workflows preserve state 1 by skipping the
    // current-to-old copy while still shifting every deeper state.
    const std::size_t stop = skip_current_to_old ? 1 : 0;
    for (std::size_t state = number_of_states - 1; state > stop; --state)
      copyGradient(container.state_values[state - 1], container.state_values[state]);
  }
}

Referenced by AuxiliarySystem::copyAdditionalStateBackwards(), and LinearSystem::copyAdditionalStateBackwards().

finalizeLinearFVGradientContainer()

void LinearFVGradientManager::finalizeLinearFVGradientContainer ( LinearFVGradientContainer &  container )

protected

Replace the current gradient storage with the freshly computed new gradients.

Parameters

container

Method container whose gradient values should be finalized.

Definition at line 305 of file LinearFVGradientManager.C.

{
  mooseAssert(!container.state_values.empty(),
              "Gradient state storage must contain a current state.");
  mooseAssert(container.next_values.size() == container.current_values.size(),
              "Next and current gradient containers must have the same size.");
  container.current_values.swap(container.next_values);
  setCurrentGradientState(container);
 
  if (!container.has_initialized_history)
  {
    for (const auto state : make_range(std::size_t(1), container.state_values.size()))
      copyGradient(container.state_values[0], container.state_values[state]);
    container.has_initialized_history = true;
  }
 
  container.has_computed_gradient = true;
}

Referenced by computeGradients(), initializeGradientStatesForTimeAdvance(), and updateFVGradient().

gradientStateVectorName()

std::string LinearFVGradientManager::gradientStateVectorName ( const FVGradientMethod &  method, unsigned int  state, unsigned int  component  )

staticprotected

Return the stable system-vector name for one old gradient component.

Definition at line 228 of file LinearFVGradientManager.C.

{
  return "linear_fv_gradient_" + method.name() + "_state_" + std::to_string(state) + "_component_" +
         std::to_string(component);
}

Referenced by checkRestartedGradientHistory(), and initializeLinearFVGradientHistoryStorage().

hasLinearFVGradients()

bool LinearFVGradientManager::hasLinearFVGradients ( ) const

protected

Whether any linear finite-volume gradient fields have been registered to this object.

Definition at line 165 of file LinearFVGradientManager.C.

{
  return !_linear_fv_gradient_container_by_method.empty();
}

Referenced by AuxiliarySystem::compute().

initializeContainer()

void LinearFVGradientManager::initializeContainer ( OwnedGradientContainer &  container ) const

protected

Allocate one zeroed vector per spatial component for gradient storage.

Parameters

container

Component-vector container to rebuild.

Definition at line 171 of file LinearFVGradientManager.C.

{
  container.clear();
  const auto & current_solution = _sys.system().current_local_solution;
  mooseAssert(current_solution && current_solution->initialized(),
              "Current solution must exist before building FV gradient storage.");
  container.resize(_sys.mesh().dimension());
  for (auto & component : container)
    component = current_solution->zero_clone();
}

Referenced by initializeLinearFVGradientStorage(), and AuxiliarySystem::updateFVGradient().

initializeGradientStatesForTimeAdvance()

void LinearFVGradientManager::initializeGradientStatesForTimeAdvance ( )

protected

Compute and publish uninitialized gradients before their first time-state advancement.

Definition at line 352 of file LinearFVGradientManager.C.

{
  for (auto & [method, container] : _linear_fv_gradient_container_by_method)
    if (container.state_values.size() > 1 && !container.has_computed_gradient)
      computeLinearFVGradientContainer(*method);
 
  for (auto & [_, container] : _linear_fv_gradient_container_by_method)
    if (container.state_values.size() > 1 && !container.has_computed_gradient)
      finalizeLinearFVGradientContainer(container);
}

Referenced by copyPreviousGradientStates().

initializeLinearFVGradientHistoryStorage()

void LinearFVGradientManager::initializeLinearFVGradientHistoryStorage ( )

protected

Register named system vectors for requested historical gradient states.

This must run after gradient state requirements are known and before restart or recovery data is loaded, so checkpoint data can be restored into these vectors. It does not initialize the current or replacement working storage.

Definition at line 201 of file LinearFVGradientManager.C.

{
  for (auto & [method, container] : _linear_fv_gradient_container_by_method)
    for (const auto state : make_range(std::size_t(1), container.state_values.size()))
      if (container.state_values[state].empty())
      {
        GradientContainer state_values(_sys.mesh().dimension());
        for (const auto component : index_range(state_values))
          state_values[component] = &_sys.addVector(
              gradientStateVectorName(*method, state, component), true, libMesh::GHOSTED);
        container.state_values[state] = std::move(state_values);
      }
}

Referenced by AuxiliarySystem::AuxiliarySystem(), and LinearSystem::initSolutionState().

initializeLinearFVGradientStorage()

void LinearFVGradientManager::initializeLinearFVGradientStorage ( )

protected

Initialize private current and replacement gradient storage.

This must run after the current local solution has been created and initialized, and after restart or recovery data has been loaded. At that point, it also checks if the restored historical gradient storage is set up correctly.

Definition at line 325 of file LinearFVGradientManager.C.

{
  for (auto & [method, container] : _linear_fv_gradient_container_by_method)
  {
    if (container.current_values.empty())
      initializeContainer(container.current_values);
    if (container.next_values.empty())
      initializeContainer(container.next_values);
    setCurrentGradientState(container);
    checkRestartedGradientHistory(*method, container);
  }
}

Referenced by computeLinearFVGradientContainer(), AuxiliarySystem::initialSetup(), LinearSystem::initialSetup(), and rebuildLinearFVGradientStorage().

rebuildLinearFVGradientStorage()

void LinearFVGradientManager::rebuildLinearFVGradientStorage ( )

protected

Rebuild cached gradient values and reusable scratch storage after mesh/DOF changes.

Definition at line 339 of file LinearFVGradientManager.C.

{
  for (auto & method_container_pair : _linear_fv_gradient_container_by_method)
  {
    method_container_pair.second.current_values.clear();
    method_container_pair.second.next_values.clear();
    method_container_pair.second.has_computed_gradient = false;
  }
 
  initializeLinearFVGradientStorage();
}

Referenced by AuxiliarySystem::reinit(), and LinearSystem::reinit().

registerFVGradient()

LinearFVGradientReader LinearFVGradientManager::registerFVGradient	(	unsigned int	variable_number,
		const FVGradientMethod &	method,
		unsigned int	oldest_state = 0
	)

Register a variable for gradient values produced by a method object.

Parameters

variable_number	Variable number whose gradient should be stored.
method	Gradient method that computes the field values.
oldest_state	Oldest time state that consumers need to read.

Definition at line 78 of file LinearFVGradientManager.C.

{
  auto * const variable =
      dynamic_cast<MooseVariableFieldBase *>(_sys.variableWarehouse().getVariable(variable_number));
  if (!variable)
    mooseError("Linear FV gradients were requested for variable number ",
               variable_number,
               " on system '",
               _sys.name(),
               "', but no field variable with that number exists on the system.");
 
  auto & container = _linear_fv_gradient_container_by_method[&method];
  container.variable_numbers.insert(variable_number);
 
  resizeGradientStateStorage(container, oldest_state);
 
  const auto & current_solution = _sys.system().current_local_solution;
  if (current_solution && current_solution->initialized())
  {
    if (container.current_values.empty())
      initializeContainer(container.current_values);
    if (container.next_values.empty())
      initializeContainer(container.next_values);
    setCurrentGradientState(container);
  }
 
  return LinearFVGradientReader(_sys, container.state_values, method, variable_number);
}

resizeGradientStateStorage()

void LinearFVGradientManager::resizeGradientStateStorage ( LinearFVGradientContainer &  container, unsigned int  oldest_state  )

protected

Ensure that a method container stores every requested time state.

Parameters

container	Method container whose state storage should be grown.
oldest_state	Oldest time state that must be stored.

Definition at line 183 of file LinearFVGradientManager.C.

{
  const auto required_states = static_cast<std::size_t>(oldest_state) + 1;
  const auto old_size = container.state_values.size();
  if (required_states > old_size && _sys.solutionStatesInitialized() && oldest_state > 0)
    mooseError("Linear FV gradient state ",
               oldest_state,
               " was requested on system '",
               _sys.name(),
               "' after solution states were initialized. Old gradient states must be requested "
               "during setup.");
 
  if (required_states > old_size)
    container.state_values.resize(required_states);
}

Referenced by AuxiliarySystem::updateFVGradient().

resolveFVGradientMethod()

const FVGradientMethod & LinearFVGradientManager::resolveFVGradientMethod

(

const GradientMethodName &

method_name

)

Resolve a named gradient method, constructing a built-in method when needed.

Parameters

method_name

Name of the gradient method to retrieve.

Returns

Gradient method associated with the supplied name.

Definition at line 52 of file LinearFVGradientManager.C.

{
  auto & fe_problem = _sys.feProblem();
 
  if (!fe_problem.hasFVGradientMethod(method_name))
  {
    if (method_name == "green-gauss")
    {
      auto params = fe_problem.getMooseApp().getFactory().getValidParams("FVGreenGaussGradient");
      fe_problem.addFVGradientMethod("FVGreenGaussGradient", method_name, params);
    }
    else if (method_name == "green-gauss-venkatakrishnan")
    {
      auto params = fe_problem.getMooseApp().getFactory().getValidParams("FVGreenGaussGradient");
      params.set<MooseEnum>("limiter") = "venkatakrishnan";
      fe_problem.addFVGradientMethod("FVGreenGaussGradient", method_name, params);
    }
  }
 
  if (!fe_problem.hasFVGradientMethod(method_name))
    mooseError("Unable to find FVGradientMethod with name '", method_name, "'");
 
  return fe_problem.getFVGradientMethod(method_name);
}

restoreGradientStates()

void LinearFVGradientManager::restoreGradientStates ( )

protected

Restore current gradients from state one after a failed timestep.

Definition at line 392 of file LinearFVGradientManager.C.

{
  mooseAssert(!Threads::in_threads, "Linear FV gradient state copying is not thread-safe.");
  for (auto & [_, container] : _linear_fv_gradient_container_by_method)
  {
    if (container.state_values.size() <= 1)
      continue;
 
    mooseAssert(container.has_computed_gradient,
                "Current gradient state must be initialized before restoration.");
    copyGradient(container.state_values[1], container.state_values[0]);
    copyGradient(container.state_values[0], container.next_values);
  }
}

Referenced by AuxiliarySystem::restoreAdditionalStates(), and LinearSystem::restoreAdditionalStates().

setCurrentGradientState()

void LinearFVGradientManager::setCurrentGradientState ( LinearFVGradientContainer &  container ) const

protected

Set solution state zero to the current gradient.

Definition at line 216 of file LinearFVGradientManager.C.

{
  mooseAssert(!container.state_values.empty(),
              "Gradient state storage must contain a current state.");
  auto & current_view = container.state_values[0];
  current_view.clear();
  current_view.reserve(container.current_values.size());
  for (auto & component : container.current_values)
    current_view.push_back(component.get());
}

Referenced by finalizeLinearFVGradientContainer(), initializeLinearFVGradientStorage(), and AuxiliarySystem::updateFVGradient().

updateFVGradient()

void LinearFVGradientManager::updateFVGradient ( const LinearFVGradientReader &  reader )

protected

Update a registered gradient reader explicitly.

Parameters

reader

Gradient reader to update.

Definition at line 135 of file LinearFVGradientManager.C.

{
  if (&reader.system() != &_sys)
    mooseError("Requested update for a linear FV gradient field from a different system than '",
               _sys.name(),
               "'.");
 
  const auto method_container_pair = _linear_fv_gradient_container_by_method.find(&reader.method());
  if (method_container_pair != _linear_fv_gradient_container_by_method.end())
  {
    auto * const perf_graph_interface = dynamic_cast<PerfGraphInterface *>(&_sys);
    mooseAssert(perf_graph_interface,
                "LinearFVGradientManager requires its owning system to implement "
                "PerfGraphInterface.");
    const auto perf_id =
        perf_graph_interface->registerTimedSection("LinearVariableFV_Gradients", 3);
    mooseAssert(!Threads::in_threads, "PerfGraph timing cannot be used within threaded sections");
    PerfGuard time_guard(perf_graph_interface->perfGraph(), perf_id);
 
    auto & container = computeLinearFVGradientContainer(reader.method());
    finalizeLinearFVGradientContainer(container);
    return;
  }
 
  mooseError("Requested update for an unregistered linear FV gradient field on system '",
             _sys.name(),
             "'.");
}

Member Data Documentation

_linear_fv_gradient_container_by_method

std::unordered_map<const FVGradientMethod *, LinearFVGradientContainer> LinearFVGradientManager::_linear_fv_gradient_container_by_method

protected

Gradient containers keyed by the method object that produces them.

Definition at line 197 of file LinearFVGradientManager.h.

Referenced by computeGradients(), computeLinearFVGradientContainer(), copyPreviousGradientStates(), hasLinearFVGradients(), initializeGradientStatesForTimeAdvance(), initializeLinearFVGradientHistoryStorage(), initializeLinearFVGradientStorage(), rebuildLinearFVGradientStorage(), restoreGradientStates(), AuxiliarySystem::updateFVGradient(), and updateFVGradient().

_sys

SystemBase& LinearFVGradientManager::_sys

protected

Reference to the system object.

Definition at line 193 of file LinearFVGradientManager.h.

Referenced by checkRestartedGradientHistory(), computeGradients(), computeLinearFVGradientContainer(), initializeContainer(), initializeLinearFVGradientHistoryStorage(), resizeGradientStateStorage(), resolveFVGradientMethod(), AuxiliarySystem::updateFVGradient(), and updateFVGradient().

---

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

• include/systems/LinearFVGradientManager.h
• src/systems/LinearFVGradientManager.C