CSGBase

Updating Existing CSGBase Objects

An empty CSGBase object can be initialized on its own in each generateCSG method for each mesh generator. However, in most cases, it is necessary to update an existing CSGBase object from a previous MeshGenerator or join multiple CSGBase together such that only one CSGBase object is ultimately produced at the end of the mesh/CSG generation process. There are two main ways to handle this: passing and joining.

  // get the existing CSGBase associated with the input mesh generator
  // this is the CSGBase object that will be updated
  std::unique_ptr<CSG::CSGBase> csg_obj = std::move(getCSGBase("input"));

  // Case 1: Create two CSGBase objects to join together into a single root
  // CSGBase 1: only one cell, which lives in the ROOT_UNIVERSE
  std::unique_ptr<CSGBase> base1 = std::make_unique<CSG::CSGBase>();
  std::unique_ptr<CSG::CSGSphere> surf_ptr1 = std::make_unique<CSG::CSGSphere>("s1", 1.0);
  const auto & surf1 = base1->addSurface(std::move(surf_ptr1));
  auto & c1 = base1->createCell("c1", +surf1);
  // CSGBase 2: two total unverses (ROOT_UNIVERSE and extra_univ) with a cell in each
  std::unique_ptr<CSGBase> base2 = std::make_unique<CSG::CSGBase>();
  std::unique_ptr<CSG::CSGSphere> surf_ptr2 = std::make_unique<CSG::CSGSphere>("s2", 1.0);
  const auto & surf2 = base2->addSurface(std::move(surf_ptr2));
  auto & c2 = base2->createCell("c2", +surf2);
  auto & extra_univ = base2->createUniverse("extra_univ");
  auto & c3 = base2->createCell("c3", -surf2, &extra_univ);

  // Joining: two universes will remain
  // base1 ROOT_UNIVERSE will gain all cells from base2 ROOT_UNIVERSE
  // base2 ROOT_UNIVERSE will not exist as a separate universe
  // the "extra_univ" in base2 will remain a separate universe
  base1->joinOtherBase(std::move(base2));

  // Case 2: Create two CSGBase objects to join together but keep incoming root separate
  // CSGBase 1: only one cell, which lives in the ROOT_UNIVERSE
  std::unique_ptr<CSGBase> base1 = std::make_unique<CSG::CSGBase>();
  std::unique_ptr<CSG::CSGSphere> surf_ptr1 = std::make_unique<CSG::CSGSphere>("s1", 1.0);
  const auto & surf1 = base1->addSurface(std::move(surf_ptr1));
  auto & c1 = base1->createCell("c1", +surf1);
  // CSGBase 2: two total unverses (ROOT_UNIVERSE and extra_univ) with a cell in each
  std::unique_ptr<CSGBase> base2 = std::make_unique<CSG::CSGBase>();
  std::unique_ptr<CSG::CSGSphere> surf_ptr2 = std::make_unique<CSG::CSGSphere>("s2", 1.0);
  const auto & surf2 = base2->addSurface(std::move(surf_ptr2));
  auto & c2 = base2->createCell("c2", +surf2);
  auto & extra_univ = base2->createUniverse("extra_univ");
  auto & c3 = base2->createCell("c3", -surf2, &extra_univ);

  // Joining: three universes will remain
  // base1 ROOT_UNIVERSE will remain untouched
  // all cells from ROOT_UNIVERSE in base2 create new universe called "new_univ"
  // the "extra_univ" in base2 will remain a separate universe
  std::string new_root_name = "new_univ";
  base1->joinOtherBase(std::move(base2), new_root_name);

  // Case 3: Create two CSGBase objects to join together with each root becoming a new universe
  // CSGBase 1: only one cell, which lives in the ROOT_UNIVERSE
  std::unique_ptr<CSGBase> base1 = std::make_unique<CSG::CSGBase>();
  std::unique_ptr<CSG::CSGSphere> surf_ptr1 = std::make_unique<CSG::CSGSphere>("s1", 1.0);
  const auto & surf1 = base1->addSurface(std::move(surf_ptr1));
  auto & c1 = base1->createCell("c1", +surf1);
  // CSGBase 2: two total unverses (ROOT_UNIVERSE and extra_univ) with a cell in each
  std::unique_ptr<CSGBase> base2 = std::make_unique<CSG::CSGBase>();
  std::unique_ptr<CSG::CSGSphere> surf_ptr2 = std::make_unique<CSG::CSGSphere>("s2", 1.0);
  const auto & surf2 = base2->addSurface(std::move(surf_ptr2));
  auto & c2 = base2->createCell("c2", +surf2);
  auto & extra_univ = base2->createUniverse("extra_univ");
  auto & c3 = base2->createCell("c3", -surf2, &extra_univ);

  // Joining: four universes will remain
  // all cells from base1 ROOT_UNIVERSE will be moved to a new universe called "new_univ1"
  // all cells from base2 ROOT_UNIVERSE will be moved to a new universe called "new_univ2"
  // base1 ROOT_UNIVERSE will be empty
  // the "extra_univ" in base2 will remain a separate universe
  std::string new_name1 = "new_univ1";
  std::string new_name2 = "new_univ2";
  base1->joinOtherBase(std::move(base2), new_name1, new_name2);

Accessing CSG-related Methods

All CSG methods related to creating or changing a CSG object must be called through CSGBase. Calls that retrieve information only but do not manipulate an object (such as getName methods) can be called on the object directly. For example, if a cell were to be created, the current name and region could be retrieved directly from the CSGCell object, but if the name or region needed to be changed, that would need to be handled through CSGBase.

This ensures proper accounting of all CSG-related objects in the CSGBase instance. Consult the Doxygen documentation for information on all object-specific methods.

Object Naming Recommendations

For each new CSG element (CSGSurface, CSGCell, and CSGUniverse) that is created, a unique name identifier (of type std::string) must be provided (name parameter for all creation methods). A recommended best practice is to include the mesh generator name (which can be accessed with this->getName() in any MeshGenerator class) as a part of that object name. This name is used as the unique identifier within the CSGBase instance. Methods for renaming objects are available as described in the above sections to help prevent issues and errors.

Example Implementation

Provided here is an example implementation of the generateCSG method for a simple example MeshGenerator that creates an infinite rectangular prism given an input parameter for side_length. The code snippets provided here correspond to the .C file.

InputParameters
ExampleCSGInfiniteSquareMeshGenerator::validParams()
{
  InputParameters params = MeshGenerator::validParams();

  params.addRequiredParam<Real>("side_length", "Side length of infinite square.");
  // Declare that this generator has a generateCSG method
  MeshGenerator::setHasGenerateCSG(params);
  return params;
}

ExampleCSGInfiniteSquareMeshGenerator::ExampleCSGInfiniteSquareMeshGenerator(
    const InputParameters & params)
  : MeshGenerator(params), _side_length(getParam<Real>("side_length"))
{
}

std::unique_ptr<MeshBase>
ExampleCSGInfiniteSquareMeshGenerator::generate()
{
  auto null_mesh = nullptr;
  return null_mesh;
}

std::unique_ptr<CSG::CSGBase>
ExampleCSGInfiniteSquareMeshGenerator::generateCSG()
{
  // name of the current mesh generator to use for naming generated objects
  auto mg_name = this->name();

  // initialize a CSGBase object
  auto csg_obj = std::make_unique<CSG::CSGBase>();

  // Add surfaces and halfspaces corresponding to 4 planes of infinite square
  std::vector<std::vector<Point>> points_on_planes{{Point(1. * _side_length / 2., 0., 0.),
                                                    Point(1. * _side_length / 2., 1., 0.),
                                                    Point(1. * _side_length / 2., 0., 1.)},
                                                   {Point(-1. * _side_length / 2., 0., 0.),
                                                    Point(-1. * _side_length / 2., 1., 0.),
                                                    Point(-1. * _side_length / 2., 0., 1.)},
                                                   {Point(0., 1. * _side_length / 2., 0.),
                                                    Point(1., 1. * _side_length / 2., 0.),
                                                    Point(0., 1. * _side_length / 2., 1.)},
                                                   {Point(0., -1. * _side_length / 2., 0.),
                                                    Point(1., -1. * _side_length / 2., 0.),
                                                    Point(0., -1. * _side_length / 2., 1.)}};
  std::vector<std::string> surf_names{"plus_x", "minus_x", "plus_y", "minus_y"};

  // initialize cell region to be updated
  CSG::CSGRegion region;

  // set the center of the prism to be used for determining half-spaces
  const auto centroid = Point(0, 0, 0);

  for (unsigned int i = 0; i < points_on_planes.size(); ++i)
  {
    // object name includes the mesh generator name for uniqueness
    const auto surf_name = mg_name + "_surf_" + surf_names[i];
    // create the plane for one face of the prism
    std::unique_ptr<CSG::CSGSurface> plane_ptr = std::make_unique<CSG::CSGPlane>(
        surf_name, points_on_planes[i][0], points_on_planes[i][1], points_on_planes[i][2]);
    auto & csg_plane = csg_obj->addSurface(std::move(plane_ptr));
    // determine where the plane is in relation to the centroid to be able to set the half-space
    const auto region_direction = csg_plane.getHalfspaceFromPoint(centroid);
    // half-space is either positive (+plane_ptr) or negative (-plane_ptr)
    // depending on the direction to the centroid
    auto halfspace =
        ((region_direction == CSG::CSGSurface::Halfspace::POSITIVE) ? +csg_plane : -csg_plane);
    // check if this is the first half-space to be added to the region,
    // if not, update the existing region with the intersection of the regions (&=)
    if (region.getRegionType() == CSG::CSGRegion::RegionType::EMPTY)
      region = halfspace;
    else
      region &= halfspace;
  }

  // create the cell defined by the surfaces and region just created
  const auto cell_name = mg_name + "_square_cell";
  const auto material_name = "square_material";
  csg_obj->createCell(cell_name, material_name, region);

  return csg_obj;
}

The following example builds on the infinite prism example above by taking a MeshGeneratorName for an existing ExampleCSGInfiniteSquareMeshGenerator as input and adding planes to create a finite rectangular prism.

InputParameters
TestCSGAxialSurfaceMeshGenerator::validParams()
{
  InputParameters params = MeshGenerator::validParams();
  // input parameter that is an existing mesh generator
  params.addRequiredParam<MeshGeneratorName>("input", "The input MeshGenerator.");
  // additional params for this specific mesh generator
  params.addRequiredParam<Real>("axial_height", "Axial height of the model.");
  // Declare that this generator has a generateCSG method
  MeshGenerator::setHasGenerateCSG(params);
  return params;
}

TestCSGAxialSurfaceMeshGenerator::TestCSGAxialSurfaceMeshGenerator(const InputParameters & params)
  : MeshGenerator(params),
    _mesh_ptr(getMesh("input")),
    _axial_height(getParam<Real>("axial_height"))
{
}

std::unique_ptr<MeshBase>
TestCSGAxialSurfaceMeshGenerator::generate()
{
  auto null_mesh = nullptr;
  return null_mesh;
}

std::unique_ptr<CSG::CSGBase>
TestCSGAxialSurfaceMeshGenerator::generateCSG()
{
  // get the existing CSGBase associated with the input mesh generator
  // this is the CSGBase object that will be updated
  std::unique_ptr<CSG::CSGBase> csg_obj = std::move(getCSGBase("input"));

  // get the names of the current mesh generator and the input mesh generator
  // so that unique object naming can be enforced
  auto mg_name = this->name();
  auto inp_name = getParam<MeshGeneratorName>("input");

  // get the expected existing cell
  const auto cell_name = inp_name + "_square_cell";
  const auto & csg_cell = csg_obj->getCellByName(cell_name);

  // get the existing cell region to update
  auto cell_region = csg_cell.getRegion();

  // centroid used to determine direction for half-space
  const auto centroid = Point(0, 0, 0);

  // setting a default surface name purely for testing purposes
  const auto default_surf_name = "default_surf";

  // Add surfaces and halfspaces corresponding to top and bottom axial planes
  std::vector<std::string> surf_names{"plus_z", "minus_z"};
  std::vector<Real> coeffs{0.5 * _axial_height, -0.5 * _axial_height};
  for (unsigned int i = 0; i < coeffs.size(); ++i)
  {
    // create a plane using the coefficients for the equation of a plane
    // z plane equation: 0.0*x + 0.0*y + 1.0*z = (+/-)0.5 * axial_height
    std::unique_ptr<CSG::CSGSurface> surface_ptr =
        std::make_unique<CSG::CSGPlane>(default_surf_name, 0.0, 0.0, 1.0, coeffs[i]);
    auto & csg_plane = csg_obj->addSurface(std::move(surface_ptr));

    // Rename surface so that it has a unique surface name based on the mesh generator
    const auto surf_name = mg_name + "_surf_" + surf_names[i];
    csg_obj->renameSurface(csg_plane, surf_name);

    // determine the half-space to add as an updated intersection
    const auto region_direction = csg_plane.getHalfspaceFromPoint(centroid);
    auto halfspace =
        ((region_direction == CSG::CSGSurface::Halfspace::POSITIVE) ? +csg_plane : -csg_plane);

    // update the existing region with a half-space
    cell_region &= halfspace;
  }

  // set the new region for the existing cell
  csg_obj->updateCellRegion(csg_cell, cell_region);

  // Rename cell as it now defines a box region instead of an infinite square region
  csg_obj->renameCell(csg_cell, mg_name + "_box_cell");

  return csg_obj;
}

If the above methods were to be used, the following input would generate the corresponding JSON output below.

Example Input:

[Mesh<<<{"href": "../../syntax/Mesh/index.html"}>>>]
  [inf_square]
    type = ExampleCSGInfiniteSquareMeshGenerator
    side_length = 4
  []
  [cube]
    type = TestCSGAxialSurfaceMeshGenerator
    input = inf_square
    axial_height = 5
  []
[]

Example Output:

{
  "cells": {
    "cube_box_cell": {
      "fill": "square_material",
      "filltype": "CSG_MATERIAL",
      "region":
          "(+inf_square_surf_plus_x & -inf_square_surf_minus_x & -inf_square_surf_plus_y & +inf_square_surf_minus_y & -cube_surf_plus_z & +cube_surf_minus_z)"
    }
  },
  "surfaces": {
    "inf_square_surf_minus_x": {
      "coefficients": {
        "a": -1.0,
        "b": 0.0,
        "c": 0.0,
        "d": 2.0
      },
      "type": "CSG::CSGPlane"
    },
    "inf_square_surf_minus_y": {
      "coefficients": {
        "a": 0.0,
        "b": 1.0,
        "c": 0.0,
        "d": -2.0
      },
      "type": "CSG::CSGPlane"
    },
    "cube_surf_minus_z": {
      "coefficients": {
        "a": 0.0,
        "b": 0.0,
        "c": 1.0,
        "d": -2.5
      },
      "type": "CSG::CSGPlane"
    },
    "inf_square_surf_plus_x": {
      "coefficients": {
        "a": -1.0,
        "b": 0.0,
        "c": 0.0,
        "d": -2.0
      },
      "type": "CSG::CSGPlane"
    },
    "inf_square_surf_plus_y": {
      "coefficients": {
        "a": 0.0,
        "b": 1.0,
        "c": 0.0,
        "d": 2.0
      },
      "type": "CSG::CSGPlane"
    },
    "cube_surf_plus_z": {
      "coefficients": {
        "a": 0.0,
        "b": 0.0,
        "c": 1.0,
        "d": 2.5
      },
      "type": "CSG::CSGPlane"
    }
  },
  "universes": {
    "ROOT_UNIVERSE": {
      "cells": [
        "cube_box_cell"
      ],
      "root": true
    }
  }
}

To run the above example, use --allow-test-objects:

./moose_test-opt --allow-test-objects --csg-only -i tests/csg/csg_only_chained.i