finlized refactoring, updated documentation.

close idaholab#14680

framework/doc/content/source/auxkernels/InterfaceValueUserObjectAux.md

@@ -11,7 +11,7 @@ It requires three inputs:
 * `boundary` = the name of the boundary to which this AuxKernel applies
 * `interface_uo_name` = the name of interface UserObject where data are stored
 
-The optional argument `return_side_average` retrieve element side average values from the specified UserObject. 
+The optional argument `return_side_average` retrieves element side average values from the specified UserObject. 
 
 ## Example Input File Syntax
 

framework/doc/content/source/userobject/InterfaceQpMaterialPropertyRealUO.md

@@ -0,0 +1,33 @@
+# InterfaceQpMaterialPropertyRealUO
+
+## IMPORTANT NOTES
+*** This userobejct only support multiprocessing. Threading is not supported at this time  ***
+
+
+## Description
+!syntax description /UserObjects/InterfaceQpMaterialPropertyRealUO
+
+InterfaceQpMaterialPropertyRealUO is a user object computing and storing average `real` material property values, rates, or increments across an interface for each quadrature point. The kind of average value are the one available in [InterfaceValueTools](/InterfaceValueTools.md).
+The user object only stores one type of value. For example to get both the material property value and material property rate the user must add two separate user objects in the input file.
+
+The InterfaceQpMaterialPropertyRealUO can provide two types of values to other MOOSE systems:
+
+* a qp value by calling `getQpValue`
+* an element side average value by calling `getSideAverageValue`
+
+The stored value can be converted into an AuxVariable by using [InterfaceValueUserObjectAux](/InterfaceValueUserObjectAux.md) AuxKernel.
+
+
+## Example Input File Syntax
+
+listing test/tests/userobjects/interface_user_object/interface_mp_real_user_object_QP.i block=UserObjects/interface_value_uo
+listing test/tests/userobjects/interface_user_object/interface_mp_real_user_object_QP.i block=UserObjects/interface_value_rate_uo
+listing test/tests/userobjects/interface_user_object/interface_mp_real_user_object_QP.i block=UserObjects/interface_value_increment_uo
+
+!syntax description /UserObjects/InterfaceQpMaterialPropertyRealUO
+
+!syntax parameters /UserObjects/InterfaceQpMaterialPropertyRealUO
+
+!syntax inputs /UserObjects/InterfaceQpMaterialPropertyRealUO
+
+!syntax children /UserObjects/InterfaceQpMaterialPropertyRealUO

framework/doc/content/source/userobject/InterfaceQpValueUserObject.md

@@ -8,7 +8,7 @@
 !syntax description /UserObjects/InterfaceQpValueUserObject
 
 InterfaceQpValueUserObject is a user object computing and storing average variable values or rates across an interface for each quadrature. The kind of average value are the one available in [InterfaceValueTools](/InterfaceValueTools.md).
-The rate is computed if `compute_rate=true` is set in the input file. Note that this choice is exclusive, to get both the interface value and interface value rate the user must add two separate user objects in the input file.
+The user object only stores one type of value. For example to get both the variable value and variable rate the user must add two separate user objects in the input file.
 
 The InterfaceQpValueUserObject can provide two types of values to other MOOSE systems:
 
@@ -22,6 +22,10 @@ The stored value can be converted into an AuxVariable by using [InterfaceValueUs
 
 listing test/tests/userobjects/interface_user_object/interface_value_user_object_QP.i block=UserObjects/interface_value_uo
 
+listing test/tests/userobjects/interface_user_object/interface_value_rate_increment_user_object_QP.i block=UserObjects/interface_avg_value_rate_uo
+
+listing test/tests/userobjects/interface_user_object/interface_value_rate_increment_user_object_QP.i block=UserObjects/interface_avg_value_increment_uo
+
 !syntax description /UserObjects/InterfaceQpValueUserObject
 
 !syntax parameters /UserObjects/InterfaceQpValueUserObject

framework/include/userobject/InterfaceQpMaterialPropertyBaseUserObject.h

@@ -19,9 +19,8 @@ template <>
 InputParameters validParams<InterfaceQpMaterialPropertyBaseUserObject<>>();
 
 /**
- * This userobject collect values of a variable across an interface for each QP and compute a
- * scalar. The computed scalar value depends on the given parameter _interface_value_type\
- * _interface_value_type (see IntervafeValueTools).
+ * Specialization of InterfaceQpUserObjectBase for material properties. Material property type
+ * specialization is achieved by specializing computeScalarMaterialProperty in derived classes.
  */
 template <typename T>
 class InterfaceQpMaterialPropertyBaseUserObject : public InterfaceQpUserObjectBase
@@ -37,12 +36,47 @@ class InterfaceQpMaterialPropertyBaseUserObject : public InterfaceQpUserObjectBa
   virtual ~InterfaceQpMaterialPropertyBaseUserObject(){};
 
 protected:
-  virtual Real computeRealValueMaster(const unsigned int /*qp*/) override = 0;
-  virtual Real computeRealValueSlave(const unsigned int /*qp*/) override = 0;
+  /* method computing the real value*/
+  virtual Real computeRealValue(const unsigned int qp) override final
+  {
+    if (!_compute_rate && !_compute_increment)
+    {
+      return computeInterfaceValueType(computeScalarMaterialProperty(&_prop, qp),
+                                       computeScalarMaterialProperty(&_prop_neighbor, qp));
+    }
+    else
+    {
+
+      Real value_master = 0;
+      Real value_slave = 0;
+      if (_dt != 0)
+      {
+
+        value_master = (computeScalarMaterialProperty(&_prop, qp) -
+                        computeScalarMaterialProperty(_prop_old, qp));
+        value_slave = (computeScalarMaterialProperty(&_prop_neighbor, qp) -
+                       computeScalarMaterialProperty(_prop_neighbor_old, qp));
+        if (_compute_rate)
+        {
+          value_master /= _dt;
+          value_slave /= _dt;
+        }
+      }
+      return computeInterfaceValueType(value_master, value_slave);
+    }
+  };
+
+  /*template for computing a scalar material property value*/
+  virtual Real computeScalarMaterialProperty(const MaterialProperty<T> *,
+                                             const unsigned int qp) = 0;
+
+  /// the material property and neighbor material property current and old value
+  ///@{
   const MaterialProperty<T> & _prop;
   const MaterialProperty<T> & _prop_neighbor;
   const MaterialProperty<T> * _prop_old;
   const MaterialProperty<T> * _prop_neighbor_old;
+  ///@}
 };
 
 template <typename T>
@@ -67,8 +101,9 @@ InterfaceQpMaterialPropertyBaseUserObject<T>::InterfaceQpMaterialPropertyBaseUse
     _prop_neighbor(parameters.isParamSetByUser("property_neighbor")
                        ? getNeighborMaterialProperty<T>("property_neighbor")
                        : getNeighborMaterialProperty<T>("property")),
-    _prop_old(_compute_rate ? &getMaterialPropertyOld<T>("property") : nullptr),
-    _prop_neighbor_old(_compute_rate
+    _prop_old(_compute_rate || _compute_increment ? &getMaterialPropertyOld<T>("property")
+                                                  : nullptr),
+    _prop_neighbor_old(_compute_rate || _compute_increment
                            ? (parameters.isParamSetByUser("property_neighbor")
                                   ? &getNeighborMaterialPropertyOld<T>("property_neighbor")
                                   : &getNeighborMaterialPropertyOld<T>("property"))

framework/include/userobject/InterfaceQpMaterialPropertyRealUO.h

@@ -18,8 +18,7 @@ template <>
 InputParameters validParams<InterfaceQpMaterialPropertyRealUO>();
 
 /**
- * This userobject works on Real material properties. It returns the interface value (see
- * IntervafeValueTools) or its rate.
+ * Specialization of InterfaceQpMaterialPropertyBaseUserObject for Real material properties.
  */
 class InterfaceQpMaterialPropertyRealUO : public InterfaceQpMaterialPropertyBaseUserObject<Real>
 {
@@ -34,6 +33,10 @@ class InterfaceQpMaterialPropertyRealUO : public InterfaceQpMaterialPropertyBase
   virtual ~InterfaceQpMaterialPropertyRealUO(){};
 
 protected:
-  virtual Real computeRealValueMaster(const unsigned int /*qp*/) override;
-  virtual Real computeRealValueSlave(const unsigned int /*qp*/) override;
+  /// return the material property value at the give qp
+  virtual Real computeScalarMaterialProperty(const MaterialProperty<Real> * p,
+                                             const unsigned int qp) override final
+  {
+    return (*p)[qp];
+  }
 };

framework/include/userobject/InterfaceQpUserObjectBase.h

@@ -18,11 +18,11 @@ InputParameters validParams<InterfaceQpUserObjectBase>();
 
 /**
  * This is a base class for userobjects collecting values of variables or material properites across
- * an interface at each QP. This userobejct class always return a scalar value and compute both the
- * current value or its rate. The computed scalar value depends on the given parameter
- * interface_value_type paramters (see IntervafeValueTools). Also, it provides two output options to
- * all other MOOSE systems, a qp value (getQpValue) or an element side average value
- * (getSideAverageValue).
+ * an interface at each QP. This userobejct class always return a scalar value and can compute the
+ * current value or current rate or the current increment. The computed scalar depends on the
+ * given interface_value_type paramters (see IntervafeValueTools). Also, it provides two
+ * output options to all other MOOSE systems as a qp value (getQpValue) or an element side average
+ * value (getSideAverageValue).
  */
 class InterfaceQpUserObjectBase : public InterfaceValueUserObject
 {
@@ -37,15 +37,17 @@ class InterfaceQpUserObjectBase : public InterfaceValueUserObject
   virtual void finalize() { return; };
   virtual void threadJoin(const UserObject & /*uo*/) { return; };
 
+  /// function returning the quadrature point value
   Real getQpValue(const dof_id_type elem, const unsigned int side, unsigned int qp) const;
-
+  /// function returning the element side average value
   Real getSideAverageValue(const dof_id_type elem, const unsigned int side) const;
 
 protected:
+  /// boolealn varaibles deciding which type of value to return
   const bool _compute_rate;
+  const bool _compute_increment;
   /// this map is used to store QP data.
   std::map<std::pair<dof_id_type, unsigned int>, std::vector<Real>> _map_values;
   std::map<std::pair<dof_id_type, unsigned int>, std::vector<Real>> _map_JxW;
-  virtual Real computeRealValueMaster(const unsigned int /*qp*/) = 0;
-  virtual Real computeRealValueSlave(const unsigned int /*qp*/) = 0;
+  virtual Real computeRealValue(const unsigned int /*qp*/) = 0;
 };

framework/include/userobject/InterfaceQpValueUserObject.h

@@ -17,9 +17,7 @@ template <>
 InputParameters validParams<InterfaceQpValueUserObject>();
 
 /**
- * This userobject collect values of a variable across an interface for each QP and compute a
- * scalar. The computed scalar value depends on the given parameter _interface_value_type\
- * _interface_value_type (see IntervafeValueTools).
+ * Specialization of InterfaceQpUserObjectBase for scalar variables.
  */
 class InterfaceQpValueUserObject : public InterfaceQpUserObjectBase
 {
@@ -29,8 +27,11 @@ class InterfaceQpValueUserObject : public InterfaceQpUserObjectBase
   virtual ~InterfaceQpValueUserObject(){};
 
 protected:
-  virtual Real computeRealValueMaster(const unsigned int qp) override { return _u[qp]; };
-  virtual Real computeRealValueSlave(const unsigned int qp) override { return _u_neighbor[qp]; };
+  virtual Real computeRealValue(const unsigned int qp) override;
+
+  /// the variable and neighbor variable values or rate
+  ///@{
   const VariableValue & _u;
   const VariableValue & _u_neighbor;
+  ///@}
 };

framework/src/userobject/InterfaceQpMaterialPropertyRealUO.C

@@ -17,9 +17,10 @@ InputParameters
 InterfaceQpMaterialPropertyRealUO::validParams()
 {
   InputParameters params = InterfaceQpMaterialPropertyBaseUserObject<Real>::validParams();
-  params.addClassDescription("Computes the value or rate of a Real Material property across an "
-                             "interface. The value or rate is computed according to the provided "
-                             "interface_value_type parameter");
+  params.addClassDescription(
+      "Computes the value, rate or increment of a Real Material property across an "
+      "interface. The value or rate is computed according to the provided "
+      "interface_value_type parameter");
   return params;
 }
 
@@ -29,31 +30,3 @@ InterfaceQpMaterialPropertyRealUO::InterfaceQpMaterialPropertyRealUO(
 
 {
 }
-
-Real
-InterfaceQpMaterialPropertyRealUO::computeRealValueMaster(const unsigned int qp)
-{
-  if (_compute_rate)
-  {
-    if (_dt != 0)
-      return (_prop[qp] - (*_prop_old)[qp]) / _dt;
-    else
-      return 0;
-  }
-  else
-    return _prop[qp];
-}
-
-Real
-InterfaceQpMaterialPropertyRealUO::computeRealValueSlave(const unsigned int qp)
-{
-  if (_compute_rate)
-  {
-    if (_dt != 0)
-      return (_prop_neighbor[qp] - (*_prop_neighbor_old)[qp]) / _dt;
-    else
-      return 0;
-  }
-  else
-    return _prop_neighbor[qp];
-}

framework/src/userobject/InterfaceQpUserObjectBase.C

@@ -18,13 +18,18 @@ InterfaceQpUserObjectBase::validParams()
   InputParameters params = InterfaceValueUserObject::validParams();
   params.addClassDescription("Base class to compute a scalar value or rate across an interface");
   params.addParam<bool>("compute_rate", false, "if true, compute the rate of the value.");
+  params.addParam<bool>("compute_increment", false, "if true, compute the finite increment.");
   return params;
 }
 
 InterfaceQpUserObjectBase::InterfaceQpUserObjectBase(const InputParameters & parameters)
-  : InterfaceValueUserObject(parameters), _compute_rate(getParam<bool>("compute_rate"))
+  : InterfaceValueUserObject(parameters),
+    _compute_rate(getParam<bool>("compute_rate")),
+    _compute_increment(getParam<bool>("compute_increment"))
 
 {
+  if (_compute_rate && _compute_increment)
+    mooseError("InterfaceQpUserObjectBase cannot compute both the rate and the increment");
 }
 
 void
@@ -74,7 +79,7 @@ InterfaceQpUserObjectBase::execute()
     for (unsigned int qp = 0; qp < _qrule->n_points(); ++qp)
     {
       // compute average value at qp
-      vec[qp] = computeInterfaceValueType(computeRealValueMaster(qp), computeRealValueSlave(qp));
+      vec[qp] = computeRealValue(qp);
       jxw[qp] = _JxW[qp];
     }
   }

framework/src/userobject/InterfaceQpValueUserObject.C

@@ -18,21 +18,31 @@ InterfaceQpValueUserObject::validParams()
 {
   InputParameters params = InterfaceQpUserObjectBase::validParams();
   params.addRequiredCoupledVar("var", "The variable name");
-  params.addCoupledVar("var_neighbor", "The variable name");
-  params.addClassDescription("Computes the variable value or rate across an "
+  params.addCoupledVar("var_neighbor", "The neighbor variable name");
+  params.addClassDescription("Computes the variable value, rate or increment across an "
                              "interface. The value or rate is computed according to the provided "
                              "interface_value_type parameter");
   return params;
 }
 
 InterfaceQpValueUserObject::InterfaceQpValueUserObject(const InputParameters & parameters)
   : InterfaceQpUserObjectBase(parameters),
-    _u(_compute_rate ? coupledDot("var") : coupledValue("var")),
-    _u_neighbor(
-        parameters.isParamSetByUser("var_neighbor")
-            ? (_compute_rate ? coupledNeighborValueDot("var_neighbor")
-                             : coupledNeighborValue("var_neighbor"))
-            : (_compute_rate ? coupledNeighborValueDot("var") : coupledNeighborValue("var")))
+    _u(_compute_rate || _compute_increment ? coupledDot("var") : coupledValue("var")),
+    _u_neighbor(parameters.isParamSetByUser("var_neighbor")
+                    ? (_compute_rate || _compute_increment ? coupledNeighborValueDot("var_neighbor")
+                                                           : coupledNeighborValue("var_neighbor"))
+                    : (_compute_rate || _compute_increment ? coupledNeighborValueDot("var")
+                                                           : coupledNeighborValue("var")))
 
 {
 }
+
+Real
+InterfaceQpValueUserObject::computeRealValue(const unsigned int qp)
+{
+  Real val = computeInterfaceValueType(_u[qp], _u_neighbor[qp]);
+  if (_compute_increment)
+    val *= _dt;
+
+  return val;
+}

test/src/materials/LinearNonLinearIterationInterfaceMaterial.C

@@ -20,7 +20,7 @@ LinearNonLinearIterationInterfaceMaterial::validParams()
   params.addRequiredParam<MaterialPropertyName>("prop_name", "The name of the property");
   params.addParam<Real>("prefactor", 1, "the prefactor to apply to the new material value");
   params.addClassDescription(
-      "Material whose property  is equal to (t_step+n_linear*n_nonlinear)*prefactor");
+      "Interface material whose property is equal to (t_step+n_linear*n_nonlinear)*prefactor");
   return params;
 }
 

test/src/materials/LinearNonLinearIterationMaterial.C

@@ -20,7 +20,7 @@ LinearNonLinearIterationMaterial::validParams()
   params.addRequiredParam<MaterialPropertyName>("prop_name", "The name of the property");
   params.addParam<Real>("prefactor", 1, "the prefactor to apply to the new material value");
   params.addClassDescription(
-      "Material whose property  is equal to (t_step+n_linear*n_nonlinear)*prefactor");
+      "Material whose property is equal to (t_step+n_linear*n_nonlinear)*prefactor");
   return params;
 }