Merge pull request #28756 from GiudGiud/PR_dot

framework/doc/content/source/functormaterials/GenericFunctorTimeDerivativeMaterial.md

@@ -0,0 +1,33 @@
+# GenericFunctorTimeDerivativeMaterial
+
+!syntax description /FunctorMaterials/GenericFunctorTimeDerivativeMaterial
+
+## Overview
+
+This object creates [functor material properties](Materials/index.md#functor-props) that are time derivatives of
+other functors.
+
+!alert warning
+Not all functors can be used as inputs. Many functors, notably off-the-shelf postprocessors do not compute
+their time derivative by default. These time derivatives can be derived and implemented as the `dot` functor routine.
+Unless this routine is implemented, these functors should not be used as inputs to this functor material.
+
+!alert warning
+Time derivatives are not available at all times during the simulation. Notably, on `INITIAL` and `TIMESTEP_BEGIN`,
+the time derivatives are a priori NOT available, and any functor material properties created by this object will return 0.
+
+!alert warning
+The time derivative routine used by this functor, namely `functor.dot(spatial_argument, state_argument)`, is not implemented for
+all spatial arguments and all state arguments for every single functor. Users must be extremely careful in their use
+of the functors created by this functor material.
+
+!alert note
+All AD-types of the properties defined in this material must match. Variables are automatically
+considered as AD functors, even auxiliary variables. The AD version of this material is `ADGenericFunctorTimeDerivativeMaterial`.
+Its inputs are a vector of AD functors and it creates AD functor material properties.
+
+!syntax parameters /FunctorMaterials/GenericFunctorTimeDerivativeMaterial
+
+!syntax inputs /FunctorMaterials/GenericFunctorTimeDerivativeMaterial
+
+!syntax children /FunctorMaterials/GenericFunctorTimeDerivativeMaterial

framework/include/functormaterials/GenericFunctorTimeDerivativeMaterial.h

@@ -0,0 +1,42 @@
+//* This file is part of the MOOSE framework
+//* https://www.mooseframework.org
+//*
+//* 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 "FunctorMaterial.h"
+
+/**
+ * This material automatically declares as functor material properties whatever is passed to it
+ * through the parameters 'prop_names' and uses the time derivatives of the functors from
+ * 'prop_values' as the values for those properties.
+ */
+template <bool is_ad>
+class GenericFunctorTimeDerivativeMaterialTempl : public FunctorMaterial
+{
+public:
+  static InputParameters validParams();
+
+  GenericFunctorTimeDerivativeMaterialTempl(const InputParameters & parameters);
+
+protected:
+  /// Names of the functor material properties to define
+  std::vector<std::string> _prop_names;
+
+  /// Names of the functors to evaluate for those properties
+  std::vector<MooseFunctorName> _prop_values;
+
+  /// Number of properties to define
+  const unsigned int _num_props;
+
+  /// Vector of the functors
+  std::vector<const Moose::Functor<GenericReal<is_ad>> *> _functors;
+};
+
+typedef GenericFunctorTimeDerivativeMaterialTempl<false> GenericFunctorTimeDerivativeMaterial;
+typedef GenericFunctorTimeDerivativeMaterialTempl<true> ADGenericFunctorTimeDerivativeMaterial;

framework/src/functormaterials/GenericFunctorTimeDerivativeMaterial.C

@@ -0,0 +1,76 @@
+//* This file is part of the MOOSE framework
+//* https://www.mooseframework.org
+//*
+//* 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 "GenericFunctorTimeDerivativeMaterial.h"
+
+registerMooseObject("MooseApp", GenericFunctorTimeDerivativeMaterial);
+registerMooseObject("MooseApp", ADGenericFunctorTimeDerivativeMaterial);
+
+template <bool is_ad>
+InputParameters
+GenericFunctorTimeDerivativeMaterialTempl<is_ad>::validParams()
+{
+  InputParameters params = FunctorMaterial::validParams();
+  params.set<ExecFlagEnum>("execute_on") = {EXEC_ALWAYS};
+  params.addClassDescription(
+      "FunctorMaterial object for declaring properties that are populated by evaluation of "
+      "time derivatives of Functors objects. (such as variables, constants, postprocessors). "
+      "The time derivative is only returned if the 'dot' functor routine is implemented.");
+  params.addParam<std::vector<std::string>>("prop_names",
+                                            "The names of the properties this material will have");
+
+  params.addParam<std::vector<MooseFunctorName>>("prop_values",
+                                                 "The corresponding names of the "
+                                                 "functors which gradient are going to provide "
+                                                 "the values for the variables");
+  return params;
+}
+
+template <bool is_ad>
+GenericFunctorTimeDerivativeMaterialTempl<is_ad>::GenericFunctorTimeDerivativeMaterialTempl(
+    const InputParameters & parameters)
+  : FunctorMaterial(parameters),
+    _prop_names(getParam<std::vector<std::string>>("prop_names")),
+    _prop_values(getParam<std::vector<MooseFunctorName>>("prop_values")),
+    _num_props(_prop_names.size())
+{
+  unsigned int num_values = _prop_values.size();
+
+  if (_num_props != num_values)
+    mooseError("Number of prop_names must match the number of prop_values for a "
+               "GenericFunctorTimeDerivativeMaterial!");
+
+  // Check that there is no name conflict, a common mistake with this object
+  for (const auto i : make_range(_num_props))
+    for (const auto j : make_range(num_values))
+      if (_prop_names[i] == _prop_values[j])
+        paramError("prop_names",
+                   "prop_names should not be the same as any of the prop_values. They"
+                   " can both be functors, and functors may not have the same name.");
+
+  _functors.resize(_num_props);
+
+  for (const auto i : make_range(_num_props))
+  {
+    if (_fe_problem.hasPostprocessor(_prop_values[i]))
+      paramError("prop_names", "Postprocessors should not be used in this functor material");
+    _functors[i] = &getFunctor<GenericReal<is_ad>>(_prop_values[i]);
+  }
+
+  const std::set<ExecFlagType> clearance_schedule(_execute_enum.begin(), _execute_enum.end());
+  for (const auto i : make_range(_num_props))
+    addFunctorProperty<GenericReal<is_ad>>(
+        _prop_names[i],
+        [this, i](const auto & r, const auto & t) -> GenericReal<is_ad>
+        { return (*_functors[i]).dot(r, t); },
+        clearance_schedule);
+}
+
+template class GenericFunctorTimeDerivativeMaterialTempl<false>;
+template class GenericFunctorTimeDerivativeMaterialTempl<true>;

test/tests/functormaterials/time_derivatives/functor_time_derivatives.i

@@ -0,0 +1,97 @@
+[Mesh]
+  type = GeneratedMesh
+  dim = 3
+  nx = 2
+  ny = 2
+  nz = 2
+  xmin = 0.0
+  xmax = 4.0
+  ymin = 0.0
+  ymax = 6.0
+  zmin = 0.0
+  zmax = 10.0
+[]
+
+[Variables]
+  [v1]
+  []
+[]
+
+[Kernels]
+  [time]
+    type = TimeDerivative
+    variable = v1
+  []
+  [source]
+    type = BodyForce
+    variable = v1
+    function = 10
+  []
+[]
+
+[Functions]
+  [f1]
+    type = ParsedFunction
+    expression = '- 4 * t'
+  []
+  [f2]
+    type = ConstantFunction
+    value = 3
+  []
+[]
+
+[AuxVariables]
+  [v2]
+    [AuxKernel]
+      type = ParsedAux
+      expression = '3 * t'
+      use_xyzt = true
+    []
+  []
+[]
+
+[FunctorMaterials]
+  [time_derivatives]
+    type = ADGenericFunctorTimeDerivativeMaterial
+    prop_names = 'f1dt f2dt v1dt v2dt'
+    prop_values = 'f1 f2 v1 v2'
+  []
+[]
+
+[Postprocessors]
+  [f1_time]
+    type = ElementExtremeFunctorValue
+    functor = f1dt
+    value_type = max
+    execute_on = 'INITIAL'
+  []
+  [f2_time]
+    type = ElementExtremeFunctorValue
+    functor = f2dt
+    value_type = max
+    execute_on = 'INITIAL'
+  []
+  [v1_time]
+    type = ElementExtremeFunctorValue
+    functor = v1dt
+    value_type = max
+    # derivatives are not available on INITIAL and TIMESTEP_BEGIN
+    execute_on = 'TIMESTEP_END'
+  []
+  [v2_time]
+    type = ElementExtremeFunctorValue
+    functor = v2dt
+    value_type = max
+    # derivatives are not available on INITIAL and TIMESTEP_BEGIN
+    execute_on = 'TIMESTEP_END'
+  []
+[]
+
+[Executioner]
+  type = Transient
+  num_steps = 2
+[]
+
+[Outputs]
+  csv = true
+[]

test/tests/functormaterials/time_derivatives/gold/functor_time_derivatives_out.csv

@@ -0,0 +1,4 @@
+time,f1_time,f2_time,v1_time,v2_time
+0,-4,0,0,0
+1,-4,0,10,3
+2,-4,0,10,3

test/tests/functormaterials/time_derivatives/tests

@@ -0,0 +1,10 @@
+[Tests]
+  issues = '#28755'
+  design = 'GenericFunctorTimeDerivativeMaterial.md'
+  [test]
+    type = CSVDiff
+    input = functor_time_derivatives.i
+    csvdiff = functor_time_derivatives_out.csv
+    requirement = 'The system shall be able to compute the time derivatives of functors, and make them available as functor material properties.'
+  []
+[]