TopologySubsetData

sofa::core::topology::TopologySubsetData

TopologyData

Doc (from source)

A class for storing element related data. Automatically manages topology changes. This class is a wrapper of class type::vector that is made to take care transparently of all topology changes that might happen (non exhaustive list: elements added, removed, fused, renumbered).

Abstract (AI generated)

`TopologySubsetData` manages subsets of topological data within the SOFA framework, automatically handling topology changes such as additions, removals, and renumbering operations to maintain consistency.

Metadata

module

Sofa.framework.Core

namespace

sofa::core::topology

include

sofa/core/topology/TopologySubsetData.h

inherits

TopologyData

templates

Index, sofa::type::vector<Index>

description

The TopologySubsetData class in the SOFA framework is designed for managing subsets of topological data (e.g., points, edges, triangles) and ensuring consistency across topology changes. This class plays a crucial role in maintaining the integrity of the simulation by handling operations such as adding, removing, and renumbering elements within the subset data structure.

Governing Equations or Operators

The TopologySubsetData does not directly implement any governing equations or operators related to FEM (such as mass matrix $M$, stiffness matrix $K$, internal force $f_{int}$, residual $R$), but it is essential for managing the underlying topological structure that these operators depend on. For instance, when elements are added or removed, the TopologySubsetData ensures that any data associated with those elements (e.g., displacements, forces) is correctly updated and managed.

Constitutive or Kinematic Laws

The class itself does not involve constitutive or kinematic laws directly. However, it facilitates the management of topological changes that are necessary for applying these laws consistently across the simulation domain. For example, when an element is added or removed from a subset, any associated material properties or geometric constraints must be updated accordingly.

Role in the Global FEM Pipeline

In the context of the global FEM pipeline:
- Discretization Phase: The class helps manage subsets of topological data used for discretizing the domain into finite elements. It ensures that these subsets are consistent with any changes to the underlying topology.
- Assembly Phase: When assembling global operators (e.g., mass matrix, stiffness matrix), TopologySubsetData manages the subset data such that these operators can be updated correctly in response to topological changes.
- Nonlinear Solution and Linear Solve: The class ensures that any constraints or mappings associated with subsets of elements are consistent during nonlinear iterations and linear solves. For example, if an element is removed from a subset, its contribution to the system must be adjusted accordingly.

Numerical Methods or Discretization Choices

The TopologySubsetData class does not directly involve numerical methods or discretization choices. Instead, it provides mechanisms for maintaining consistency in the topological data structure used by these methods. For instance, when elements are renumbered or removed, the mappings and subset indices are updated to ensure that any subsequent operations (e.g., assembly of global matrices) remain valid.

Variational / Lagrangian Mechanics Framework

While TopologySubsetData does not directly implement variational principles or Lagrangian mechanics, it is crucial for ensuring that the underlying topological structure used in these formulations remains consistent. For example, when elements are added or removed from a subset, any associated contributions to the weak form (e.g., internal forces) must be correctly updated.

Detailed Operations and Methods

setMap2Elements: Sets a vector map that defines which elements belong to this subset.
$\mathbf{m}_{map2Elements} = [i_1, i_2, ..., i_n]$
where each index $i_j$ represents an element in the full topological data structure.
indexOfElement: Returns the position of a given element within the subset map.
For element index $e_i$, $ ext{indexOfElement}(e_i) = k$ where $k$ is the position of $e_i$ in $\mathbf{m}_{map2Elements}$.
indicesOfElement: Returns all positions of a given element within the subset map.
For element index $e_i$, $ ext{indicesOfElement}(e_i) = [k_1, k_2, ..., k_m]$ where each $k_j$ is a position in $\mathbf{m}_{map2Elements}$.
swap: Swaps values of the subset map at specified indices.
For indices $i_1$ and $i_2$, swap $ ext{subsetMap}[i_1]$ with $ ext{subsetMap}[i_2]$.
add: Adds new elements to the subset data, updating mappings accordingly.
For a set of new element indices $E_{new}$, update $ ext{m_map2Elements}$ and track last added index.
remove: Removes specified elements from the subset data.
For indices $index$, remove corresponding entries from $ ext{subsetMap}$.

Conclusion

The TopologySubsetData class is a critical component for managing subsets of topological data within the SOFA framework. It ensures that any changes to the topology are consistently reflected in the subset data, which is essential for maintaining the correctness and robustness of FEM simulations.

Methods

void setMap2Elements (const int _map2Elements)

int & getMap2Elements ()

void supportNewTopologyElements (bool value)

bool isNewTopologyElementsSupported ()

int indexOfElement (int index)

const int indicesOfElement (int index)

void swap (int i1, int i2)

void add (int nbElements, const int & ancestors, const int & coefs) virtual

void add (int nbElements, const int & elems, const int & ancestors, const int & coefs) virtual

void add (const int & index, const int & elems, const int & ancestors, const int & coefs, const int & ancestorElems)

void remove (const int & index)

void renumber (const int & index)

void move (const int & indexList, const int & ancestors, const int & coefs)

void addOnMovedPosition (const int & indexList, const int & elems)

void removeOnMovedPosition (const int & indices)

void swapPostProcess (int i1, int i2) virtual

void removePostProcess (int elemId) virtual

void addPostProcess (int dataLastId) virtual

void updateLastIndex (int posLastIndex, int newGlobalId) virtual

{
  "name": "TopologySubsetData",
  "namespace": "sofa::core::topology",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/topology/TopologySubsetData.h",
  "doc": "A class for storing element related data. Automatically manages topology changes.\nThis class is a wrapper of class type::vector that is made to take care transparently of all topology changes that might\nhappen (non exhaustive list: elements added, removed, fused, renumbered).",
  "inherits": [
    "TopologyData"
  ],
  "templates": [
    "Index, sofa::type::vector<Index>"
  ],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "setMap2Elements",
      "return_type": "void",
      "params": [
        {
          "name": "_map2Elements",
          "type": "const int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMap2Elements",
      "return_type": "int &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "supportNewTopologyElements",
      "return_type": "void",
      "params": [
        {
          "name": "value",
          "type": "bool"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "isNewTopologyElementsSupported",
      "return_type": "bool",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "indexOfElement",
      "return_type": "int",
      "params": [
        {
          "name": "index",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "indicesOfElement",
      "return_type": "const int",
      "params": [
        {
          "name": "index",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "swap",
      "return_type": "void",
      "params": [
        {
          "name": "i1",
          "type": "int"
        },
        {
          "name": "i2",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "add",
      "return_type": "void",
      "params": [
        {
          "name": "nbElements",
          "type": "int"
        },
        {
          "name": "ancestors",
          "type": "const int &"
        },
        {
          "name": "coefs",
          "type": "const int &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "add",
      "return_type": "void",
      "params": [
        {
          "name": "nbElements",
          "type": "int"
        },
        {
          "name": "elems",
          "type": "const int &"
        },
        {
          "name": "ancestors",
          "type": "const int &"
        },
        {
          "name": "coefs",
          "type": "const int &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "add",
      "return_type": "void",
      "params": [
        {
          "name": "index",
          "type": "const int &"
        },
        {
          "name": "elems",
          "type": "const int &"
        },
        {
          "name": "ancestors",
          "type": "const int &"
        },
        {
          "name": "coefs",
          "type": "const int &"
        },
        {
          "name": "ancestorElems",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "remove",
      "return_type": "void",
      "params": [
        {
          "name": "index",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "renumber",
      "return_type": "void",
      "params": [
        {
          "name": "index",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "move",
      "return_type": "void",
      "params": [
        {
          "name": "indexList",
          "type": "const int &"
        },
        {
          "name": "ancestors",
          "type": "const int &"
        },
        {
          "name": "coefs",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addOnMovedPosition",
      "return_type": "void",
      "params": [
        {
          "name": "indexList",
          "type": "const int &"
        },
        {
          "name": "elems",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "removeOnMovedPosition",
      "return_type": "void",
      "params": [
        {
          "name": "indices",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "swapPostProcess",
      "return_type": "void",
      "params": [
        {
          "name": "i1",
          "type": "int"
        },
        {
          "name": "i2",
          "type": "int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "removePostProcess",
      "return_type": "void",
      "params": [
        {
          "name": "elemId",
          "type": "int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "addPostProcess",
      "return_type": "void",
      "params": [
        {
          "name": "dataLastId",
          "type": "int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "updateLastIndex",
      "return_type": "void",
      "params": [
        {
          "name": "posLastIndex",
          "type": "int"
        },
        {
          "name": "newGlobalId",
          "type": "int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `TopologySubsetData` class in the SOFA framework is designed for storing element-related data and automatically managing topology changes, such as elements being added, removed, fused, or renumbered. It acts as a wrapper around `type::vector` to transparently handle these modifications.\n\n**Role and Purpose**: This class encapsulates the storage and manipulation of subsets of topological data (e.g., points, edges, triangles) within the SOFA scene graph. It ensures that any changes in topology are reflected correctly across the simulation, maintaining consistency with the rest of the system.\n\n**Interactions with Other Components**: `TopologySubsetData` inherits from `TopologyData`, which is a base class for managing topological data. Its methods interact with other components by allowing additions, removals, and renumbering operations that are critical to maintaining correct simulation states during runtime. It also manages callbacks (`p_onCreationCallback` and `p_onDestructionCallback`) to respond to topology changes.\n\n**Practical Usage**: The class provides methods such as `add`, `remove`, and `swap` to manipulate the subset data, ensuring these operations handle internal mappings correctly. For example, the `setMap2Elements` method can be used to set a vector map that defines which elements are part of this subset.\n\n**Data Fields**: The class maintains an internal mapping (`m_map2Elements`) and a flag (`m_addNewElements`) to track whether new topology elements should be added. Additional methods like `indexOfElement`, `indicesOfElement`, `swapPostProcess`, `removePostProcess`, and `addPostProcess` support these operations.",
  "maths": "The `TopologySubsetData` class in the SOFA framework is designed for managing subsets of topological data (e.g., points, edges, triangles) and ensuring consistency across topology changes. This class plays a crucial role in maintaining the integrity of the simulation by handling operations such as adding, removing, and renumbering elements within the subset data structure.\n\n### Governing Equations or Operators\nThe `TopologySubsetData` does not directly implement any governing equations or operators related to FEM (such as mass matrix \\(M\\), stiffness matrix \\(K\\), internal force \\(f_{int}\\), residual \\(R\\)), but it is essential for managing the underlying topological structure that these operators depend on. For instance, when elements are added or removed, the `TopologySubsetData` ensures that any data associated with those elements (e.g., displacements, forces) is correctly updated and managed.\n\n### Constitutive or Kinematic Laws\nThe class itself does not involve constitutive or kinematic laws directly. However, it facilitates the management of topological changes that are necessary for applying these laws consistently across the simulation domain. For example, when an element is added or removed from a subset, any associated material properties or geometric constraints must be updated accordingly.\n\n### Role in the Global FEM Pipeline\nIn the context of the global FEM pipeline:\n- **Discretization Phase**: The class helps manage subsets of topological data used for discretizing the domain into finite elements. It ensures that these subsets are consistent with any changes to the underlying topology.\n- **Assembly Phase**: When assembling global operators (e.g., mass matrix, stiffness matrix), `TopologySubsetData` manages the subset data such that these operators can be updated correctly in response to topological changes.\n- **Nonlinear Solution and Linear Solve**: The class ensures that any constraints or mappings associated with subsets of elements are consistent during nonlinear iterations and linear solves. For example, if an element is removed from a subset, its contribution to the system must be adjusted accordingly.\n\n### Numerical Methods or Discretization Choices\nThe `TopologySubsetData` class does not directly involve numerical methods or discretization choices. Instead, it provides mechanisms for maintaining consistency in the topological data structure used by these methods. For instance, when elements are renumbered or removed, the mappings and subset indices are updated to ensure that any subsequent operations (e.g., assembly of global matrices) remain valid.\n\n### Variational / Lagrangian Mechanics Framework\nWhile `TopologySubsetData` does not directly implement variational principles or Lagrangian mechanics, it is crucial for ensuring that the underlying topological structure used in these formulations remains consistent. For example, when elements are added or removed from a subset, any associated contributions to the weak form (e.g., internal forces) must be correctly updated.\n\n### Detailed Operations and Methods\n- **`setMap2Elements`**: Sets a vector map that defines which elements belong to this subset.\n  - \\(\\mathbf{m}_{map2Elements} = [i_1, i_2, ..., i_n]\\)\n    where each index \\(i_j\\) represents an element in the full topological data structure.\n- **`indexOfElement`**: Returns the position of a given element within the subset map.\n  - For element index \\(e_i\\), \\(\text{indexOfElement}(e_i) = k\\) where \\(k\\) is the position of \\(e_i\\) in \\(\\mathbf{m}_{map2Elements}\\).\n- **`indicesOfElement`**: Returns all positions of a given element within the subset map.\n  - For element index \\(e_i\\), \\(\text{indicesOfElement}(e_i) = [k_1, k_2, ..., k_m]\\) where each \\(k_j\\) is a position in \\(\\mathbf{m}_{map2Elements}\\).\n- **`swap`**: Swaps values of the subset map at specified indices.\n  - For indices \\(i_1\\) and \\(i_2\\), swap \\(\text{subsetMap}[i_1]\\) with \\(\text{subsetMap}[i_2]\\).\n- **`add`**: Adds new elements to the subset data, updating mappings accordingly.\n  - For a set of new element indices \\(E_{new}\\), update \\(\text{m_map2Elements}\\) and track last added index.\n- **`remove`**: Removes specified elements from the subset data.\n  - For indices \\(index\\), remove corresponding entries from \\(\text{subsetMap}\\).\n\n### Conclusion\nThe `TopologySubsetData` class is a critical component for managing subsets of topological data within the SOFA framework. It ensures that any changes to the topology are consistently reflected in the subset data, which is essential for maintaining the correctness and robustness of FEM simulations.",
  "abstract": "`TopologySubsetData` manages subsets of topological data within the SOFA framework, automatically handling topology changes such as additions, removals, and renumbering operations to maintain consistency.",
  "sheet": "# TopologySubsetData\n\n## Overview\nThe `TopologySubsetData` class is designed for storing element-related data and managing topology changes transparently. It acts as a wrapper around `type::vector`, ensuring that any modifications (additions, removals, renumbering) are correctly reflected in the simulation.\n\n## Parameters and Data\n- **m_map2Elements**: A vector map defining which elements belong to this subset. This is managed by methods such as `setMap2Elements` and `getMap2Elements`.\n- **m_addNewElements**: A flag indicating whether new topology elements should be added, controlled via the `supportNewTopologyElements` method.\n\n## Dependencies and Connections\nThis component inherits from `TopologyData`, which is a base class for managing topological data. It interacts with other components by allowing additions, removals, and renumbering operations that are critical to maintaining correct simulation states during runtime."
}