Merge pull request #27965 from Wendy-Ji/esm_moving_boundary

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

@@ -4,66 +4,27 @@
 
 ## Overview
 
-The `CoupledVarThresholdElementSubdomainModifier` can model
+The `CoupledVarThresholdElementSubdomainModifier` changes the element subdomain if a coupled variable meets a particular criterion. The `threshold` and `criterion_type` are used to determine this criterion. By default, the element changes subdomain if the averaged value of the coupled variable in the element is `above` the `threshold`. Other types of criterion are `below` and `equal` to the `threshold` value.
 
-- Element death (with applications in ablation, fracture, etc.);
-- Element activation (with applications in additive manufacturing, sintering, solidification, etc.);
-- Moving interface (with applications in metal oxidation, phase transformation, melt pool, etc.).
+The `CoupledVarThresholdElementSubdomainModifier` inherits from the [ElementSubdomainModifier.md]. Details on solution reinitialization, stateful material property reinitialization and moving boundary/interface nodeset/sideset modification can be found in the description of the [ElementSubdomainModifier.md].
 
-The `CoupledVarThresholdElementSubdomainModifier` changes the element subdomain based on the given criterion. It also handles the corresponding
+## Irreversible Modification
 
-- Moving boundary/interface nodeset/sideset modification,
-- Solution initialization, and
-- Stateful material property initialization,
+Consider a unit square domain, and an auxiliary variable defined by the function $\phi(x,y,t) = (x-t)^2+y^2-0.5^2$. The function represents a signed-distance function of a circle of radius $0.5$ whose center is moving along the x-axis towards the right.
 
-all of which are demonstrated using the following example.
+Initially, the domain is decomposed by a vertical line $x=0.25$. The elements on the left side of the vertical line have subdomain ID of 1, and the elements on the right side have subdomain ID of 2. The `CoupledVarThresholdElementSubdomainModifier` sets the coupled variable to be $\phi$, and the criterion to be `below` a `threshold` value of 0, so all the elements within the moving circle will change subdomain ID from 2 to 1:
 
-Consider a unit square domain, and an auxiliary variable defined by the function $\phi(x,y,t) = (x-t)^2+y^2-0.5^2$. The function represents a signed-distance function of a circle of radius $0.5$ whose center is moving along the x-axis towards right.
+!listing test/tests/meshmodifiers/element_subdomain_modifier/irreversible.i start=[moving_circle] end=[] include-end=true
 
-Initially, the domain is decomposed by a vertical line $x=0.25$. The elements on the left side of the vertical line have subdomain ID of 1, and the elements on the right side have subdomain ID of 2. The `CoupledVarThresholdElementSubdomainModifier` is used to change the subdomain ID from 2 to 1 for elements within the circle.
+!media large_media/mesh_modifiers/element_subdomain_modifier/irrev.png style=float:center;width:100%; caption=The result of a reversible element subdomain modifier at three different time steps
 
-## Reversible vs. irreversible modification
+## Reversible Modification
 
-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:
+The irreversible modification is useful for applications suhc as element death and activation, but the subdomain modificationan can be changed to reversible by setting the parameter `complement_subdomain_id` to 2. Then the subdomain ID of all elements outside the circle will be set to 2:
 
 !listing test/tests/meshmodifiers/element_subdomain_modifier/reversible.i start=[moving_circle] end=[] include-end=true
 
-!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/meshmodifiers/element_subdomain_modifier/block_restricted.i start=[moving_circle] end=[] include-end=true
-
-!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/meshmodifiers/esm_sideset.jpg style=float:center;width:100%; caption=The evolving sideset (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.
-
-## Solution initialization
-
-Depending on the physics, one may or may not want to initialize the solution when an element and its related nodes change subdomain.
-The parameter `apply_initial_conditions` defaults to true and determines whether the initial conditions should be re-evaluated.
-
-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/meshmodifiers/element_subdomain_modifier/initial_condition.i start=[AuxVariables] end=[Executioner]
-
-!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/meshmodifiers/element_subdomain_modifier/stateful_property.i start=[Materials] end=[Executioner]
-
-!media media/meshmodifiers/esm_material.jpg style=float:center;width:100%; caption=The diffusivity at three different time steps
+!media large_media/mesh_modifiers/element_subdomain_modifier/rev.png style=float:center;width:100%; caption=The result of a reversible element subdomain modifier at three different time steps
 
 !syntax parameters /MeshModifiers/CoupledVarThresholdElementSubdomainModifier
 

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

@@ -0,0 +1,99 @@
+# ElementSubdomainModifier
+
+## Overview
+
+The `ElementSubdomainModifier` modifies an element subdomain ID. This class is inherited by other mesh modifiers, such as [CoupledVarThresholdElementSubdomainModifier.md] and [TimedSubdomainModifier.md], which implement different criteria for a subdomain ID to be modified.
+
+The `ElementSubdomainModifier` can model
+
+- Element death (with applications in ablation, fracture, etc.);
+- Element activation (with applications in additive manufacturing, sintering, solidification, etc.);
+- Moving interface (with applications in metal oxidation, phase transformation, melt pool, etc.).
+
+The `ElementSubdomainModifier` only changes the element's subdomain. It inherits from `ElementSubdomainModifierBase`, which handles the corresponding
+
+- Moving boundary/interface nodeset/sideset modification,
+- Solution reinitialization, and
+- Stateful material property reinitialization,
+
+all of which are demonstrated below.
+
+Consider a unit square domain decomposed by a vertical line $x=0.25$. The elements on the left side of the vertical line have subdomain ID of 1, and the elements on the right side have subdomain ID of 2. The `ElementSubdomainModifier` is used to change the subdomain ID from 2 to 1 for elements within a circle of radius 0.5 whose center moves along the bottom side towards the right.
+
+## Moving boundary/interface nodeset/sideset modification
+
+!alert note
+If the moving boundary is defined completely around a subdomain, or between subdomains, then [SidesetAroundSubdomainUpdater.md] may be more useful to use in conjunction with the `ElementSubdomainModifier`, rather than using the `moving_boundaries` and `moving_boundary_subdomain_pairs` parameters in `ElementSubdomainModifier`.
+
+The change of element subdomains will alter the definitions of certain sidesets and nodesets. The parameters `moving_boundaries` and `moving_boundary_subdomain_pairs` can optionally be used to modify the corresponding sidesets/nodesets over the elements that change subdomain. The names of the boundaries are specified in `moving_boundaries`, and the pair of subdomains that each boundary in `moving_boundaries` lies between must be specified in the corresponding `moving_boundary_subdomain_pairs`. The element side from the first subdomain of the pair is added to the boundary.
+
+If the boundaries provided through `moving_boundaries` already exist, the modifier will attempt to modify the provided sidesets/nodesets whenever an element changes subdomain ID. If the boundaries do not exist, the modifier will create sidesets and nodesets with the provided names.
+
+!listing test/tests/meshmodifiers/element_subdomain_modifier/moving_boundary.i start=[moving_circle] end=[] include-end=true
+
+!media large_media/mesh_modifiers/element_subdomain_modifier/nodeset.png style=float:center;width:100%; caption=The evolving nodeset (green) between subdomains 1 and 2, as created by the modifier without an existing boundary. 
+
+The modifier only creates and modifies boundaries over elements that change subdomain, so the vertical boundary between subdomains 1 and 2 at $x=0.25$ is not added to the created boundary. 
+
+If only one boundary is provided but multiple pairs of subdomains are specified, then all the pairs are applied to the one boundary. Element sides on a subdomain's external boundary can also be added by specifying only one subdomain.
+
+!listing test/tests/meshmodifiers/element_subdomain_modifier/external_moving_boundary.i start=[ext] end=[AuxVariables] include-end=false
+
+!media large_media/mesh_modifiers/element_subdomain_modifier/ext.png style=float:center;width:100%; caption=The evolving sideset (green) around subdomain 1, including the external element sides, from an existing boundary.
+
+Since the update of the moving boundary only occurs over elements that change subdomain, this can be used to update boundaries which do not cover the entirety of a subdomain:
+
+!listing test/tests/meshmodifiers/element_subdomain_modifier/partial_moving_boundary.i start=[moving_circle] end=[] include-end=true
+
+!media large_media/mesh_modifiers/element_subdomain_modifier/partial.png style=float:center;width:100%; caption=The evolving sideset (green) around subdomain 1, including the external element sides, from an existing boundary.
+
+
+Even though the `moving_boundary_subdomain_pairs` defines the moving boundary to be between subdomains 1 and 2 only, the right side of subdomain 2 remains throughout, as no element sides belong to elements that change subdomain.
+
+Nodal and integrated BCs can be applied on the moving boundary.
+
+## Solution reinitialization
+
+By default, all elements that change subdomain ID are reinitialized to the new subdomain's initial condition. Suppose the auxiliary variable $u$ has an initial variable value of $1$ in subdomain 1 and $-0.5$ in subdomain 2, and the variable value doubles at each timestep in subdomain 1:
+
+!listing test/tests/meshmodifiers/element_subdomain_modifier/initial_condition.i start=[ICs] end=[Postprocessors]
+
+!media large_media/mesh_modifiers/element_subdomain_modifier/init_cond.png style=float:center;width:100%; caption=The auxiliary variable $u$ is reinitialized to $1$, which doubles over the timestep to $2$, for all the elements that change subdomain ID to 1
+
+## Stateful material property reinitialization
+
+Similarly, all stateful material properties will be re-initialized when an element changes subdomain ID. Suppose initially the diffusivity is $0.5$ in subdomain 1 and $-1$ in subdomain 2, and the diffusivity doubles at each time step in subdomain 1:
+
+!listing test/tests/meshmodifiers/element_subdomain_modifier/stateful_property.i start=[Materials] end=[Executioner]
+
+!media large_media/mesh_modifiers/element_subdomain_modifier/stateful_prop.png style=float:center;width:100%; caption=The diffusivity is reinitialized to $0.5$, which doubles over the timestep to $1$, for all the elements that change subdomain ID to 1.
+
+## Reinitialization restrictions
+
+Depending on the physics, one may or may not want to reinitialize the solution when an element and its related nodes change subdomain ID. For the below examples, consider a unit square domain decomposed by vertical lines $x=0.3$ and $x=0.6$. The elements on the left have subdomain ID of 1, the elements in the middle have subdomain ID of 2, and the elements on the right have subdomain ID of 3.
+
+The `ElementSubdomainModifier` is used to change the subdomain ID to 1 for elements within a circle of radius 0.3 whose center moves along the bottom side towards the right, and to subdomain ID 2 for elements within a circle of radius 0.3 whose center moves along the top side towards the right.
+
+An auxiliary variable $u$ is defined over the domain, with initial values of 1, 2, and 3 in subdomains 1, 2, and 3 respectively:
+
+!listing test/tests/meshmodifiers/element_subdomain_modifier/reinitialization.i start=[MeshModifiers] end=[AuxVariables]
+
+!media large_media/mesh_modifiers/element_subdomain_modifier/orig.png style=float:center;width:100%; caption=The default behaviour of the modifier is to reinitializate all elements that change subdomain ID.
+
+However, if a list of subdomains (IDs or names) is provided through the parameter `reinitialize_subdomains`, the reinitialization only occurs if the element's new subdomain ID is in the provided list:
+
+!listing test/tests/meshmodifiers/element_subdomain_modifier/reinitialization_into.i start=[MeshModifiers] end=[AuxVariables]
+
+!media large_media/mesh_modifiers/element_subdomain_modifier/into.png style=float:center;width:100%; caption=Reinitialization of only the elements that change subdomain ID to 1.
+
+If an empty list is given in `reinitialize_subdomains`, then there is no reinitialization of any elements that change subdomain ID.
+
+!listing test/tests/meshmodifiers/element_subdomain_modifier/no_reinitialization.i start=[MeshModifiers] end=[AuxVariables]
+
+!media large_media/mesh_modifiers/element_subdomain_modifier/none.png style=float:center;width:100%; caption=No reinitialization of any elements that change subdomain ID.
+
+Reinitialization can be further restricted by setting the parameter `old_subdomain_reinitialized` to `false`. The modifier will then additionally check the element's old subdomain ID. Reinitialization then only occurs if the old subdomain ID was not in the list provided in the parameter `reinitialize_subdomains`.
+
+!listing test/tests/meshmodifiers/element_subdomain_modifier/reinitialization_from_into.i start=[MeshModifiers] end=[AuxVariables]
+
+!media large_media/mesh_modifiers/element_subdomain_modifier/from_into.png style=float:center;width:100%; caption=Reinitialization of only the elements which change subdomain ID from 3, to subdomain IDs 1 or 2

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

@@ -9,7 +9,7 @@ For geometrically complex models, an efficient option is to define the volumes t
 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 `TimedSubdomainModifier` inherits from the [ElementSubdomainModifier.md]. Details on solution reinitialization, stateful material property reinitialization and moving boundary/interface nodeset/sideset modification can be found in the description of the [ElementSubdomainModifier.md].
 
 The subdomains and times to be used by the `TimedSubdomainModifier` can be specified using one of the following options: