Data Fields

Methods

{
  "name": "SubsetTopologicalMapping",
  "namespace": "sofa::component::topology::mapping",
  "module": "Sofa.Component.Topology.Mapping",
  "include": "sofa/component/topology/mapping/SubsetTopologicalMapping.h",
  "doc": "TopologicalMapping where the destination topology is a subset of the source topology. The implementation currently assumes that both topologies have been initialized correctly.\n\nThis class is a specific implementation of TopologicalMapping where the destination topology should be kept identical to the source topology.\nThe implementation currently assumes that both topology have been initialized identically.",
  "inherits": [
    "TopologicalMapping"
  ],
  "templates": [],
  "data_fields": [
    {
      "name": "d_samePoints",
      "type": "bool",
      "xmlname": "samePoints",
      "help": "True if the same set of points is used in both topologies"
    },
    {
      "name": "d_handleEdges",
      "type": "bool",
      "xmlname": "handleEdges",
      "help": "True if edges events and mapping should be handled"
    },
    {
      "name": "d_handleTriangles",
      "type": "bool",
      "xmlname": "handleTriangles",
      "help": "True if triangles events and mapping should be handled"
    },
    {
      "name": "d_handleQuads",
      "type": "bool",
      "xmlname": "handleQuads",
      "help": "True if quads events and mapping should be handled"
    },
    {
      "name": "d_handleTetrahedra",
      "type": "bool",
      "xmlname": "handleTetrahedra",
      "help": "True if tetrahedra events and mapping should be handled"
    },
    {
      "name": "d_handleHexahedra",
      "type": "bool",
      "xmlname": "handleHexahedra",
      "help": "True if hexahedra events and mapping should be handled"
    },
    {
      "name": "d_pointS2D",
      "type": "SetIndex",
      "xmlname": "pointS2D",
      "help": "Internal source -> destination topology points map"
    },
    {
      "name": "d_pointD2S",
      "type": "SetIndex",
      "xmlname": "pointD2S",
      "help": "Internal destination -> source topology points map (link to SubsetMapping::indices to handle the mechanical-side of the mapping"
    },
    {
      "name": "d_edgeS2D",
      "type": "SetIndex",
      "xmlname": "edgeS2D",
      "help": "Internal source -> destination topology edges map"
    },
    {
      "name": "d_edgeD2S",
      "type": "SetIndex",
      "xmlname": "edgeD2S",
      "help": "Internal destination -> source topology edges map"
    },
    {
      "name": "d_triangleS2D",
      "type": "SetIndex",
      "xmlname": "triangleS2D",
      "help": "Internal source -> destination topology triangles map"
    },
    {
      "name": "d_triangleD2S",
      "type": "SetIndex",
      "xmlname": "triangleD2S",
      "help": "Internal destination -> source topology triangles map"
    },
    {
      "name": "d_quadS2D",
      "type": "SetIndex",
      "xmlname": "quadS2D",
      "help": "Internal source -> destination topology quads map"
    },
    {
      "name": "d_quadD2S",
      "type": "SetIndex",
      "xmlname": "quadD2S",
      "help": "Internal destination -> source topology quads map"
    },
    {
      "name": "d_tetrahedronS2D",
      "type": "SetIndex",
      "xmlname": "tetrahedronS2D",
      "help": "Internal source -> destination topology tetrahedra map"
    },
    {
      "name": "d_tetrahedronD2S",
      "type": "SetIndex",
      "xmlname": "tetrahedronD2S",
      "help": "Internal destination -> source topology tetrahedra map"
    },
    {
      "name": "d_hexahedronS2D",
      "type": "SetIndex",
      "xmlname": "hexahedronS2D",
      "help": "Internal source -> destination topology hexahedra map"
    },
    {
      "name": "d_hexahedronD2S",
      "type": "SetIndex",
      "xmlname": "hexahedronD2S",
      "help": "Internal destination -> source topology hexahedra map"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "updateTopologicalMappingTopDown",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "isTheOutputTopologySubdividingTheInputOne",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getGlobIndex",
      "return_type": "Index",
      "params": [
        {
          "name": "ind",
          "type": "Index"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getFromIndex",
      "return_type": "Index",
      "params": [
        {
          "name": "ind",
          "type": "Index"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `SubsetTopologicalMapping` class is part of the SOFA framework and inherits from `sofa::core::topology::TopologicalMapping`. This mapping is designed to handle scenarios where the destination topology (the target) is a subset of the source topology (input). The key purpose of this component is to ensure that topological changes in the source are correctly translated into the destination, which can be more sparse or contain fewer elements than the source. This is particularly useful for simulating multi-resolution models where some parts of the geometry require finer detail while others do not.\n\nThe class contains several boolean data fields (`d_samePoints`, `d_handleEdges`, etc.) that control whether certain topological elements (points, edges, triangles, quads, tetrahedra, hexahedra) should be considered in the mapping process. These settings allow for flexible handling of different types of topological changes.\n\nThere are also several internal mappings stored as `SetIndex` fields (`d_pointS2D`, `d_pointD2S`, etc.) that maintain correspondences between elements in the source and destination topologies. The initialization method (`init`) and update methods (`updateTopologicalMappingTopDown`) manage these mappings to ensure correct correspondence during simulation.\n\nIn practical usage, users should configure the component with appropriate data fields to specify which types of topology changes should be handled. For example, setting `handleEdges` to true would enable handling edge-related topological events.",
  "maths": "### Mathematical and Physical Description of `SubsetTopologicalMapping`\n\n#### Governing Equations and Operators\n\nThe `SubsetTopologicalMapping` class does not directly implement any governing equations or operators such as the mass matrix $M$, stiffness matrix $K$, internal force vector $f_{int}$, or residual vector $R$. Instead, it focuses on maintaining topological consistency between a source mesh (input) and a destination mesh (output), where the destination is a subset of the source. The primary role of this component is to handle topological changes in such a way that these changes are correctly translated from the source to the destination.\n\n#### Constitutive or Kinematic Laws Involved\n\nThe `SubsetTopologicalMapping` class does not involve any constitutive laws (e.g., hyperelastic potentials, stress-strain relationships). Instead, it deals with kinematic mappings between different levels of mesh resolution. The primary operation is the mapping of topological elements such as points, edges, triangles, quads, tetrahedra, and hexahedra from a higher-resolution source topology to a lower-resolution destination topology.\n\n#### Role in Global FEM Pipeline\n\nWithin the broader context of the Finite Element Method (FEM) pipeline, `SubsetTopologicalMapping` plays a crucial role during the discretization phase. Specifically:\n\n1. **Discretization Phase**\n   - The class ensures that any topological changes made to the source mesh are appropriately reflected in the destination mesh.\n\n2. **Assembly Phase**\n   - The mappings created by `SubsetTopologicalMapping` ensure that contributions from different elements (e.g., internal forces, constraints) can be correctly assembled into global operators such as $M$ and $K$. This ensures consistency between the source and destination topologies during assembly.\n\n3. **Time Integration**\n   - The mapping is used to transfer state variables like displacements and velocities from the source topology to the destination topology, ensuring that the simulation remains consistent across different levels of resolution.\n\n4. **Nonlinear Resolution**\n   - During nonlinear solution steps, the mappings ensure that any corrections or updates made in one topology are correctly applied to the other.\n\n#### Numerical Methods and Discretization Choices\n\nThe class does not directly discretize PDEs but rather handles the mapping of topological changes. The numerical methods used include:\n\n- **Mapping Initialization** (`init` method):\n  - This initializes mappings between corresponding points, edges, triangles, quads, tetrahedra, and hexahedra in the source and destination topologies.\n\n- **Topological Change Handling** (`updateTopologicalMappingTopDown` method):\n  - The class processes various types of topological changes (e.g., adding or removing points, edges, triangles) and ensures these are consistently applied to both the source and destination meshes.\n\n#### How It Fits into the Broader Variational / Lagrangian Mechanics Framework\n\nIn the context of variational mechanics and Lagrangian dynamics, the `SubsetTopologicalMapping` class plays a supporting role in ensuring that topologies remain consistent across different resolutions. This consistency is crucial for maintaining physical fidelity during simulation:\n\n- **Consistency**: By maintaining mappings between elements in different topologies, this component ensures that any state updates (e.g., displacements) are correctly transferred from the source to the destination topology.\n\n- **Topological Consistency**: Ensures that operations such as adding or removing points and edges in one mesh are consistently applied in another, which is essential for multi-resolution simulations where different parts of a model may require varying levels of detail.\n\n### Summary\nThe `SubsetTopologicalMapping` class is primarily focused on maintaining topological consistency between source and destination meshes. It does not directly contribute to the governing equations or operators typically associated with FEM but instead ensures that these equations can be consistently applied across different resolutions, thereby supporting more flexible and efficient simulation scenarios.",
  "abstract": "The `SubsetTopologicalMapping` component manages topological mappings where the destination topology is a subset of the source topology, ensuring consistency between different levels of mesh resolution.",
  "sheet": "# SubsetTopologicalMapping\n\n## Overview\n\nThe `SubsetTopologicalMapping` class handles scenarios where the destination topology (target) is a subset of the source topology (input). It ensures that topological changes in the source are correctly translated into the destination, which can be more sparse or contain fewer elements than the source. This component inherits from `sofa::core::topology::TopologicalMapping` and plays a crucial role in maintaining consistency between different levels of mesh resolution.\n\n## Parameters and Data\n\nThe significant data fields exposed by this component control whether certain topological elements should be considered in the mapping process:\n\n- **samePoints**: `bool`, default unspecified. True if the same set of points is used in both topologies.\n- **handleEdges**: `bool`, default unspecified. True if edges events and mapping should be handled.\n- **handleTriangles**: `bool`, default unspecified. True if triangles events and mapping should be handled.\n- **handleQuads**: `bool`, default unspecified. True if quads events and mapping should be handled.\n- **handleTetrahedra**: `bool`, default unspecified. True if tetrahedra events and mapping should be handled.\n- **handleHexahedra**: `bool`, default unspecified. True if hexahedra events and mapping should be handled.\n\nInternal mappings are stored as `SetIndex` fields to maintain correspondences between elements in the source and destination topologies:\n\n- **pointS2D**: Internal source -> destination topology points map.\n- **pointD2S**: Internal destination -> source topology points map (linked to SubsetMapping::indices for mechanical-side handling).\n- **edgeS2D**: Internal source -> destination topology edges map.\n- **edgeD2S**: Internal destination -> source topology edges map.\n- **triangleS2D**: Internal source -> destination topology triangles map.\n- **triangleD2S**: Internal destination -> source topology triangles map.\n- **quadS2D**: Internal source -> destination topology quads map.\n- **quadD2S**: Internal destination -> source topology quads map.\n- **tetrahedronS2D**: Internal source -> destination topology tetrahedra map.\n- **tetrahedronD2S**: Internal destination -> source topology tetrahedra map.\n- **hexahedronS2D**: Internal source -> destination topology hexahedra map.\n- **hexahedronD2S**: Internal destination -> source topology hexahedra map.\n\n## Dependencies and Connections\n\nThis component typically requires a `TopologicalMapping` parent class to function correctly. It fits into the scene graph by ensuring that topological changes in the source mesh are consistently applied to the destination mesh, which is a subset of the source."
}