Kokkos BCs System

Before reading this documentation, consider reading the following materials first for a better understanding of this documentation:

BCs System to understand the MOOSE boundary condition system,
Getting Started with Kokkos-MOOSE to understand the programming practices for Kokkos-MOOSE,
Kokkos Kernels System to understand the common design pattern of objects in Kokkos-MOOSE.

note

Kokkos-MOOSE boundary conditions do not support automatic differention yet.

The basic design pattern of Kokkos-MOOSE kernels described in Kokkos Kernels System applies to the boundary conditions as well. You can create your own integrated and nodal boundary conditions by subclassing Moose::Kokkos::IntegratedBC and Moose::Kokkos::NodalBC, respectively, and following the same pattern with kernels including registering your boundary conditions with registerKokkosResidualObject(). Especially, integrated boundary conditions have identical interfaces with kernels, so they will not be explained here in detail. See the following source codes of KokkosCoupledVarNeumannBC for an example of an integrated boundary condition:

Listing 1: The KokkosCoupledVarNeumannBC header file.


#pragma once

#include "KokkosIntegratedBC.h"

/**
 * Implements a Neumann BC where grad(u)=_coupled_var on the boundary.
 * Uses the term produced from integrating the diffusion operator by parts.
 */
class KokkosCoupledVarNeumannBC : public Moose::Kokkos::IntegratedBC
{
public:
  static InputParameters validParams();

  KokkosCoupledVarNeumannBC(const InputParameters & parameters);

  KOKKOS_FUNCTION Real computeQpResidual(const unsigned int i,
                                         const unsigned int qp,
                                         ResidualDatum & datum) const;
  KOKKOS_FUNCTION Real computeQpOffDiagJacobian(const unsigned int i,
                                                const unsigned int j,
                                                const unsigned int jvar,
                                                const unsigned int qp,
                                                ResidualDatum & datum) const;

protected:
  /// Variable providing the value of grad(u) on the boundary.
  const Moose::Kokkos::VariableValue _coupled_var;

  /// The identifying number of the coupled variable
  const unsigned int _coupled_num;

  /// A coefficient that is multiplied with the residual contribution
  const Real _coef;

  /// Scale factor
  const Moose::Kokkos::VariableValue _scale_factor;
};

KOKKOS_FUNCTION inline Real
KokkosCoupledVarNeumannBC::computeQpResidual(const unsigned int i,
                                             const unsigned int qp,
                                             ResidualDatum & datum) const
{
  return -_scale_factor(datum, qp) * _coef * _test(datum, i, qp) * _coupled_var(datum, qp);
}

KOKKOS_FUNCTION inline Real
KokkosCoupledVarNeumannBC::computeQpOffDiagJacobian(const unsigned int i,
                                                    const unsigned int j,
                                                    const unsigned int jvar,
                                                    const unsigned int qp,
                                                    ResidualDatum & datum) const
{
  if (jvar == _coupled_num)
    return -_scale_factor(datum, qp) * _coef * _test(datum, i, qp) * _phi(datum, j, qp);
  else
    return 0;
}

Listing 2: The KokkosCoupledVarNeumannBC source file.


#include "KokkosCoupledVarNeumannBC.h"

registerKokkosResidualObject("MooseApp", KokkosCoupledVarNeumannBC);

InputParameters
KokkosCoupledVarNeumannBC::validParams()
{
  InputParameters params = IntegratedBC::validParams();
  params.addRequiredCoupledVar("v", "Coupled variable setting the gradient on the boundary.");
  params.addCoupledVar("scale_factor", 1., "Scale factor to multiply the heat flux with");
  params.addParam<Real>(
      "coef", 1.0, "Coefficent ($\\sigma$) multiplier for the coupled force term.");
  params.addClassDescription("Imposes the integrated boundary condition "
                             "$\\frac{\\partial u}{\\partial n}=v$, "
                             "where $v$ is a variable.");
  return params;
}
KokkosCoupledVarNeumannBC::KokkosCoupledVarNeumannBC(const InputParameters & parameters)
  : IntegratedBC(parameters),
    _coupled_var(kokkosCoupledValue("v")),
    _coupled_num(coupled("v")),
    _coef(getParam<Real>("coef")),
    _scale_factor(kokkosCoupledValue("scale_factor"))
{
}

On the other hand, nodal boundary conditions have slightly different interfaces. The hook methods for a nodal boundary condition have the following signatures:


KOKKOS_FUNCTION Real computeQpResidual(const unsigned int qp, ResidualDatum & datum) const;
KOKKOS_FUNCTION Real computeQpJacobian(const unsigned int qp, ResidualDatum & datum) const;
KOKKOS_FUNCTION Real computeQpOffDiagJacobian(const unsigned int jvar,
                                              const unsigned int qp,
                                              ResidualDatum & datum) const;

The test and trial function indices, i and j, are no longer passed as arguments. qp corresponds to the dummy _qp index in the original MOOSE and is always zero. To keep the consistency between interfaces, however, it is still passed as an argument and used for getting solution values. _current_node, which is a pointer to the current libMesh node object, does not have a direct replacement. Instead, the node index can be queried by datum.node() and used to retrieve mesh data from the Kokkos mesh object. The node coordinate can also be obtained by datum.q_point(qp). As a result, the following residual function in DirichletBCBase:


Real
DirichletBCBase::computeQpResidual()
{
  return _u[_qp] - computeQpValue();
}

becomes the following in Moose::Kokkos::DirichletBCBase:


template <typename Derived>
KOKKOS_FUNCTION Real
DirichletBCBase<Derived>::computeQpResidual(const unsigned int qp, ResidualDatum & datum) const
{
  auto bc = static_cast<const Derived *>(this);

  return _u(datum, qp) - bc->computeValue(qp, datum);
}

Also note here the static implementation of computeValue using the Curiously Recurring Template Pattern (CRTP) which is originally a virtual function.

See the following source codes of KokkosMatchedValueBC for another example of a nodal boundary condition:

Listing 3: The KokkosMatchedValueBC header file.


#pragma once

#include "KokkosNodalBC.h"

/**
 * Implements a simple coupled boundary condition where u=v on the boundary.
 */
class KokkosMatchedValueBC : public Moose::Kokkos::NodalBC
{
public:
  static InputParameters validParams();

  KokkosMatchedValueBC(const InputParameters & parameters);

  KOKKOS_FUNCTION Real computeQpResidual(const unsigned int qp, ResidualDatum & datum) const;
  KOKKOS_FUNCTION Real computeQpOffDiagJacobian(const unsigned int jvar,
                                                const unsigned int qp,
                                                ResidualDatum & datum) const;

protected:
  const Moose::Kokkos::VariableValue _v;

  /// The id of the coupled variable
  const unsigned int _v_num;
  /// Coefficient for primary variable
  const Real _u_coeff;
  /// Coefficient for coupled variable
  const Real _v_coeff;
};

KOKKOS_FUNCTION inline Real
KokkosMatchedValueBC::computeQpResidual(const unsigned int qp, ResidualDatum & datum) const
{
  return _u_coeff * _u(datum, qp) - _v_coeff * _v(datum, qp);
}

KOKKOS_FUNCTION inline Real
KokkosMatchedValueBC::computeQpOffDiagJacobian(const unsigned int jvar,
                                               const unsigned int /* qp */,
                                               ResidualDatum & /* datum */) const
{
  if (jvar == _v_num)
    return -_v_coeff;
  else
    return 0;
}

Listing 4: The KokkosMatchedValueBC source file.


#include "KokkosMatchedValueBC.h"

registerKokkosResidualObject("MooseApp", KokkosMatchedValueBC);

InputParameters
KokkosMatchedValueBC::validParams()
{
  InputParameters params = NodalBC::validParams();
  params.addRequiredCoupledVar("v", "The variable whose value we are to match.");
  params.addParam<Real>("u_coeff", 1.0, " A coefficient for primary variable u");
  params.addParam<Real>("v_coeff", 1.0, " A coefficient for coupled variable v");
  params.addClassDescription("Implements a NodalBC which equates two different Variables' values "
                             "on a specified boundary.");
  return params;
}

KokkosMatchedValueBC::KokkosMatchedValueBC(const InputParameters & parameters)
  : NodalBC(parameters),
    _v(kokkosCoupledNodalValue("v")),
    _v_num(coupled("v")),
    _u_coeff(getParam<Real>("u_coeff")),
    _v_coeff(getParam<Real>("v_coeff"))
{
}

Available Objects

Moose App
KokkosCoupledVarNeumannBCImposes the integrated boundary condition $var element = document.getElementById("moose-equation-8e876272-666a-488f-bcc6-54fbfbea5ca1");katex.render("\\frac{\\partial u}{\\partial n}=v", element, {displayMode:false,throwOnError:false,macros:{"\\eqc":"\\,,","\\eqp":"\\,.","\\pd":"\\frac{\\partial #1}{\\partial #2}","\\pr":"\\left(#1\\right)","\\ddt":"\\frac{d #1}{d t}"}});$ , where $var element = document.getElementById("moose-equation-101510b0-bfb3-4574-a73a-da06400c2c07");katex.render("v", element, {displayMode:false,throwOnError:false,macros:{"\\eqc":"\\,,","\\eqp":"\\,.","\\pd":"\\frac{\\partial #1}{\\partial #2}","\\pr":"\\left(#1\\right)","\\ddt":"\\frac{d #1}{d t}"}});$ is a variable.
KokkosDirichletBCImposes the essential boundary condition $var element = document.getElementById("moose-equation-22a02aed-1c9d-4b0a-a4b9-d07517e9256a");katex.render("u=g", element, {displayMode:false,throwOnError:false,macros:{"\\eqc":"\\,,","\\eqp":"\\,.","\\pd":"\\frac{\\partial #1}{\\partial #2}","\\pr":"\\left(#1\\right)","\\ddt":"\\frac{d #1}{d t}"}});$ , where $var element = document.getElementById("moose-equation-d008dbab-59f8-4939-8d42-d6f2358e1155");katex.render("g", element, {displayMode:false,throwOnError:false,macros:{"\\eqc":"\\,,","\\eqp":"\\,.","\\pd":"\\frac{\\partial #1}{\\partial #2}","\\pr":"\\left(#1\\right)","\\ddt":"\\frac{d #1}{d t}"}});$ is a constant, controllable value.
KokkosMatchedValueBCImplements a NodalBC which equates two different Variables' values on a specified boundary.
KokkosNeumannBCImposes the integrated boundary condition $var element = document.getElementById("moose-equation-a0a8cc7e-e476-44f0-9cc8-4154d7c5f110");katex.render("\\frac{\\partial u}{\\partial n}=h", element, {displayMode:false,throwOnError:false,macros:{"\\eqc":"\\,,","\\eqp":"\\,.","\\pd":"\\frac{\\partial #1}{\\partial #2}","\\pr":"\\left(#1\\right)","\\ddt":"\\frac{d #1}{d t}"}});$ , where $var element = document.getElementById("moose-equation-4c2cc75b-7b87-4082-89cb-25f441149ea7");katex.render("h", element, {displayMode:false,throwOnError:false,macros:{"\\eqc":"\\,,","\\eqp":"\\,.","\\pd":"\\frac{\\partial #1}{\\partial #2}","\\pr":"\\left(#1\\right)","\\ddt":"\\frac{d #1}{d t}"}});$ is a constant, controllable value.
KokkosPostprocessorNeumannBCNeumann boundary condition with value prescribed by a Postprocessor value.
KokkosVacuumBCVacuum boundary condition for diffusion.
Heat Transfer App
KokkosConvectiveHeatFluxBCConvective heat transfer boundary condition with temperature and heat transfer coefficent given by material properties.
KokkosCoupledConvectiveHeatFluxBCConvective heat transfer boundary condition with temperature and heat transfer coefficent given by auxiliary variables.
Thermal Hydraulics App
KokkosRadiativeHeatFluxBCRadiative heat transfer boundary condition for a plate heat structure

(framework/include/kokkos/bcs/KokkosCoupledVarNeumannBC.h)

// This file is part of the MOOSE framework
// https://mooseframework.inl.gov
//
// All rights reserved, see COPYRIGHT for full restrictions
// https://github.com/idaholab/moose/blob/master/COPYRIGHT
//
// Licensed under LGPL 2.1, please see LICENSE for details
// https://www.gnu.org/licenses/lgpl-2.1.html

#pragma once

#include "KokkosIntegratedBC.h"

/**
 * Implements a Neumann BC where grad(u)=_coupled_var on the boundary.
 * Uses the term produced from integrating the diffusion operator by parts.
 */
class KokkosCoupledVarNeumannBC : public Moose::Kokkos::IntegratedBC
{
public:
  static InputParameters validParams();

  KokkosCoupledVarNeumannBC(const InputParameters & parameters);

  KOKKOS_FUNCTION Real computeQpResidual(const unsigned int i,
                                         const unsigned int qp,
                                         ResidualDatum & datum) const;
  KOKKOS_FUNCTION Real computeQpOffDiagJacobian(const unsigned int i,
                                                const unsigned int j,
                                                const unsigned int jvar,
                                                const unsigned int qp,
                                                ResidualDatum & datum) const;

protected:
  /// Variable providing the value of grad(u) on the boundary.
  const Moose::Kokkos::VariableValue _coupled_var;

  /// The identifying number of the coupled variable
  const unsigned int _coupled_num;

  /// A coefficient that is multiplied with the residual contribution
  const Real _coef;

  /// Scale factor
  const Moose::Kokkos::VariableValue _scale_factor;
};

KOKKOS_FUNCTION inline Real
KokkosCoupledVarNeumannBC::computeQpResidual(const unsigned int i,
                                             const unsigned int qp,
                                             ResidualDatum & datum) const
{
  return -_scale_factor(datum, qp) * _coef * _test(datum, i, qp) * _coupled_var(datum, qp);
}

KOKKOS_FUNCTION inline Real
KokkosCoupledVarNeumannBC::computeQpOffDiagJacobian(const unsigned int i,
                                                    const unsigned int j,
                                                    const unsigned int jvar,
                                                    const unsigned int qp,
                                                    ResidualDatum & datum) const
{
  if (jvar == _coupled_num)
    return -_scale_factor(datum, qp) * _coef * _test(datum, i, qp) * _phi(datum, j, qp);
  else
    return 0;
}

(framework/src/kokkos/bcs/KokkosCoupledVarNeumannBC.K)

// This file is part of the MOOSE framework
// https://mooseframework.inl.gov
//
// All rights reserved, see COPYRIGHT for full restrictions
// https://github.com/idaholab/moose/blob/master/COPYRIGHT
//
// Licensed under LGPL 2.1, please see LICENSE for details
// https://www.gnu.org/licenses/lgpl-2.1.html

#include "KokkosCoupledVarNeumannBC.h"

registerKokkosResidualObject("MooseApp", KokkosCoupledVarNeumannBC);

InputParameters
KokkosCoupledVarNeumannBC::validParams()
{
  InputParameters params = IntegratedBC::validParams();
  params.addRequiredCoupledVar("v", "Coupled variable setting the gradient on the boundary.");
  params.addCoupledVar("scale_factor", 1., "Scale factor to multiply the heat flux with");
  params.addParam<Real>(
      "coef", 1.0, "Coefficent ($\\sigma$) multiplier for the coupled force term.");
  params.addClassDescription("Imposes the integrated boundary condition "
                             "$\\frac{\\partial u}{\\partial n}=v$, "
                             "where $v$ is a variable.");
  return params;
}
KokkosCoupledVarNeumannBC::KokkosCoupledVarNeumannBC(const InputParameters & parameters)
  : IntegratedBC(parameters),
    _coupled_var(kokkosCoupledValue("v")),
    _coupled_num(coupled("v")),
    _coef(getParam<Real>("coef")),
    _scale_factor(kokkosCoupledValue("scale_factor"))
{
}

(framework/include/kokkos/bcs/KokkosMatchedValueBC.h)

// This file is part of the MOOSE framework
// https://mooseframework.inl.gov
//
// All rights reserved, see COPYRIGHT for full restrictions
// https://github.com/idaholab/moose/blob/master/COPYRIGHT
//
// Licensed under LGPL 2.1, please see LICENSE for details
// https://www.gnu.org/licenses/lgpl-2.1.html

#pragma once

#include "KokkosNodalBC.h"

/**
 * Implements a simple coupled boundary condition where u=v on the boundary.
 */
class KokkosMatchedValueBC : public Moose::Kokkos::NodalBC
{
public:
  static InputParameters validParams();

  KokkosMatchedValueBC(const InputParameters & parameters);

  KOKKOS_FUNCTION Real computeQpResidual(const unsigned int qp, ResidualDatum & datum) const;
  KOKKOS_FUNCTION Real computeQpOffDiagJacobian(const unsigned int jvar,
                                                const unsigned int qp,
                                                ResidualDatum & datum) const;

protected:
  const Moose::Kokkos::VariableValue _v;

  /// The id of the coupled variable
  const unsigned int _v_num;
  /// Coefficient for primary variable
  const Real _u_coeff;
  /// Coefficient for coupled variable
  const Real _v_coeff;
};

KOKKOS_FUNCTION inline Real
KokkosMatchedValueBC::computeQpResidual(const unsigned int qp, ResidualDatum & datum) const
{
  return _u_coeff * _u(datum, qp) - _v_coeff * _v(datum, qp);
}

KOKKOS_FUNCTION inline Real
KokkosMatchedValueBC::computeQpOffDiagJacobian(const unsigned int jvar,
                                               const unsigned int /* qp */,
                                               ResidualDatum & /* datum */) const
{
  if (jvar == _v_num)
    return -_v_coeff;
  else
    return 0;
}

(framework/src/kokkos/bcs/KokkosMatchedValueBC.K)

// This file is part of the MOOSE framework
// https://mooseframework.inl.gov
//
// All rights reserved, see COPYRIGHT for full restrictions
// https://github.com/idaholab/moose/blob/master/COPYRIGHT
//
// Licensed under LGPL 2.1, please see LICENSE for details
// https://www.gnu.org/licenses/lgpl-2.1.html

#include "KokkosMatchedValueBC.h"

registerKokkosResidualObject("MooseApp", KokkosMatchedValueBC);

InputParameters
KokkosMatchedValueBC::validParams()
{
  InputParameters params = NodalBC::validParams();
  params.addRequiredCoupledVar("v", "The variable whose value we are to match.");
  params.addParam<Real>("u_coeff", 1.0, " A coefficient for primary variable u");
  params.addParam<Real>("v_coeff", 1.0, " A coefficient for coupled variable v");
  params.addClassDescription("Implements a NodalBC which equates two different Variables' values "
                             "on a specified boundary.");
  return params;
}

KokkosMatchedValueBC::KokkosMatchedValueBC(const InputParameters & parameters)
  : NodalBC(parameters),
    _v(kokkosCoupledNodalValue("v")),
    _v_num(coupled("v")),
    _u_coeff(getParam<Real>("u_coeff")),
    _v_coeff(getParam<Real>("v_coeff"))
{
}

Available Objects