Misc fixups:

- remove all caps variables - avoid overlapping names for sidesets and blocks - clearer docs - more docstrings refs idaholab#20880
RocksSavage · Nov 2, 2022 · 3f6734d · 3f6734d
1 parent 924d249
commit 3f6734d
Show file tree

Hide file tree

Showing 4 changed files with 57 additions and 72 deletions.
diff --git a/framework/doc/content/source/meshgenerators/SideSetExtruderGenerator.md b/framework/doc/content/source/meshgenerators/SideSetExtruderGenerator.md
@@ -2,61 +2,45 @@
 
 !syntax description /Mesh/SideSetExtruderGenerator
 
-## Overview
+The `SideSetExtruderGenerator` differs from the [MeshExtruderGenerator](MeshExtruderGenerator.md) in that the extruded
+block has the same dimensionality as the input mesh.
 
-The SideSetExtruder Generator is for "pulling" mesh in a direction. Given a sideset and a direction(vector), it adds to the mesh. SideSetExtruder differs from [MeshExtruderGenerator](MeshExtruderGenerator.md) in that the extrusion stays in the same dimension as the sideset it is pulling on (MeshExtruderGenerator is for pulling 2 dimensional shapes into 3 dimensions). 
+!alert note
+The `SideSetExtruderGenerator` will not throw any errors if you extrude a mesh through (overlap with) another mesh or
+another part of the mesh. It will throw an error if the extrusion vector would create a mesh with a negative determinant
+(the nested [MeshExtruderGenerator](MeshExtruderGenerator.md) throws the error).
 
-SideSetExtruder will not throw any errors if you extrude a mesh through (collide with) another mesh. It will throw an error if the extrusion vector would create a mesh with a negative determinant (or rather, [MeshExtruderGenerator](MeshExtruderGenerator.md) throws the error). The extrusion vector is applied relative to the sideset given, not from the origin point of the mesh. The extrusion vector must be a 3D vector even if you are only extruding a 2D mesh; in such a case, let the z component be 0 (e.g., `extrusion_vector = '1 0.5 0'`)
-
-The output will have no sidesets, even the sideset you extruded from will be gone. The user is expected to use the other side-set generating generators on the output if sidesets are needed. 
+!alert warning
+The output will have no sidesets, even the sideset which served for extrusion will be removed.
+The user is expected to use the other sideset generating generators on the output if sidesets are needed. 
 
 ## Visual Example
 
-### Input 2D Mesh
+The following 2D mesh has the `right` sideset extruded using a `SideSetExtruderGenerator` with the (1, 0.5, 0) vector.
 
 !media large_media/framework/meshgenerators/sideset_extruder_before.png caption=Before: a square, with sidesets on each side.
 
-### Output of SideSetExtruderGenerator
-
-!media large_media/framework/meshgenerators/sideset_extruder_after.png caption=After, the right sideset has been extruded in the < 1, 0.5, 0> direction.
-
-SideSetExtruderGenerator is actually a mere wrapper of 4 other generators: [LowerDBlockFromSidesetGenerator](LowerDBlockFromSidesetGenerator.md), [BlockToMeshConverterGenerator](BlockToMeshConverterGenerator.md), [MeshExtruderGenerator](MeshExtruderGenerator.md), and [StitchedMeshGenerator](StitchedMeshGenerator.md). SideSetExtruderGenerator's output from the example above is exactly equivalent to the output of a recipe like this:
-
-```
-[Mesh]
-  [square]
-    type = GeneratedMeshGenerator
-    dim = 2
-  []
-  [lowerDblock]
-    type = LowerDBlockFromSidesetGenerator
-    input = square
-    new_block_name = "extrusions0"
-    sidesets = "right"
-  []
-  [separateMesh]
-    type = BlockToMeshConverterGenerator
-    input = lowerDblock
-    target_blocks = extrusions0
-  []
-  [extrude]
-    type = MeshExtruderGenerator
-    input = separateMesh
-    num_layers = 3
-    extrusion_vector = '1 0.5 0'
-    bottom_sideset = 'new_bottom'
-    top_sideset = 'new_top'
-  []
-  [stitch]
-    type = StitchedMeshGenerator
-    inputs = 'square extrude'
-    stitch_boundaries_pairs = 'right new_bottom'
-  []
-[]
-
-```
-
-If you are needing to tweak the output of SideSetExtruderGenerator, you may be better off manually running these operations instead. SideSetExtruderGenerator uses the defaults of these sub-generators. 
+!media large_media/framework/meshgenerators/sideset_extruder_after.png caption=After, the right sideset has been extruded.
+
+## Implementation details
+
+SideSetExtruderGenerator is actually a mere wrapper of 4 other generators:
+
+- a [LowerDBlockFromSidesetGenerator](LowerDBlockFromSidesetGenerator.md) to generate a block from the sideset
+- a [BlockToMeshConverterGenerator](BlockToMeshConverterGenerator.md) to generate a block with the mesh
+- a [MeshExtruderGenerator](MeshExtruderGenerator.md) to extrude the new mesh
+- a [StitchedMeshGenerator](StitchedMeshGenerator.md) to stitch the original mesh and the extruded mesh.
+
+
+As such, the `SideSetExtruderGenerator` is exactly equivalent to the output of a recipe similar to the one below.
+If you are needing to tweak the output of `SideSetExtruderGenerator`, it may be preferrable to use these generators
+instead. `SideSetExtruderGenerator` uses the default parameters of these sub-generators. 
+
+!listing test/tests/meshgenerators/sideset_extruder_generator/extrude_square.i
+
+The input above should be equivalent to the input shown below.
+
+!listing test/tests/meshgenerators/sideset_extruder_generator/external_generators.i
 
 !syntax parameters /Mesh/SideSetExtruderGenerator
 

diff --git a/framework/include/meshgenerators/SideSetExtruderGenerator.h b/framework/include/meshgenerators/SideSetExtruderGenerator.h
@@ -10,11 +10,10 @@
 #pragma once
 
 #include "MeshGenerator.h"
-
 #include "libmesh/mesh_generation.h"
 
 /**
- * Extrude a 1D, 2D, or 3D mesh outward within the same dimension
+ * Extrude a sideset from a mesh in a given direction
  */
 class SideSetExtruderGenerator : public MeshGenerator
 {
@@ -26,11 +25,18 @@ class SideSetExtruderGenerator : public MeshGenerator
   std::unique_ptr<MeshBase> generate() override;
 
 protected:
-  /// Mesh that comes from another generator
+  /// Mesh generated from each sub-generator
   std::unique_ptr<MeshBase> * _build_mesh;
 
+  /// Name of the base mesh containing the sideset to extruded
   const MeshGeneratorName _original_input;
+
+  /// Extrusion vector containing both the direction and the magnitude of the sideset extrusion
   const RealVectorValue _extrusion_vector;
+
+  /// Number of element layers in the direction of the extrusion when extruding
   const unsigned int _num_layers;
+
+  /// Name of the sideset to extrude
   const BoundaryName _sideset_name;
 };
diff --git a/framework/src/meshgenerators/SideSetExtruderGenerator.C b/framework/src/meshgenerators/SideSetExtruderGenerator.C
@@ -17,16 +17,14 @@ SideSetExtruderGenerator::validParams()
 {
   InputParameters params = MeshGenerator::validParams();
 
-  params.addClassDescription("Takes a 1D or 2D mesh and extrudes the entire structure along the "
-                             "specified axis increasing the dimensionality of the mesh.");
+  params.addClassDescription("Takes a 1D or 2D mesh and extrudes a selected sideset along the "
+                             "specified axis.");
 
-  // list params
   params.addRequiredParam<MeshGeneratorName>("input", "The mesh we want to modify");
   params.addRequiredParam<RealVectorValue>("extrusion_vector",
-                                           "The direction and length of the extrusion");
+                                           "The direction and length of the extrusion as a vector");
   params.addParam<unsigned int>("num_layers", 1, "The number of layers in the extruded mesh");
-  params.addRequiredParam<BoundaryName>("sideset",
-                                        "The side set (boundary) that will be extruded from");
+  params.addRequiredParam<BoundaryName>("sideset", "The sideset (boundary) that will be extruded");
 
   return params;
 }
@@ -38,19 +36,18 @@ SideSetExtruderGenerator::SideSetExtruderGenerator(const InputParameters & param
     _num_layers(getParam<unsigned int>("num_layers")),
     _sideset_name(getParam<BoundaryName>("sideset"))
 {
-  // constants needed only temporarily
-  const BoundaryName _EXTRUDED_BLOCK_NAME = "extruded_block";
-  const BoundaryName _SIDESET_TO_BE_STITCHED = "to_be_stitched";
+  const SubdomainName extruded_block_name = "extruded_block_" + name();
+  const BoundaryName sideset_to_stitch = "to_be_stitched_" + name();
 
   // sub generators
   {
     auto params = _app.getFactory().getValidParams("LowerDBlockFromSidesetGenerator");
 
     params.set<MeshGeneratorName>("input") = _original_input;
-    params.set<SubdomainName>("new_block_name") = _EXTRUDED_BLOCK_NAME;
+    params.set<SubdomainName>("new_block_name") = extruded_block_name;
     params.set<std::vector<BoundaryName>>("sidesets") = {_sideset_name};
 
-    // generate lower dimensional mesh from the given sidesets
+    // generate lower dimensional mesh from the given sideset
     _build_mesh = &addMeshSubgenerator(
         "LowerDBlockFromSidesetGenerator", name() + "_lowerDgeneration", params);
   }
@@ -59,7 +56,7 @@ SideSetExtruderGenerator::SideSetExtruderGenerator(const InputParameters & param
     auto params = _app.getFactory().getValidParams("BlockToMeshConverterGenerator");
 
     params.set<MeshGeneratorName>("input") = name() + "_lowerDgeneration";
-    params.set<std::vector<SubdomainName>>("target_blocks") = {_EXTRUDED_BLOCK_NAME};
+    params.set<std::vector<SubdomainName>>("target_blocks") = {extruded_block_name};
 
     // convert lower dimensional block to a separate mesh
     _build_mesh =
@@ -72,7 +69,7 @@ SideSetExtruderGenerator::SideSetExtruderGenerator(const InputParameters & param
     params.set<MeshGeneratorName>("input") = name() + "_blockToMesh";
     params.set<RealVectorValue>("extrusion_vector") = _extrusion_vector;
     params.set<unsigned int>("num_layers") = _num_layers;
-    params.set<std::vector<BoundaryName>>("bottom_sideset") = {_SIDESET_TO_BE_STITCHED};
+    params.set<std::vector<BoundaryName>>("bottom_sideset") = {sideset_to_stitch};
 
     // extrude the new, separate mesh into a higher dimension
     _build_mesh = &addMeshSubgenerator("MeshExtruderGenerator", name() + "_extruder", params);
@@ -86,7 +83,7 @@ SideSetExtruderGenerator::SideSetExtruderGenerator(const InputParameters & param
     params.set<std::vector<MeshGeneratorName>>("inputs") = {_original_input, name() + "_extruder"};
 
     params.set<std::vector<std::vector<std::string>>>("stitch_boundaries_pairs") = {
-        {_sideset_name, _SIDESET_TO_BE_STITCHED}};
+        {_sideset_name, sideset_to_stitch}};
 
     // stitch the newly made high-dimensional mesh back to the original mesh
     _build_mesh = &addMeshSubgenerator("StitchedMeshGenerator", name() + "_stitched", params);
@@ -96,5 +93,5 @@ SideSetExtruderGenerator::SideSetExtruderGenerator(const InputParameters & param
 std::unique_ptr<MeshBase>
 SideSetExtruderGenerator::generate()
 {
-  return dynamic_pointer_cast<MeshBase>(*_build_mesh);
+  return std::move(*_build_mesh);
 }
diff --git a/test/tests/meshgenerators/sideset_extruder_generator/tests b/test/tests/meshgenerators/sideset_extruder_generator/tests
@@ -6,17 +6,15 @@
     requirement = 'The system shall have the capability of extruding the sideset of a mesh '
                   'in a given direction'
 
-    [control]
+    [check_explicit_subgenerators]
       type = 'Exodiff'
       input = 'external_generators.i'
       exodiff = 'external_generators_in.e'
       recover = false
       mesh_mode = 'REPLICATED'
       cli_args = '--mesh-only'
 
-      detail = 'SideSetExtruderGenerator is essentially just a wrapper for 4 other generators used in sequence. 
-      The output of the 4 other generators should be identical to SideSetExtruderGenerator, or SideSetExtruderGenerator
-      has changed behavior'
+      detail = 'and the output of the SideSetExtruderGenerator should match the equivalent sequence of mesh generators'
     []
     [square]
       type = 'Exodiff'
@@ -26,7 +24,7 @@
       mesh_mode = 'REPLICATED'
       cli_args = '--mesh-only'
 
-      detail = 'A simple case, extruding the right side of a square out at an upward angle'
+      detail = 'in a simple case, extruding the right side of a square out at an upward angle'
     []
     [cube]
       type = 'Exodiff'
@@ -36,7 +34,7 @@
       mesh_mode = 'REPLICATED'
       cli_args = '--mesh-only'
 
-      detail = 'Extruding the top side of a cube out a side-ways angle'
+      detail = 'when extruding the top side of a cube in a direction not normal to the sideset'
     []
     [multiblock]
       type = 'Exodiff'
@@ -46,7 +44,7 @@
       mesh_mode = 'REPLICATED'
       cli_args = '--mesh-only'
 
-      detail = 'extruding an entangled block in a complicated 3d geomitry'
+      detail = 'extruding an entangled block in a complicated 3d geometry'
     []
   []
 []