Data Fields

Links

Methods

{
  "name": "TopologicalChangeProcessor",
  "namespace": "sofa::component::topology::utility",
  "module": "Sofa.Component.Topology.Utility",
  "include": "sofa/component/topology/utility/TopologicalChangeProcessor.h",
  "doc": "Read topological changes and process them.\n\nRead file containing topological modification. Or apply input modifications\nA timestep has to be established for each modification.\nSIMPLE METHOD FOR THE MOMENT. DON'T HANDLE MULTIPLE TOPOLOGIES",
  "inherits": [
    "BaseObject"
  ],
  "templates": [],
  "data_fields": [
    {
      "name": "d_interval",
      "type": "double",
      "xmlname": "interval",
      "help": "time duration between 2 actions"
    },
    {
      "name": "d_shift",
      "type": "double",
      "xmlname": "shift",
      "help": "shift between times in the file and times when they will be read"
    },
    {
      "name": "d_loop",
      "type": "bool",
      "xmlname": "loop",
      "help": "set to 'true' to re-read the file when reaching the end"
    },
    {
      "name": "d_useDataInputs",
      "type": "bool",
      "xmlname": "useDataInputs",
      "help": "If true, will perform operation using Data input lists rather than text file."
    },
    {
      "name": "d_timeToRemove",
      "type": "double",
      "xmlname": "timeToRemove",
      "help": "If using option useDataInputs, time at which will be done the operations. Possibility to use the interval Data also."
    },
    {
      "name": "d_saveIndicesAtInit",
      "type": "bool",
      "xmlname": "saveIndicesAtInit",
      "help": "set to 'true' to save the incision to do in the init to incise even after a movement"
    },
    {
      "name": "d_epsilonSnapPath",
      "type": "SReal",
      "xmlname": "epsilonSnapPath",
      "help": "epsilon snap path"
    },
    {
      "name": "d_epsilonSnapBorder",
      "type": "SReal",
      "xmlname": "epsilonSnapBorder",
      "help": "epsilon snap path"
    },
    {
      "name": "d_draw",
      "type": "bool",
      "xmlname": "draw",
      "help": "draw information"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single",
      "xmlname": "topology",
      "help": "link to the topology container"
    }
  ],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "reinit",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "readDataFile",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "handleEvent",
      "return_type": "void",
      "params": [
        {
          "name": "event",
          "type": "sofa::core::objectmodel::Event *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setTime",
      "return_type": "void",
      "params": [
        {
          "name": "time",
          "type": "double"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "processTopologicalChanges",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "processTopologicalChanges",
      "return_type": "void",
      "params": [
        {
          "name": "time",
          "type": "double"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "readNext",
      "return_type": "bool",
      "params": [
        {
          "name": "time",
          "type": "double"
        },
        {
          "name": "lines",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "canCreate",
      "return_type": "bool",
      "params": [
        {
          "name": "obj",
          "type": "T *&"
        },
        {
          "name": "context",
          "type": "core::objectmodel::BaseContext *"
        },
        {
          "name": "arg",
          "type": "core::objectmodel::BaseObjectDescription *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    },
    {
      "name": "draw",
      "return_type": "void",
      "params": [
        {
          "name": "vparams",
          "type": "const core::visual::VisualParams *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "updateTriangleIncisionInformation",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getValuesInLine",
      "return_type": "int",
      "params": [
        {
          "name": "line",
          "type": "int"
        },
        {
          "name": "nbElements",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "findElementIndex",
      "return_type": "void",
      "params": [
        {
          "name": "coord",
          "type": "type::Vec3"
        },
        {
          "name": "triangleIndex",
          "type": "int &"
        },
        {
          "name": "oldTriangleIndex",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "saveIndices",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "inciseWithSavedIndices",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "findIndexInListOfTime",
      "return_type": "int",
      "params": [
        {
          "name": "time",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `TopologicalChangeProcessor` is a SOFA component designed to handle and process topological changes in the simulation. It reads topological modifications from an input file or applies predefined operations specified through data fields, ensuring that these changes are applied at specific timesteps during the simulation.\n\n**Role & Purpose:**\nThe primary role of `TopologicalChangeProcessor` is to manage dynamic topological alterations such as adding, removing, and cutting elements (points, edges, triangles, quads, tetrahedra, hexahedra) from a mesh. It is particularly useful for simulations where the topology needs to change over time, enabling more realistic and interactive scenarios.\n\n**Interactions with Other Components:**\nThe component interacts closely with other SOFA components through its `l_topology` link, which connects it to a `BaseMeshTopology`. This allows `TopologicalChangeProcessor` to modify the mesh topology based on the read or predefined topological changes. Additionally, it interfaces with various `*SetTopologyModifier` and `TriangleSetGeometryAlgorithms` components for actual modifications and geometric operations.\n\n**Practical Usage Guidance & Data Fields:**\nThe component includes several data fields that control its behavior:\n- `d_interval`: Time duration between consecutive actions (topological changes).\n- `d_shift`: Shifts the times specified in the file to align with simulation times.\n- `d_loop`: Allows the component to loop through the input file if it reaches the end.\n- `d_useDataInputs`: Determines whether operations are performed using data inputs or from a text file. If true, topological changes are based on predefined lists of elements specified in other fields like `d_pointsToRemove`, `d_edgesToRemove`, etc., and applied at specific times (`d_timeToRemove`).\n- `d_saveIndicesAtInit` and related fields: Facilitate saving indices for incisions to ensure they remain accurate even after the mesh topology changes.\n\nThe component also supports drawing information when visualization is enabled, making it easier to debug and understand the effects of topological changes during simulation.",
  "maths": "### Mathematical and Physical Description of `TopologicalChangeProcessor`\n\n#### Role in the Global FEM Pipeline\nThe `TopologicalChangeProcessor` is a crucial component for handling dynamic topological modifications during simulations. It allows for the addition, removal, or cutting of elements (points, edges, triangles, quads, tetrahedra, hexahedra) at specified timesteps, ensuring that the mesh topology evolves according to predefined rules or user-defined inputs.\n\n#### Governing Equations and Operators\n- **Topological Changes**: The component does not directly contribute to the governing equations of motion (such as \\(\\rho \\ddot{u} = \nabla \\cdot \\sigma + \\rho b\\)). Instead, it focuses on managing the mesh topology, which indirectly affects these equations by altering the domain over which they are defined.\n\n- **Residual and Jacobian**: Topological changes can alter the structure of the residual (\\(R(x_{n+1}) = M\\frac{x_{n+1}-x_n}{\nDelta t} - \nDelta t f_{int}(x_{n+1}) - \nDelta t f_{ext}\\)) and Jacobian (\\(J(x) = \\frac{1}{\nDelta t}M - \nDelta t K(x)\\)). The Jacobian is particularly sensitive to changes in the connectivity of the mesh.\n\n#### Constitutive or Kinematic Laws Involved\n- **Topology Modifications**: The component does not directly involve constitutive laws. However, topological modifications can change how strain and stress are calculated within elements, which indirectly affects the mechanical response of the system.\n\n- **Strain Measures**: While not explicitly defined in this component, any changes to element connectivity can impact the calculation of strain measures such as Green-Lagrange or Almansi strains.\n\n#### Numerical Methods or Discretization Choices\n- **Element Addition/Removal**: The component reads topological modifications from a file or data inputs and applies them at specified timesteps. This involves operations on mesh connectivity, which can be seen as a form of remeshing.\n\n- **Incisions**: When incisions are applied (cutting elements), the component uses geometric algorithms to determine how to split triangles along specified paths. This involves barycentric coordinates and intersection tests to ensure accurate splitting.\n\n#### Constraint Handling and Mapping\nThe `TopologicalChangeProcessor` does not explicitly handle constraints in the traditional sense of Lagrange multipliers or penalty methods. Instead, it manages topological changes that can affect how constraints are applied, particularly when elements are added, removed, or cut.\n\n#### Fitting into Variational/Lagrangian Mechanics Framework\nWhile `TopologicalChangeProcessor` is not directly involved in the variational formulation of the problem, its role in managing mesh topology is critical for maintaining consistency and accuracy in the simulation. Changes to the mesh topology can affect how the weak form (the integral equations) are discretized and solved.\n\n### Summary\nThe `TopologicalChangeProcessor` plays a vital role in enabling dynamic topological changes during simulations by managing the addition, removal, or cutting of elements at specified timesteps. Although it does not directly contribute to the governing equations, its operations on mesh topology indirectly influence how these equations are solved and affect the overall mechanical behavior of the simulated system.",
  "abstract": "The `TopologicalChangeProcessor` manages dynamic topological changes in simulations by reading modifications from files or predefined data fields and applying them at specified timesteps.",
  "sheet": "# TopologicalChangeProcessor\n\n## Overview\nThe `TopologicalChangeProcessor` is a SOFA component designed to handle dynamic topological alterations such as adding, removing, and cutting elements (points, edges, triangles, quads, tetrahedra, hexahedra) from a mesh. It reads modifications from files or predefined data fields and applies them at specified timesteps during the simulation.\n\n## Parameters and Data\nThe component includes several significant data fields that control its behavior:\n- `d_interval`: Time duration between consecutive actions (topological changes).\n- `d_shift`: Shifts the times specified in the file to align with simulation times.\n- `d_loop`: Allows the component to loop through the input file if it reaches the end.\n- `d_useDataInputs`: Determines whether operations are performed using data inputs or from a text file. If true, topological changes are based on predefined lists of elements specified in other fields like `d_pointsToRemove`, `d_edgesToRemove`, etc., and applied at specific times (`d_timeToRemove`).\n- `d_saveIndicesAtInit` and related fields: Facilitate saving indices for incisions to ensure they remain accurate even after the mesh topology changes.\n\n## Dependencies and Connections\nThe component interacts closely with other SOFA components through its `l_topology` link, which connects it to a `BaseMeshTopology`. This allows `TopologicalChangeProcessor` to modify the mesh topology based on the read or predefined topological changes. Additionally, it interfaces with various `*SetTopologyModifier` and `TriangleSetGeometryAlgorithms` components for actual modifications and geometric operations.\n\n## Practical Notes\n- Ensure that the input file or data fields are correctly formatted and contain valid topological changes.\n- The component supports drawing information when visualization is enabled, making it easier to debug and understand the effects of topological changes during simulation."
}