Merge pull request #28314 from kyleeswanson/MeshModifiers

Add MeshModifiers syntax

framework/doc/content/source/actions/AddMeshModifiersAction.md

@@ -0,0 +1,8 @@
+# AddMeshModifiersAction
+
+Adds `MeshModifier` objects into the system that are listed under `MeshModifiers/` in the input file.
+This action adds them to the [application](MooseApp.md).
+
+The preferred syntax for adding `MeshModifiers` is to add them in the `[Mesh]` block.
+
+<!-- !syntax parameters /Mesh/AddMeshModifiersAction -->

framework/doc/content/source/markers/BoundaryPreservedMarker.md

@@ -12,7 +12,7 @@ These elements might be coarsened later if the boundary moves to a different loc
 
 ## Example Input File Syntax
 
-!listing test/tests/userobjects/element_subdomain_modifier/adaptivity_moving_boundary.i
+!listing test/tests/meshmodifiers/element_subdomain_modifier/adaptivity_moving_boundary.i
            block=Adaptivity
            link=False
 

framework/doc/content/source/meshmodifiers/ActivateElementsByPath.md

@@ -0,0 +1,9 @@
+# ActivateElementsByPath
+
+This MeshModifier uses the +function path+ as the metric to activate (add) an element by moving the element from an "inactive" subdomain to the "active" subdomain. It uses the user provided points $(x(t), y(t), z(t))$ with components defined by the functions specified by the parameters `function_x`, `function_y`, and `function_z` in the input. An element is activated at time $t_0$ if this element is close (distance < `activate_distance`) to the point $(x(t_0), y(t_0), z(t_0))$.
+
+!syntax parameters /MeshModifiers/ActivateElementsByPath
+
+!syntax inputs /MeshModifiers/ActivateElementsByPath
+
+!syntax children /MeshModifiers/ActivateElementsByPath

framework/doc/content/source/meshmodifiers/ActivateElementsCoupled.md

@@ -0,0 +1,9 @@
+# ActivateElementsCoupled
+
+This MeshModifier uses the +coupled variable value+ as the metric to activate (add) an element by moving the element from an "inactive" subdomain to the "active" subdomain. It uses a coupled variable to decide whether to activate an element. The `coupled_var`, `activate_value` and the `activate_type` needs to be provided in the input to form the activation criterion. By default, the element is activated if the averaged value of the coupled variable in the element is `above` the `activate_value`. User can set `activate_type = 'below'` or `'equal'` to activate element when the averaged coupled variable value is below or equal to the `activate_value`.
+
+!syntax parameters /MeshModifiers/ActivateElementsCoupled
+
+!syntax inputs /MeshModifiers/ActivateElementsCoupled
+
+!syntax children /MeshModifiers/ActivateElementsCoupled

framework/doc/content/source/userobjects/ActivateElementsUserObjectBase.md → framework/doc/content/source/meshmodifiers/ActivateElementsUserObjectBase.md

@@ -2,4 +2,4 @@
 
 The `ActivateElementsUserObjectBase` class is for activating (adding) an element by moving the element from an "inactive" subdomain to the "active" subdomain. There are two metrics for activating an element, i.e., by +function path+ and by +coupled variable value+, which are implemented in the classes [ActivateElementsByPath](/ActivateElementsByPath.md) and [ActivateElementsCoupled](/ActivateElementsCoupled.md), respectively.
 
-This user object updates the boundary information due to the addition of elements across subdomains. User can save this boundary information by passing the changed boundary name to  `expand_boundary_name` in the input block.  Note that current implementation does not de-activate an element once the element is activated.
+This mesh modifier updates the boundary information due to the addition of elements across subdomains. User can save this boundary information by passing the changed boundary name to  `expand_boundary_name` in the input block.  Note that current implementation does not de-activate an element once the element is activated.

framework/doc/content/source/userobjects/CoupledVarThresholdElementSubdomainModifier.md → framework/doc/content/source/meshmodifiers/CoupledVarThresholdElementSubdomainModifier.md

@@ -1,6 +1,6 @@
 # CoupledVarThresholdElementSubdomainModifier
 
-!syntax description /UserObjects/CoupledVarThresholdElementSubdomainModifier
+!syntax description /MeshModifiers/CoupledVarThresholdElementSubdomainModifier
 
 ## Overview
 
@@ -26,23 +26,23 @@ Initially, the domain is decomposed by a vertical line $x=0.25$. The elements on
 
 If the `CoupledVarThresholdElementSubdomainModifier` is applied onto the entire domain, and the parameter `complement_subdomain_id` is set to 2, then the subdomain ID of all elements outside the circle will be set to 2:
 
-!listing test/tests/userobjects/element_subdomain_modifier/reversible.i start=[moving_circle] end=[] include-end=true
+!listing test/tests/meshmodifiers/element_subdomain_modifier/reversible.i start=[moving_circle] end=[] include-end=true
 
-!media media/userobjects/esm_reversible.jpg style=float:center;width:100%; caption=The result of a reversible element subdomain modifier at three different time steps
+!media media/meshmodifiers/esm_reversible.jpg style=float:center;width:100%; caption=The result of a reversible element subdomain modifier at three different time steps
 
 However, in many applications, e.g. element death and activation, the equivalent movement of element subdomains is not reversible. In this case, omitting the parameter `complement_subdomain_id` will make the subdomain modification irreversible:
 
-!listing test/tests/userobjects/element_subdomain_modifier/block_restricted.i start=[moving_circle] end=[] include-end=true
+!listing test/tests/meshmodifiers/element_subdomain_modifier/block_restricted.i start=[moving_circle] end=[] include-end=true
 
-!media media/userobjects/esm_irreversible.jpg style=float:center;width:100%; caption=The result of an irreversible element subdomain modifier at three different time steps
+!media media/meshmodifiers/esm_irreversible.jpg style=float:center;width:100%; caption=The result of an irreversible element subdomain modifier at three different time steps
 
 ## Moving boundary/interface nodeset/sideset modification
 
 The change of element subdomains will alter the definition of certain sidesets and nodesets. The `CoupledVarThresholdElementSubdomainModifier` optionally takes the parameter `moving_boundary_name` to help modify the corresponding sideset/nodeset. If the boundary provided through the `moving_boundary_name` parameter already exists, the modifier will attempt to modify the provided sideset/nodeset whenever an element changes subdomain. If the boundary does not exist, the modifier will create a sideset and a nodeset with the provided name.
 
-!media media/userobjects/esm_sideset.jpg style=float:center;width:100%; caption=The evolving sideset (green) at three different time steps
+!media media/meshmodifiers/esm_sideset.jpg style=float:center;width:100%; caption=The evolving sideset (green) at three different time steps
 
-!media media/userobjects/esm_nodeset.jpg style=float:center;width:100%; caption=The evolving nodeset (green) at three different time steps
+!media media/meshmodifiers/esm_nodeset.jpg style=float:center;width:100%; caption=The evolving nodeset (green) at three different time steps
 
 Nodal and integrated BCs can be applied on the moving boundary.
 
@@ -53,20 +53,20 @@ The parameter `apply_initial_conditions` defaults to true and determines whether
 
 Suppose initially there is an auxiliary variable $u=1$ everywhere inside the domain, and the variable value in subdomain 1 (blue) doubles at each time step:
 
-!listing test/tests/userobjects/element_subdomain_modifier/initial_condition.i start=[AuxVariables] end=[Executioner]
+!listing test/tests/meshmodifiers/element_subdomain_modifier/initial_condition.i start=[AuxVariables] end=[Executioner]
 
-!media media/userobjects/esm_ic.jpg style=float:center;width:100%; caption=The auxiliary variable $u$ at three different time steps
+!media media/meshmodifiers/esm_ic.jpg style=float:center;width:100%; caption=The auxiliary variable $u$ at three different time steps
 
 ## Stateful material property initialization
 
 Similarly, all stateful material properties will be re-initialized when an element changes subdomain. Suppose initially the diffusivity is $0.5$ everywhere, and the diffusivity doubles at each time step:
 
-!listing test/tests/userobjects/element_subdomain_modifier/stateful_property.i start=[Materials] end=[Executioner]
+!listing test/tests/meshmodifiers/element_subdomain_modifier/stateful_property.i start=[Materials] end=[Executioner]
 
-!media media/userobjects/esm_material.jpg style=float:center;width:100%; caption=The diffusivity at three different time steps
+!media media/meshmodifiers/esm_material.jpg style=float:center;width:100%; caption=The diffusivity at three different time steps
 
-!syntax parameters /UserObjects/CoupledVarThresholdElementSubdomainModifier
+!syntax parameters /MeshModifiers/CoupledVarThresholdElementSubdomainModifier
 
-!syntax inputs /UserObjects/CoupledVarThresholdElementSubdomainModifier
+!syntax inputs /MeshModifiers/CoupledVarThresholdElementSubdomainModifier
 
-!syntax children /UserObjects/CoupledVarThresholdElementSubdomainModifier
+!syntax children /MeshModifiers/CoupledVarThresholdElementSubdomainModifier

framework/doc/content/source/meshmodifiers/SidesetAroundSubdomainUpdater.md

@@ -0,0 +1,18 @@
+# SidesetAroundSubdomainUpdater
+
+## Description
+
+The `SidesetAroundSubdomainUpdater` mesh modifier updates a sideset during a simulation by reassigning it based on a pair of subdomain sets, the [!param](/MeshModifiers/SidesetAroundSubdomainUpdater/inner_subdomains) and [!param](/MeshModifiers/SidesetAroundSubdomainUpdater/outer_subdomains). The sideset will be updated to comprise all sides along `inner_subdomains` that are neighboring `outer_subdomains` or that have no neighbor. This dynamic update can be useful in conjunction with subdomain update user objects such as [CoupledVarThresholdElementSubdomainModifier](CoupledVarThresholdElementSubdomainModifier.md).
+
+!alert note
+Use the [!param](/MeshModifiers/SidesetAroundSubdomainUpdater/execution_order_group) parameter to ensure that this user object is run after any subdomain changing user object has fully traversed the mesh.
+
+## Example Input Syntax
+
+!listing test/tests/meshmodifiers/sideset_around_subdomain_updater/test.i block=MeshModifiers
+
+!syntax parameters /MeshModifiers/SidesetAroundSubdomainUpdater
+
+!syntax inputs /MeshModifiers/SidesetAroundSubdomainUpdater
+
+!syntax children /MeshModifiers/SidesetAroundSubdomainUpdater

framework/doc/content/source/userobjects/TimedElementSubdomainModifier.md → framework/doc/content/source/meshmodifiers/TimedElementSubdomainModifier.md

@@ -2,6 +2,6 @@
 
 ## Overview
 
-The `TimedElementSubdomainModifier` is a base class to be inherited by other user objects. It inherits
+The `TimedElementSubdomainModifier` is a base class to be inherited by other mesh modifiers. It inherits
 from `ElementSubdomainModifier` and additionally provides the ability to change elements’ subdomains
 at given times.

framework/doc/content/source/meshmodifiers/TimedSubdomainModifier.md

@@ -0,0 +1,53 @@
+# TimedSubdomainModifier
+
+!syntax description /MeshModifiers/TimedSubdomainModifier
+
+## Overview
+
+For geometrically complex models, an efficient option is to define the volumes to be excavated/backfilled by means of subdomains (aka 'blocks'). This leads to the task of moving all elements from one subdomain to another at pre-known points in time. Furthermore, in some engineering applications
+(e.g. geotechnics or mining) it might be necessary to reassign several subdomains during one simulation.
+Addressing this task, the `TimedSubdomainModifier` eases re-assignment of all elements of a subdomain, makes Moose input files shorter, and reduces
+potential sources of error compared to the usage of [CoupledVarThresholdElementSubdomainModifier.md] (which in turn has its advantages if the geometry is not organized into subdomains).
+
+The `TimedSubdomainModifier` inherits from the [CoupledVarThresholdElementSubdomainModifier.md]. Details on solution initialization, stateful material property initialization and moving boundary/interface nodeset/sideset modification can be found in the description of the [CoupledVarThresholdElementSubdomainModifier.md].
+
+The subdomains and times to be used by the `TimedSubdomainModifier` can be specified using one of the following options:
+
+- 3 vectors containing the times, source and destination subdomains/blocks, or
+- path to an CSV file
+
+## Example Input File Syntax
+
+### Vectors of data in the input file
+
+If the data on the subdomains and times should be provided directly in the input file, the following 3 parameters must be used. The vector of data in each parameter must have the same number of items:
+
+- [!param](/MeshModifiers/TimedSubdomainModifier/times): Vector of times at which the elements are to be moved.
+- [!param](/MeshModifiers/TimedSubdomainModifier/blocks_from): Vector of subdomain/blocks to move from. The subdomains/blocks may be given as ID or name.
+- [!param](/MeshModifiers/TimedSubdomainModifier/blocks_to): Vector of subdomain/blocks to move to. The subdomains/blocks may be given as ID or name.
+
+!listing test/tests/meshmodifiers/element_subdomain_modifier/tsm_direct.i block=MeshModifiers
+
+### Reading data from CSV file
+
+To read the data on the subdomains and times from an CSV file, the following parameters are to be used:
+
+- [!param](/MeshModifiers/TimedSubdomainModifier/data_file): Name of the file in which the data is read.
+- [!param](/MeshModifiers/TimedSubdomainModifier/delimiter): Optional CSV delimiter character. Defaults to comma (`,`).
+- [!param](/MeshModifiers/TimedSubdomainModifier/comment): Optional CSV comment character. Defaults to hash character (`;`).
+- [!param](/MeshModifiers/TimedSubdomainModifier/header): This parameter must be set to True, if the columns are to be found via header ([!param](/MeshModifiers/TimedSubdomainModifier/time_column_text), [!param](/MeshModifiers/TimedSubdomainModifier/blocks_from_column_text), and [!param](/MeshModifiers/TimedSubdomainModifier/blocks_to_column_text)). See following parameters.
+- [!param](/MeshModifiers/TimedSubdomainModifier/time_column_index) -or- [!param](/MeshModifiers/TimedSubdomainModifier/time_column_text): Zero-based index or name of the column defining the times.
+- [!param](/MeshModifiers/TimedSubdomainModifier/blocks_from_column_index) -or- [!param](/MeshModifiers/TimedSubdomainModifier/blocks_from_column_text): Zero-based index or name of the column defining the subdomains/blocks to move all elements from.
+- [!param](/MeshModifiers/TimedSubdomainModifier/blocks_to_column_index) -or- [!param](/MeshModifiers/TimedSubdomainModifier/blocks_to_column_text): Zero-based index or name of the column defining the subdomains/blocks to move all elements to.
+
+!listing test/tests/meshmodifiers/element_subdomain_modifier/tsm_csv.i block=MeshModifiers
+
+With the corresponding CSV-file:
+
+!listing test/tests/meshmodifiers/element_subdomain_modifier/tsm.csv
+
+!syntax parameters /MeshModifiers/TimedSubdomainModifier
+
+!syntax inputs /MeshModifiers/TimedSubdomainModifier
+
+!syntax children /MeshModifiers/TimedSubdomainModifier

framework/doc/content/source/meshmodifiers/VariableValueElementSubdomainModifier.md

@@ -0,0 +1,12 @@
+# VariableValueElementSubdomainModifier
+
+The `VariableValueElementSubdomainModifier` MeshModifier adjusts the element's subdomain according to a provided variable value. Subdomain IDs can be assigned based on the average variable value within the element, rounded to the nearest existing subdomain ID in the mesh.
+
+**Note:** If the target value is not found in the subdomain ID list, a warning will be triggered. The system will then assign the smallest subdomain ID in the mesh that matches or exceeds the target subdomain ID to the element. Alternatively, if all subdomain IDs are smaller than the target, the system will assign the largest subdomain ID available in the mesh to the element.
+
+
+!syntax parameters /MeshModifiers/VariableValueElementSubdomainModifier
+
+!syntax inputs /MeshModifiers/VariableValueElementSubdomainModifier
+
+!syntax children /MeshModifiers/VariableValueElementSubdomainModifier