Methods

{
  "name": "MechanicalState",
  "namespace": "sofa::core::behavior",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/behavior/MechanicalState.h",
  "doc": "Component storing all state vectors of a simulated body (position,\n velocity, etc), using the datatype specified in the template.\n The given DataTypes class should define the following internal types:\n \\li \\code Real \\endcode : scalar values (float or double).\n \\li \\code Coord \\endcode : position values.\n \\li \\code Deriv \\endcode : derivative values (velocity, forces, displacements).\n \\li \\code VecCoord \\endcode : container of Coord values with the same API as sofa::type::vector.\n \\li \\code VecDeriv \\endcode : container of Deriv values with the same API as sofa::type::vector.\n \\li \\code MatrixDeriv \\endcode : vector of constraints.\n Other vectors can be allocated to store other temporary values.\n Vectors can be assigned efficiently by just swapping pointers.\n In addition to state vectors, the current constraint system matrix is also\n stored, containing the coefficient of each constraint defined over the DOFs\n in this body.",
  "inherits": [
    "BaseMechanicalState",
    "State"
  ],
  "templates": [
    "sofa::defaulttype::Rigid2Types",
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "getCoordDimension",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getDerivDimension",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getIndicesInSpace",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "int &"
        },
        {
          "name": "",
          "type": "Real"
        },
        {
          "name": "",
          "type": "Real"
        },
        {
          "name": "",
          "type": "Real"
        },
        {
          "name": "",
          "type": "Real"
        },
        {
          "name": "",
          "type": "Real"
        },
        {
          "name": "",
          "type": "Real"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "shortName",
      "return_type": "int",
      "params": [
        {
          "name": "ptr",
          "type": "const T *"
        },
        {
          "name": "arg",
          "type": "objectmodel::BaseObjectDescription *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    },
    {
      "name": "copyToBuffer",
      "return_type": "void",
      "params": [
        {
          "name": "dst",
          "type": "SReal *"
        },
        {
          "name": "src",
          "type": "ConstVecId"
        },
        {
          "name": "n",
          "type": "unsigned int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "copyFromBuffer",
      "return_type": "void",
      "params": [
        {
          "name": "dst",
          "type": "VecId"
        },
        {
          "name": "src",
          "type": "const SReal *"
        },
        {
          "name": "n",
          "type": "unsigned int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addFromBuffer",
      "return_type": "void",
      "params": [
        {
          "name": "dst",
          "type": "VecId"
        },
        {
          "name": "src",
          "type": "const SReal *"
        },
        {
          "name": "n",
          "type": "unsigned int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "ComponentName": "MechanicalState",
  "Description": "The `MechanicalState` is a template class in the SOFA (Simulation Open Framework Architecture) framework designed to store and manage all state vectors of a simulated body, including positions, velocities, forces, and constraints, using the data type specified by the template parameter. This component forms an essential part of physical simulation in SOFA, ensuring that each element of a simulated object can be precisely tracked and manipulated during simulations.",
  "TemplateParameter": "TDataTypes",
  "PublicMethods": [
    {
      "MethodName": "getCoordDimension() const",
      "Description": "Returns the dimension of position values (Coords). This is useful for understanding the coordinate system in which positions are expressed, whether it's 2D or 3D.",
      "ReturnType": "Size"
    },
    {
      "MethodName": "getDerivDimension() const",
      "Description": "Returns the dimension of derivative values (derivatives include velocities and forces). This method is used to understand how many components make up derivatives like velocity vectors.",
      "ReturnType": "Size"
    },
    {
      "MethodName": "getIndicesInSpace(sofa::type::vector<Index>& indices, Real xmin, Real xmax, Real ymin, Real ymax, Real zmin, Real zmax) const",
      "Description": "Retrieves the indices of particles located within a specified bounding box. This function is crucial for spatial queries and optimizations in simulations.",
      "ReturnType": "void"
    },
    {
      "MethodName": "copyToBuffer(SReal* dst, ConstVecId src, unsigned n) const",
      "Description": "Copies vector data from the internal state to an external buffer pointed by `dst`. It takes a source vector ID and copies up to `n` elements into the destination buffer. This method facilitates the export of simulation data for further processing or visualization.",
      "ReturnType": "void"
    },
    {
      "MethodName": "copyFromBuffer(VecId dst, const SReal* src, unsigned n)",
      "Description": "Copies vector data from an external buffer `src` to the internal state at the destination ID `dst`. It takes up to `n` elements and updates the simulation state accordingly. This method is useful for importing or updating simulation states.",
      "ReturnType": "void"
    },
    {
      "MethodName": "addFromBuffer(VecId dst, const SReal* src, unsigned n)",
      "Description": "Adds vector data from an external buffer to the internal state at a destination ID `dst`. It takes up to `n` elements and adds them to existing vectors in the simulation. This method can be used for applying forces or displacements to a simulated object.",
      "ReturnType": "void"
    }
  ],
  "InheritedClasses": [
    "BaseMechanicalState",
    "State<TDataTypes>"
  ],
  "UsedDataTypes": [
    {
      "TypeName": "TDataTypes",
      "Description": "A template parameter that must define several internal types: Real, Coord, Deriv, VecCoord, VecDeriv, and MatrixDeriv."
    },
    {
      "TypeName": "Real",
      "Description": "Typedef for scalar values (float or double)."
    },
    {
      "TypeName": "Coord",
      "Description": "Typedef for position values."
    },
    {
      "TypeName": "Deriv",
      "Description": "Typedef for derivative values, such as velocity and forces."
    },
    {
      "TypeName": "VecCoord",
      "Description": "Container of Coord with the same API as sofa::type::vector."
    },
    {
      "TypeName": "VecDeriv",
      "Description": "Container of Deriv with the same API as sofa::type::vector."
    },
    {
      "TypeName": "MatrixDeriv",
      "Description": "Sparse matrix containing derivative values (constraints)."
    }
  ],
  "ShortNameMethod": [
    "shortName(const T* ptr = nullptr, objectmodel::BaseObjectDescription* arg = nullptr)",
    "Returns a simplified string name for the class by replacing specific keywords in the default shortname with shorter alternatives."
  ],
  "maths": "The **MechanicalState** component in the SOFA framework is designed to store all state vectors associated with a simulated body, including positions, velocities, and other derivative values. This component acts as a container for these vectors using specific data types defined by templates (e.g., `Vec3Types`, `Rigid3Types`). Here's a detailed breakdown of its mathematical and physical aspects:\n\n### Governing Equations and Operators\n- **Position Vectors** (\textbf{X}): The component stores position values as coordinates, which are vectors representing the positions of nodes in the simulation.\n- **Velocity/Force/Derivative Vectors** (\textbf{\textit{V}}): It also stores derivative values such as velocities and forces. These vectors are crucial for time integration and dynamic simulations.\n\n### Constitutive or Kinematic Laws\nThe component itself does not directly implement any constitutive or kinematic laws; instead, it serves as a data structure to hold these values. However, the positions and derivatives can be used in subsequent calculations involving strain measures, stress tensors, hyperelastic potentials, etc., depending on the specific force fields or constraints applied.\n\n### Role in Global FEM Pipeline\n- **State Vectors**: It holds essential state vectors like position (\textbf{X}) and velocity/force (\textbf{\textit{V}}) that are critical for assembling global matrices such as mass matrix (M), stiffness matrix (K), internal forces (\textbf{f}_{int}), etc.\n- **Time Integration**: The position and derivative values stored here are used in time integration schemes like implicit Euler or Newmark-type methods to advance the simulation over discrete time steps.\n\n### Numerical Methods or Discretization Choices\n- **Data Containers**: It uses specialized containers (`VecCoord` for positions, `VecDeriv` for derivatives) that align with SOFA's internal vector API. These containers ensure efficient memory management and operations on large datasets typical in FEM simulations.\n- **Constraint System Matrix**: The component also stores a matrix representing the current constraint system, which is essential for enforcing constraints (holonomic or non-holonomic) during the simulation.\n\n### Variational / Lagrangian Mechanics Framework\nWhile **MechanicalState** itself does not directly contribute to variational formulations or Lagrangian mechanics, it serves as a fundamental data structure that holds the states necessary for such formulations. The positions and derivatives stored here are used in weak forms and other variational principles within SOFA's broader simulation pipeline.\n\n### Summary\nThe **MechanicalState** component is a crucial part of the FEM simulation pipeline in SOFA, providing efficient storage and manipulation of state vectors required for time integration, constraint enforcement, and overall dynamic simulations. It does not implement specific constitutive laws but is essential for storing and updating states that are used across various components of the simulation framework.",
  "abstract": "The MechanicalState component stores all state vectors (positions, velocities) of a simulated body using specified data types, providing essential storage for dynamic simulations in SOFA.",
  "sheet": "# MechanicalState\n\n## Overview\nMechanicalState is a crucial component that stores the state vectors (position and derivative values such as velocity or forces) of a simulated body. It inherits from `BaseMechanicalState` and `State`, and uses specialized data types (`Vec3Types`, `Rigid2Types`, `Rigid3Types`) to manage these states efficiently.\n\n## Parameters and Data\nThe MechanicalState component does not expose any significant Data fields directly; its functionality is primarily through the management of internal state vectors. It stores positions in `VecCoord` and derivatives (velocities, forces) in `VecDeriv`. Additionally, it manages a constraint system matrix for enforcing constraints over degrees of freedom."
}