Data Fields

Links

Methods

{
  "name": "ReadTopology",
  "namespace": "sofa::component::playback",
  "module": "Sofa.Component.Playback",
  "include": "sofa/component/playback/ReadTopology.h",
  "doc": "Read topology containers information from file at each timestep.\n\nRead Topology containers information from file at each timestep",
  "inherits": [
    "BaseObject"
  ],
  "templates": [],
  "data_fields": [
    {
      "name": "d_interval",
      "type": "double",
      "xmlname": "interval",
      "help": "time duration between inputs"
    },
    {
      "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"
    }
  ],
  "links": [
    {
      "name": "l_topology",
      "target": "BaseMeshTopology",
      "kind": "single"
    }
  ],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "reset",
      "return_type": "void",
      "params": [],
      "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": "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": "processReadTopology",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "processReadTopology",
      "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"
    }
  ],
  "description": "This component reads topology data from a file and updates the connected Topology container accordingly.",
  "properties": {
    "filename": {
      "type": "string",
      "description": "The path to the file containing the topology data."
    },
    "l_topology": {
      "type": "TopologyContainer",
      "description": "Link to the Topology container that will be updated with the read data."
    }
  },
  "events_handled": [
    {
      "name": "AnimateBeginEvent",
      "description": "Triggers the component to process and apply new topology data at the beginning of each animation frame.",
      "type": "simulation event"
    }
  ],
  "functions": [
    {
      "name": "init()",
      "description": "Initializes the ReadTopology by setting up connections and opening the file for reading."
    },
    {
      "name": "reset()",
      "description": "Resets the component to its initial state, reopening the file if necessary."
    },
    {
      "name": "handleEvent(event)",
      "description": "Handles incoming events, specifically AnimateBeginEvent, which triggers the processReadTopology method.",
      "parameters": [
        {
          "name": "event",
          "type": "objectmodel::Event*",
          "description": "The event object containing information about the triggered event."
        }
      ]
    },
    {
      "name": "processReadTopology(double time)",
      "description": "Processes and applies topology data from the file corresponding to the specified time.",
      "parameters": [
        {
          "name": "time",
          "type": "double",
          "description": "The simulation time for which the topology data is processed."
        }
      ]
    },
    {
      "name": "readNext(double time, vector<string>& validLines)",
      "description": "Reads lines from the file up to a specified time and returns them in 'validLines'.",
      "parameters": [
        {
          "name": "time",
          "type": "double",
          "description": "The simulation time up to which lines should be read."
        },
        {
          "name": "validLines",
          "type": "vector<string>&",
          "description": "A reference to a vector where the valid lines are stored."
        }
      ]
    }
  ],
  "file_dependencies": [
    {
      "filename": "ReadTopology.h",
      "type": "header"
    },
    {
      "filename": "ReadTopology.inl",
      "type": "inline implementation"
    },
    {
      "filename": "ReadTopology.cpp",
      "type": "source"
    }
  ],
  "maths": "The **ReadTopology** component in the SOFA framework is designed to read topology data from an external file and update the connected mesh topology container at each time step. The primary function of this component is not to contribute directly to the governing equations or operators such as mass matrix \\(M\\), stiffness matrix \\(K\\), internal force \\(f_{int}\\), or residual \\(R\\). Instead, it plays a crucial role in providing the necessary topological information for other components (such as mechanical models and solvers) that implement these mathematical formulations. Here is its detailed description within the broader context of computational mechanics:\n\n### Mathematical and Physical Description\n\n#### Role in Topology Management\nThe **ReadTopology** component reads from a specified file, which contains time-series data about various topological elements (e.g., edges, triangles, tetrahedra) that describe how nodes are connected within the mesh. This information is crucial for defining the connectivity and structure of the discretized domain used in FEM simulations.\n\n#### Data Fields and Parameters\n- **d_interval**: Time duration between inputs from the file.\n- **d_shift**: Shift between times in the file and when they will be read by the component.\n- **d_loop**: Boolean flag to indicate whether the component should re-read the file after reaching the end.\n\n#### Workflow\n1. **Initialization**:\n   - The component initializes its internal state, setting up file streams for reading from the specified topology data file.\n2. **Reading Topology Data**:\n   - At each time step (triggered by simulation events), the **ReadTopology** component reads new topological information from the file and updates the connected mesh topology container accordingly.\n3. **Topological Elements**:\n   - The component handles various types of elements: edges, triangles, quads, tetrahedra, and hexahedra. For each type, it parses the number of such elements and their respective node indices from the file.\n4. **Updating Topology Container**:\n   - Once new topological data is read, the component updates the connected topology container with these changes, ensuring that subsequent mechanical models, solvers, or other components can use this updated information for further computations (e.g., forming element stiffness matrices, applying boundary conditions, etc.).\n\n#### Integration into FEM Pipeline\n- **Assembly Phase**: The topological data read by **ReadTopology** is crucial during the assembly phase of the FEM pipeline. It defines how nodes are connected to form elements and how these elements interact with each other.\n- **Time Integration and Nonlinear Solution**: The updated topology influences how element matrices (mass, stiffness) are formed and assembled into global matrices. This impacts subsequent steps in time integration and nonlinear solution processes.\n\n#### Numerical Methods and Discretization Choices\nThe component itself does not perform any numerical discretization or solve equations directly. Instead, it facilitates the correct setup of topological information that is essential for other components to carry out their respective tasks (e.g., finite element assembly).\n\n### Conclusion\n**ReadTopology** ensures that topology data is correctly read and propagated throughout the simulation pipeline in SOFA, thereby supporting the variational mechanics framework by providing accurate connectivity information necessary for FEM simulations. Although it does not directly contribute to governing equations or operators, its role in maintaining up-to-date topological structure is critical for the correctness of any subsequent computational mechanics operations.",
  "abstract": "The `ReadTopology` component reads topology data from a file at each time step and updates the connected mesh topology container accordingly.",
  "sheet": "# ReadTopology\n\n## Overview\nThe `ReadTopology` component is part of the SOFA framework's playback module. It reads topology information from an external file at each time step and updates the connected mesh topology container, ensuring that topological data remains current throughout the simulation.\n\n## Parameters and Data\n- **d_interval**: Time duration between inputs from the file (default: not specified).\n- **d_shift**: Shift between times in the file and when they will be read by the component (default: not specified).\n- **d_loop**: Boolean flag to indicate whether the component should re-read the file after reaching the end (default: `false`).\n\n## Dependencies and Connections\nThe `ReadTopology` component requires a connection to a `BaseMeshTopology` object, which it updates with the topology data read from the file. It fits into the scene graph by providing up-to-date topological information for other components such as mechanical models and solvers."
}