The Spatio-Temporal Path system

close idaholab#116

This PR adds a new system associated with the syntax block `[SpatioTemporalPaths]`. Multiple SpatioTemporalPath-derived objects
can be added under that syntax block. I have implemented 3 objects so far:

- `PiecewiseLinearSpatioTemporalPath`: This one accepts input file vectors `t`, `x`, `y`, `z` and constructs a spatio-temporal path object.
- `CSVPiecewiseLinearSpatioTemporalPath`: This one is similar to the previous one but instead reads from a csv file.
- `FunctionSpatioTemporalPath`: This one accepts moose functions for `x`, `y` and `z`.

Once a `SpatioTemporalPath` object is constructed, other `MooseObject`s can retrieve path given its name from the warehouse, through the
`SpatioTemporalPathInterface` interface. See e.g. `ADMovingHeatSource` for how that coupling works.

Each spatio-temporal path objects recomputes several path-related information at every time step:

- `SpatioTemporalPath::position()` returns the current path front.
- `SpatioTemporalPath::velocity()` returns the current path moving velocity.
- `SpatioTemporalPath::direction()` returns the current path direction.

Variants of the above methods exist which accepts a time and computes the corresponding path information at the specified time.

By default the path-related information is recomputed at every time step, i.e. the path information is "live".
The users have control over how often the path-related information is updated by the parameter `update_interval`.
There are also methods that retrieve the path-related information from the previous update:

- `SpatioTemporalPath::previousPosition()`
- `SpatioTemporalPath::previousVelocity()`
- `SpatioTemporalPath::previousDirection()`

An object deriving from `SpatioTemporalPath` only need to override one single method `Point position(Real t) const`. Default implementations
are provided for `RealVectorValue velocity(Real t)` and `RealVectorValue direction(Real t)` which use finite-differencing to compute the derivatives.
The developer can optionally override these methods to provide more efficient/accurate implementations.

Utility methods are provided to compute the tangential and normal components of the distance between a given point and the path's current position.

- `SpatioTemporalPath::tangentialDistance(const Point & p)`
- `SpatioTemporalPath::normalDistance(const Point & p)`

Similarly, variants of the above methods exist which additionally accepts a specified time.

Spatio-temporal paths are useful in many scenarios. I have added two concrete examples for demonstration purposes:

- `ADMovingHeatSource` and `ADMovingEllipsoidalHeatSource`
- `SpatioTemporalPathElementSubdomainModifier`

Their names are self-explanatory. Note that `ADMovingEllipsoidalHeatSource` makes use of the tangential and normal distance to effectively "rotate" the ellipsoidal heat source.

doc/content/source/actions/AddSpatioTemporalPathAction.md

@@ -0,0 +1,3 @@
+# AddSpatioTemporalPathAction
+
+This action registers objects derived from [`SpatioTemporalPath`](SpatioTemporalPath/index.md) into the current problem. See the linked page for more details on the usage of the `SpatioTemporalPath` system.

doc/content/source/materials/ADMovingEllipsoidalHeatSource.md

@@ -0,0 +1,11 @@
+# ADMovingEllipsoidalHeatSource
+
+!syntax description /Materials/ADMovingEllipsoidalHeatSource
+
+## Example Input File Syntax
+
+!syntax parameters /Materials/ADMovingEllipsoidalHeatSource
+
+!syntax inputs /Materials/ADMovingEllipsoidalHeatSource
+
+!syntax children /Materials/ADMovingEllipsoidalHeatSource

doc/content/source/spatiotemporalpaths/CSVPiecewiseLinearSpatioTemporalPath.md

@@ -0,0 +1,11 @@
+# CSVPiecewiseLinearSpatioTemporalPath
+
+!syntax description /UserObjects/CSVPiecewiseLinearSpatioTemporalPath
+
+## Example Input File Syntax
+
+!syntax parameters /UserObjects/CSVPiecewiseLinearSpatioTemporalPath
+
+!syntax inputs /UserObjects/CSVPiecewiseLinearSpatioTemporalPath
+
+!syntax children /UserObjects/CSVPiecewiseLinearSpatioTemporalPath

doc/content/source/spatiotemporalpaths/FunctionSpatioTemporalPath.md

@@ -0,0 +1,11 @@
+# FunctionSpatioTemporalPath
+
+!syntax description /UserObjects/FunctionSpatioTemporalPath
+
+## Example Input File Syntax
+
+!syntax parameters /UserObjects/FunctionSpatioTemporalPath
+
+!syntax inputs /UserObjects/FunctionSpatioTemporalPath
+
+!syntax children /UserObjects/FunctionSpatioTemporalPath

doc/content/source/spatiotemporalpaths/PiecewiseLinearSpatioTemporalPath.md

@@ -0,0 +1,11 @@
+# PiecewiseLinearSpatioTemporalPath
+
+!syntax description /UserObjects/PiecewiseLinearSpatioTemporalPath
+
+## Example Input File Syntax
+
+!syntax parameters /UserObjects/PiecewiseLinearSpatioTemporalPath
+
+!syntax inputs /UserObjects/PiecewiseLinearSpatioTemporalPath
+
+!syntax children /UserObjects/PiecewiseLinearSpatioTemporalPath

doc/content/source/userobjects/SpatioTemporalPathElementSubdomainModifier.md

@@ -0,0 +1,11 @@
+# SpatioTemporalPathElementSubdomainModifier
+
+!syntax description /UserObjects/SpatioTemporalPathElementSubdomainModifier
+
+## Example Input File Syntax
+
+!syntax parameters /UserObjects/SpatioTemporalPathElementSubdomainModifier
+
+!syntax inputs /UserObjects/SpatioTemporalPathElementSubdomainModifier
+
+!syntax children /UserObjects/SpatioTemporalPathElementSubdomainModifier

doc/content/syntax/SpatioTemporalPaths/index.md

@@ -0,0 +1,32 @@
+# SpatioTemporalPath System
+
+The SpatioTemporalPath system offers flexible ways of defining spatio-temporal paths, hereinafter referred to as paths, that are often useful in additive manufacturing simulations.
+
+## Overview
+
+A spatio-temporal path is a vector-valued function of time, written as
+
+\begin{equation}
+  \begin{aligned}
+    \boldsymbol{x} = f(t)
+  \end{aligned}
+\end{equation}
+
+where $\boldsymbol{x}$ is the path front at time $t$. In addition to the path front, the path object also defines the path's moving velocity $\boldsymbol{v}$ and the path's moving direction $\boldsymbol{t}$, defined as
+
+\begin{equation}
+  \begin{aligned}
+    \boldsymbol{v} &= \dfrac{\boldsymbol{x}}{t}
+    \boldsymbol{t} &= \dfrac{\boldsymbol{v}}{\lVert\boldsymbol{v}\rVert}
+  \end{aligned}
+\end{equation}
+
+## Example Input File Syntax
+
+Spatio-temporal paths are defined under the `[SpatioTemporalPaths]` in the input file and can be referenced by other objects in the input file.
+
+!syntax list /SpatioTemporalPath objects=True actions=False subsystems=False
+
+!syntax list /SpatioTemporalPath objects=False actions=False subsystems=True
+
+!syntax list /SpatioTemporalPath objects=False actions=True subsystems=False

include/actions/AddSpatioTemporalPathAction.h

@@ -0,0 +1,25 @@
+/****************************************************************************/
+/*                        DO NOT MODIFY THIS HEADER                         */
+/*                                                                          */
+/* MALAMUTE: MOOSE Application Library for Advanced Manufacturing UTilitiEs */
+/*                                                                          */
+/*           Copyright 2021 - 2023, Battelle Energy Alliance, LLC           */
+/*                           ALL RIGHTS RESERVED                            */
+/****************************************************************************/
+
+#pragma once
+
+#include "MooseObjectAction.h"
+
+/**
+ * Add SpatioTemporalPath
+ */
+class AddSpatioTemporalPathAction : public MooseObjectAction
+{
+public:
+  AddSpatioTemporalPathAction(const InputParameters & params);
+
+  static InputParameters validParams();
+
+  void act() override final;
+};

include/interfaces/SpatioTemporalPathInterface.h

@@ -0,0 +1,51 @@
+/****************************************************************************/
+/*                        DO NOT MODIFY THIS HEADER                         */
+/*                                                                          */
+/* MALAMUTE: MOOSE Application Library for Advanced Manufacturing UTilitiEs */
+/*                                                                          */
+/*           Copyright 2021 - 2023, Battelle Energy Alliance, LLC           */
+/*                           ALL RIGHTS RESERVED                            */
+/****************************************************************************/
+
+#pragma once
+
+#include "MooseTypes.h"
+#include "InputParameters.h"
+
+class FEProblemBase;
+class InputParameters;
+class MooseObject;
+class SpatioTemporalPath;
+
+/**
+ * Interface for objects that need to use SpatioTemporalPath
+ */
+class SpatioTemporalPathInterface
+{
+public:
+  SpatioTemporalPathInterface(const MooseObject * moose_object);
+
+  /**
+   * Get a SpatioTemporalPath with a given name
+   * @param name The name of the parameter key of the SpatioTemporalPath to retrieve
+   * @return The SpatioTemporalPath with name associated with the parameter 'name'
+   */
+  const SpatioTemporalPath & getSpatioTemporalPath(const std::string & name) const;
+
+  /**
+   * Get a SpatioTemporalPath with a given name
+   * @param name The name of the SpatioTemporalPath to retrieve
+   * @return The SpatioTemporalPath with name 'name'
+   */
+  const SpatioTemporalPath & getSpatioTemporalPathByName(const std::string & name) const;
+
+private:
+  /// Parameters of the object with this interface
+  const InputParameters & _stpi_params;
+
+  /// Reference to FEProblemBase instance
+  FEProblemBase & _stpi_feproblem;
+
+  /// Thread ID
+  const THREAD_ID _stpi_tid;
+};

include/materials/ADMovingEllipsoidalHeatSource.h

@@ -0,0 +1,37 @@
+/****************************************************************************/
+/*                        DO NOT MODIFY THIS HEADER                         */
+/*                                                                          */
+/* MALAMUTE: MOOSE Application Library for Advanced Manufacturing UTilitiEs */
+/*                                                                          */
+/*           Copyright 2021 - 2023, Battelle Energy Alliance, LLC           */
+/*                           ALL RIGHTS RESERVED                            */
+/****************************************************************************/
+
+#pragma once
+
+#include "ADMovingHeatSource.h"
+
+/**
+ * @brief A moving ellipsoidal heat source following a SpatioTemporalPath
+ */
+class ADMovingEllipsoidalHeatSource : public ADMovingHeatSource
+{
+public:
+  static InputParameters validParams();
+
+  ADMovingEllipsoidalHeatSource(const InputParameters & parameters);
+
+protected:
+  virtual ADReal computeHeatSource() override;
+
+  /// Input power
+  const ADMaterialProperty<Real> & _P;
+  /// Length of the ellipsoid semi-axis along the path direction
+  const ADMaterialProperty<Real> & _a;
+  /// Length of the ellipsoid semi-axis perpendicular to the path direction
+  const ADMaterialProperty<Real> & _b;
+  /// Process efficienty
+  const Real _eta;
+  /// Scaling factor
+  const Real _scale;
+};

include/materials/ADMovingHeatSource.h

@@ -0,0 +1,41 @@
+/****************************************************************************/
+/*                        DO NOT MODIFY THIS HEADER                         */
+/*                                                                          */
+/* MALAMUTE: MOOSE Application Library for Advanced Manufacturing UTilitiEs */
+/*                                                                          */
+/*           Copyright 2021 - 2023, Battelle Energy Alliance, LLC           */
+/*                           ALL RIGHTS RESERVED                            */
+/****************************************************************************/
+
+#pragma once
+
+#include "Material.h"
+#include "SpatioTemporalPath.h"
+#include "SpatioTemporalPathInterface.h"
+
+/**
+ * @brief A moving heat source following a SpatioTemporalPath
+ */
+class ADMovingHeatSource : public Material, public SpatioTemporalPathInterface
+{
+public:
+  static InputParameters validParams();
+
+  ADMovingHeatSource(const InputParameters & parameters);
+
+protected:
+  virtual void computeQpProperties() override;
+  virtual ADReal computeHeatSource() = 0;
+
+  /// The path
+  const SpatioTemporalPath & _path;
+
+  /// The heat source
+  ADMaterialProperty<Real> & _volumetric_heat;
+
+  /// Tangential distance from the heat source
+  MaterialProperty<Real> & _tangential_distance;
+
+  /// Normal distance from the heat source
+  MaterialProperty<Real> & _normal_distance;
+};

include/spatiotemporalpaths/CSVPiecewiseLinearSpatioTemporalPath.h

@@ -0,0 +1,24 @@
+/****************************************************************************/
+/*                        DO NOT MODIFY THIS HEADER                         */
+/*                                                                          */
+/* MALAMUTE: MOOSE Application Library for Advanced Manufacturing UTilitiEs */
+/*                                                                          */
+/*           Copyright 2021 - 2023, Battelle Energy Alliance, LLC           */
+/*                           ALL RIGHTS RESERVED                            */
+/****************************************************************************/
+
+#pragma once
+
+#include "PiecewiseLinearSpatioTemporalPathBase.h"
+
+/**
+ * @brief Construct a piecewise linear path from a csv file
+ *
+ */
+class CSVPiecewiseLinearSpatioTemporalPath : public PiecewiseLinearSpatioTemporalPathBase
+{
+public:
+  static InputParameters validParams();
+
+  CSVPiecewiseLinearSpatioTemporalPath(const InputParameters & params);
+};

include/spatiotemporalpaths/FunctionSpatioTemporalPath.h

@@ -0,0 +1,35 @@
+/****************************************************************************/
+/*                        DO NOT MODIFY THIS HEADER                         */
+/*                                                                          */
+/* MALAMUTE: MOOSE Application Library for Advanced Manufacturing UTilitiEs */
+/*                                                                          */
+/*           Copyright 2021 - 2023, Battelle Energy Alliance, LLC           */
+/*                           ALL RIGHTS RESERVED                            */
+/****************************************************************************/
+
+#pragma once
+
+#include "SpatioTemporalPath.h"
+
+class Function;
+
+/**
+ * @brief A spatiotemporal path whose coordinates are specified using MOOSE functions.
+ */
+class FunctionSpatioTemporalPath : public SpatioTemporalPath
+{
+public:
+  static InputParameters validParams();
+
+  FunctionSpatioTemporalPath(const InputParameters & params);
+
+  virtual Point position(Real t) const override;
+
+protected:
+  /// The function for the x-coordinate
+  const Function * _x;
+  /// The function for the y-coordinate
+  const Function * _y;
+  /// The function for the z-coordinate
+  const Function * _z;
+};

include/spatiotemporalpaths/PiecewiseLinearSpatioTemporalPath.h

@@ -0,0 +1,23 @@
+/****************************************************************************/
+/*                        DO NOT MODIFY THIS HEADER                         */
+/*                                                                          */
+/* MALAMUTE: MOOSE Application Library for Advanced Manufacturing UTilitiEs */
+/*                                                                          */
+/*           Copyright 2021 - 2023, Battelle Energy Alliance, LLC           */
+/*                           ALL RIGHTS RESERVED                            */
+/****************************************************************************/
+
+#pragma once
+
+#include "PiecewiseLinearSpatioTemporalPathBase.h"
+
+/**
+ * @brief Construct a piecewise linear spatiotemporal path from discrete times and vertices.
+ */
+class PiecewiseLinearSpatioTemporalPath : public PiecewiseLinearSpatioTemporalPathBase
+{
+public:
+  static InputParameters validParams();
+
+  PiecewiseLinearSpatioTemporalPath(const InputParameters & params);
+};