The Spatio-Temporal Path system #117

hugary1995 · 2023-12-06T04:23:04Z

close #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 MooseObjects 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.

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.

moosebuild · 2023-12-12T22:59:55Z

Job Documentation on 554b071 wanted to post the following:

View the site here

This comment will be updated on new commits.

moosebuild · 2023-12-12T23:00:00Z

Job Coverage on 554b071 wanted to post the following:

Coverage

	d0e3c6	#117 554b07
	Total	Total	+/-	New
Rate	68.98%	71.41%	+2.43%	82.86%
Hits	1023	1284	+261	261
Misses	460	514	+54	54

Diff coverage report

Full coverage report

Warnings

New new line coverage rate 82.86% is less than the suggested 90.0%

This comment will be updated on new commits.

cticenhour

Thanks for this contribution @hugary1995! I can see this being incredibly useful.

Not done here quite yet, but I wanted to note my current progress since there is some low-hanging fruit to address. Will dive in more tomorrow!

cticenhour · 2023-12-12T20:48:59Z

doc/content/source/materials/ADMovingEllipsoidalHeatSource.md

+
+!syntax description /Materials/ADMovingEllipsoidalHeatSource
+
+## Example Input File Syntax


Please add example input file syntax for each of these documentation files, for those objects present in the added tests. This applies to all the new documentation files except for the action and system pages.

cticenhour · 2023-12-12T20:54:12Z

include/materials/ADMovingEllipsoidalHeatSource.h

+  const ADMaterialProperty<Real> & _a;
+  /// Length of the ellipsoid semi-axis perpendicular to the path direction
+  const ADMaterialProperty<Real> & _b;
+  /// Process efficienty


Suggested change

/// Process efficienty

/// Process efficiency

cticenhour · 2023-12-12T21:00:34Z

test/tests/spatiotemporal_path/tests

+    design = 'ADMovingEllipsoidalHeatSource.md FunctionSpatioTemporalPath.md'
+    requirement = 'The system shall be able to use a function-defined path to evolve the heat source.'
+  []
+  [esm]


Suggested change

[esm]

[element_subdomain_modifier]

I am OK with the acronym being used in the input file naming, but would like this to be written out for the TestHarness output, since its an unfamiliar acronym to some.

cticenhour · 2023-12-12T23:00:05Z

doc/content/syntax/SpatioTemporalPaths/index.md

@@ -0,0 +1,32 @@
+# SpatioTemporalPath System


More of a general comment/question - have you thought about (or do you see) this system being applied to some of our current laser melting and laser welding examples? I wonder if there's some quality of life updates to be made in some of these older examples after this goes in....

cticenhour

I think this will fix the current documentation failures.

cticenhour · 2023-12-12T23:10:58Z

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.


Suggested change

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.

This action registers objects derived from [`SpatioTemporalPath`](SpatioTemporalPaths/index.md) into the current problem. See the linked page for more details on the usage of the `SpatioTemporalPath` system.

cticenhour · 2023-12-12T23:11:20Z

doc/content/syntax/SpatioTemporalPaths/index.md

+!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


Suggested change

!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

!syntax list /SpatioTemporalPaths objects=True actions=False subsystems=False

!syntax list /SpatioTemporalPaths objects=False actions=False subsystems=True

!syntax list /SpatioTemporalPaths objects=False actions=True subsystems=False

cticenhour

Alright, finally had time to finish this review. Thanks for this new feature! A couple more comments about parameter defaults and user documentation, but I think we'll be ready to go soon.

cticenhour · 2023-12-18T18:13:14Z

src/spatiotemporalpaths/CSVPiecewiseLinearSpatioTemporalPath.C

+  MooseEnum header_flag("OFF ON AUTO", "AUTO");
+  params.addParam<MooseEnum>("file_header",
+                             header_flag,
+                             "Set the header flag. ON: use the first row has header, OFF: assumes "
+                             "no header, AUTO: attempt to determine if a header exists.");
+  MooseEnum format_flag("COLUMNS ROWS", "COLUMNS");
+  params.addParam<MooseEnum>("file_format", format_flag, "Set the file format (rows vs. columns).");


We should let the user know the default enum case for both of these params. I don't remember seeing such a mention in the documentation, so it should be done either here in the param description or in the markdown.

cticenhour · 2023-12-18T18:15:40Z

src/spatiotemporalpaths/PiecewiseLinearSpatioTemporalPathBase.C

+  MooseEnum outside_behavior("CONSTANT EXTRAPOLATION EXCEPTION", "CONSTANT");
+  params.addParam<MooseEnum>(
+      "outside",
+      outside_behavior,
+      "The method to use when extrapolating the path position outside its temporal support. "
+      "CONSTANT: Return the closest path point; EXTRAPOLATION: Linear extrapolation; EXCEPTION: "
+      "Raise an exception when trying to extrapolate.");


Again, should mention the default either here or in the documentation discussion.

cticenhour · 2023-12-18T18:25:47Z

Just took a look at the coverage diff - could you also add some error checking tests? The majority of the diff is missing coverage on mooseError calls.

cticenhour self-assigned this Dec 12, 2023

cticenhour requested changes Dec 12, 2023

View reviewed changes

cticenhour reviewed Dec 12, 2023

View reviewed changes

Smooth direction and smooth velocity

554b071

cticenhour requested changes Dec 18, 2023

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

The Spatio-Temporal Path system #117

The Spatio-Temporal Path system #117

hugary1995 commented Dec 6, 2023

moosebuild commented Dec 12, 2023 •

edited

Loading

moosebuild commented Dec 12, 2023 •

edited

Loading

cticenhour left a comment

cticenhour Dec 12, 2023

cticenhour Dec 12, 2023

cticenhour Dec 12, 2023

cticenhour Dec 12, 2023

cticenhour left a comment

cticenhour Dec 12, 2023

cticenhour Dec 12, 2023

cticenhour left a comment

cticenhour Dec 18, 2023

cticenhour Dec 18, 2023

cticenhour commented Dec 18, 2023


		!syntax description /Materials/ADMovingEllipsoidalHeatSource

		## Example Input File Syntax

		@@ -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.

The Spatio-Temporal Path system #117

Are you sure you want to change the base?

The Spatio-Temporal Path system #117

Conversation

hugary1995 commented Dec 6, 2023

moosebuild commented Dec 12, 2023 • edited Loading

moosebuild commented Dec 12, 2023 • edited Loading

Coverage

Warnings

cticenhour left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cticenhour left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cticenhour left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cticenhour commented Dec 18, 2023

moosebuild commented Dec 12, 2023 •

edited

Loading

moosebuild commented Dec 12, 2023 •

edited

Loading