Data Fields

Methods

{
  "name": "SparseGridRamificationTopology",
  "namespace": "sofa::component::topology::container::grid",
  "module": "Sofa.Component.Topology.Container.Grid",
  "include": "sofa/component/topology/container/grid/SparseGridRamificationTopology.h",
  "doc": "Sparse grid in 3D (modified).\n\na SparseGridTopology where each resulting cube contains only one independent connexe component (nodes can be multiplied by using virtual nodes)",
  "inherits": [
    "SparseGridTopology"
  ],
  "templates": [],
  "data_fields": [
    {
      "name": "d_finestConnectivity",
      "type": "bool",
      "xmlname": "finestConnectivity",
      "help": "Test for connectivity at the finest level? (more precise but slower by testing all intersections between the model mesh and the faces between boundary cubes)"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "findCube",
      "description": "Finds the cube (hexahedron) containing a given point in space, returning its index along with fractional offsets within that cube. This function is overridden from SparseGridTopology to work with the ramification structure.",
      "parameters": [
        {
          "type": "const type::Vec3 &",
          "name": "pos",
          "description": "The position (coordinates) of the point in space."
        },
        {
          "type": "SReal &",
          "name": "fx",
          "description": "Fractional offset along the x-axis."
        },
        {
          "type": "SReal &",
          "name": "fy",
          "description": "Fractional offset along the y-axis."
        },
        {
          "type": "SReal &",
          "name": "fz",
          "description": "Fractional offset along the z-axis."
        }
      ],
      "returns": {
        "type": "Index",
        "description": "The index of the cube containing the point, or -1 if not found."
      }
    },
    {
      "name": "findNearestCube",
      "description": "Identifies the nearest cube to a given point and returns its index along with fractional offsets. This function also overrides functionality from SparseGridTopology.",
      "parameters": [
        {
          "type": "const type::Vec3&",
          "name": "pos",
          "description": "The position (coordinates) of the point in space."
        },
        {
          "type": "SReal&",
          "name": "fx",
          "description": "Fractional offset along the x-axis."
        },
        {
          "type": "SReal &",
          "name": "fy",
          "description": "Fractional offset along the y-axis."
        },
        {
          "type": "SReal &",
          "name": "fz",
          "description": "Fractional offset along the z-axis."
        }
      ],
      "returns": {
        "type": "Index",
        "description": "The index of the nearest cube, or -1 if no cubes exist within the grid."
      }
    },
    {
      "name": "printNeighborhood",
      "description": "A debugging function that prints out information about the neighborhood connections between hexahedra in the topology."
    },
    {
      "name": "changeIndices",
      "description": "When connecting similar particles between neighboring cubes, this method propagates changes to all instances of those particles within the grid structure."
    }
  ],
  "description": "The SparseGridRamificationTopology is a specialized version of the SparseGridTopology, specifically designed to handle complex topological structures where each resulting cube (hexahedron) contains only one independent connected component. This allows for more intricate modeling by potentially duplicating nodes to create separate connections within the grid structure.",
  "parameters": [
    {
      "name": "d_finestConnectivity",
      "type": "bool",
      "description": "A flag indicating whether connectivity tests should be performed at the finest level of detail. This provides greater precision but can significantly slow down the process as it requires testing intersections between all faces of neighboring cubes and the model's mesh.",
      "default": "false"
    }
  ],
  "additional_information": [
    {
      "title": "Connectivity and Ramification",
      "text": "This topology component uses a specialized connectivity approach. At its finest level, it identifies independent connected components (or 'connexion' objects) within each hexahedron. These connexions form a graph that captures how different parts of the grid are interconnected."
    },
    {
      "title": "Data Structures",
      "text": "The _connexions attribute is used to store lists of these connexion objects for each hexahedron in the original regular sparse grid structure. This allows the SparseGridRamificationTopology component to manage complex topological relations efficiently."
    }
  ],
  "maths": "The **SparseGridRamificationTopology** is an advanced extension of the **SparseGridTopology**, designed to handle complex topological structures in 3D sparse grids. Its primary function is to ensure that each resulting hexahedron (cube) contains only one independent connected component, which enables more intricate modeling by potentially duplicating nodes to create separate connections within the grid structure.\n\n### Governing Equations and Operators\n\nThis component does not directly contribute to governing equations or operators such as mass matrix \\(M\\), stiffness matrix \\(K\\), internal force \\(\bm{f}_{int}\\), residual \\(\bm{R}\\), etc. Instead, it focuses on the topological structure and connectivity of the grid elements. Therefore, it does not implement specific constitutive laws or kinematic models.\n\n### Role in the Global FEM Pipeline\n\n- **Assembly**: The component is crucial for assembling a structured mesh where each cube contains only one connected component.\n- **Constraint Handling**: It ensures proper handling and linking of nodes to maintain topological consistency, especially when dealing with complex geometries that require multiple connections within a single hexahedron.\n- **Mapping**: It supports the creation and management of mappings between coarse and fine levels of grid hierarchy. This is important for hierarchical modeling and adaptive refinement techniques in FEM simulations.\n\n### Numerical Methods or Discretization Choices\n\nThe component employs several key numerical methods:\n\n1. **Sparse Grid Construction**:\n   - The grid construction ensures that each hexahedron contains only one independent connected component, which is essential for complex geometries and multi-component modeling.\n   - This involves identifying and managing the connectivity of cubes through a hierarchical structure, where each cube can have multiple finer-level connections (children).\n\n2. **Hierarchical Grid Refinement**:\n   - The `buildVirtualFinerLevels` method constructs virtual finer levels to support hierarchical refinement, enabling adaptive meshing strategies.\n   - This is achieved by recursively dividing the grid into finer sub-grids and maintaining connectivity information at each level.\n\n3. **Connectivity Management**:\n   - Methods such as `findConnexionsAtFinestLevel` manage connectivity between hexahedra at the finest level, ensuring that shared triangles are properly identified and linked.\n   - The `buildRamifiedFinestLevel` method constructs new hexahedra for each independent connection, maintaining vertex linking and consistency across neighboring cubes.\n\n### Integration into Variational / Lagrangian Mechanics Framework\n\nWhile **SparseGridRamificationTopology** itself does not directly contribute to the variational formulation or governing equations of FEM, it plays a critical role in ensuring that the discretized mesh is topologically consistent. This consistency is crucial for accurate numerical integration and subsequent solution of the nonlinear system:\n\n1. **Spatial Discretization**: By ensuring each hexahedron contains only one connected component, it supports robust spatial discretization.\n2. **Boundary Conditions and Constraints**: Proper handling of connectivity ensures that boundary conditions and constraints are correctly applied at the element level, maintaining overall mechanical integrity in the simulation.\n\n### Summary\n\nThe **SparseGridRamificationTopology** is a sophisticated tool for managing complex topological structures within sparse grids. It ensures that each hexahedron contains only one independent connected component, facilitating intricate modeling while supporting hierarchical refinement and robust connectivity management.",
  "abstract": "The SparseGridRamificationTopology ensures each hexahedron contains only one independent connected component, facilitating intricate modeling while supporting hierarchical refinement and robust connectivity management.",
  "sheet": "# SparseGridRamificationTopology\n\n## Overview\nSparseGridRamificationTopology is a specialized version of the SparseGridTopology designed to handle complex topological structures in 3D sparse grids. It ensures each resulting hexahedron (cube) contains only one independent connected component, enabling more intricate modeling by potentially duplicating nodes.\n\n## Parameters and Data\n- **finestConnectivity**: Test for connectivity at the finest level? (more precise but slower by testing all intersections between the model mesh and the faces between boundary cubes). Type: bool. Default: Not specified.\n\n## Dependencies and Connections\nThis component inherits from SparseGridTopology, indicating it requires a base grid structure to operate on. It is typically used in conjunction with other components that require topologically consistent grids for complex geometries and multi-component modeling.\n\n## Practical Notes\n- The `finestConnectivity` parameter can significantly impact performance; enabling it provides more precise connectivity but at the cost of increased computational time.\n- Proper management of connectivity ensures robust spatial discretization, accurate application of boundary conditions, and constraints in FEM simulations."
}