Methods

{
  "name": "State",
  "namespace": "sofa::core",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/State.h",
  "doc": "Component storing position and velocity vectors.\n This class define the interface of components used as source and\n destination of regular (non mechanical) mapping. It is then specialized as\n MechanicalState (storing other mechanical data) or MappedModel (if no\n mechanical data is used, such as for VisualModel).\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).\n \\li \\code VecReal \\endcode : container of scalar values with the same API as sofa::type::vector.\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 Jacobians (sparse constraint matrices).",
  "inherits": [
    "BaseState"
  ],
  "templates": [
    "sofa::defaulttype::Rigid2Types",
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec2Types",
    "sofa::defaulttype::Vec3dTypes",
    "sofa::defaulttype::Vec3fTypes"
  ],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "readPositions",
      "return_type": "ReadVecCoord",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "writePositions",
      "return_type": "WriteVecCoord",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "writeOnlyPositions",
      "return_type": "WriteOnlyVecCoord",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "readRestPositions",
      "return_type": "ReadVecCoord",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "writeRestPositions",
      "return_type": "WriteVecCoord",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "writeOnlyRestPositions",
      "return_type": "WriteOnlyVecCoord",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "readVelocities",
      "return_type": "ReadVecDeriv",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "writeVelocities",
      "return_type": "WriteVecDeriv",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "writeOnlyVelocities",
      "return_type": "WriteOnlyVecDeriv",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "readForces",
      "return_type": "ReadVecDeriv",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "writeForces",
      "return_type": "WriteVecDeriv",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "writeOnlyForces",
      "return_type": "WriteOnlyVecDeriv",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "readDx",
      "return_type": "ReadVecDeriv",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "writeDx",
      "return_type": "WriteVecDeriv",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "writeOnlyDx",
      "return_type": "WriteOnlyVecDeriv",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "readNormals",
      "return_type": "ReadVecDeriv",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "readTotalForces",
      "return_type": "const AccumulationVecId<TDataTypes, V_DERIV, V_READ> &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addToTotalForces",
      "return_type": "void",
      "params": [
        {
          "name": "forceId",
          "type": "core::ConstVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "removeFromTotalForces",
      "return_type": "void",
      "params": [
        {
          "name": "forceId",
          "type": "core::ConstVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "write",
      "return_type": "Data<VecCoord> *",
      "params": [
        {
          "name": "v",
          "type": "VecCoordId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "read",
      "return_type": "const Data<VecCoord> *",
      "params": [
        {
          "name": "v",
          "type": "ConstVecCoordId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "write",
      "return_type": "Data<VecDeriv> *",
      "params": [
        {
          "name": "v",
          "type": "VecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "read",
      "return_type": "const Data<VecDeriv> *",
      "params": [
        {
          "name": "v",
          "type": "ConstVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "write",
      "return_type": "Data<MatrixDeriv> *",
      "params": [
        {
          "name": "v",
          "type": "MatrixDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "read",
      "return_type": "const Data<MatrixDeriv> *",
      "params": [
        {
          "name": "v",
          "type": "ConstMatrixDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "baseWrite",
      "return_type": "objectmodel::BaseData *",
      "params": [
        {
          "name": "v",
          "type": "VecId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "baseRead",
      "return_type": "const objectmodel::BaseData *",
      "params": [
        {
          "name": "v",
          "type": "ConstVecId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "computeBBox",
      "return_type": "sofa::type::BoundingBox",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "computeBBox",
      "return_type": "void",
      "params": [
        {
          "name": "params",
          "type": "const core::ExecParams *"
        },
        {
          "name": "onlyVisible",
          "type": "bool"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `State` class in the SOFA framework is a templated base class used for managing state data related to position and velocity vectors, commonly utilized as source or destination components in non-mechanical mappings within simulation models. This class provides an interface and functionality for accessing and manipulating various types of vector data that represent positions, velocities, forces, displacements, and other derived quantities.\n\n### Key Features:\n- **Data Types:**\n    - Defines several internal types including scalar values (`Real`), position values (`Coord`), derivative values such as velocity or force (`Deriv`), containers for vectors of coordinates (`VecCoord`) and derivatives (`VecDeriv`), and a vector of Jacobians for sparse constraint matrices (`MatrixDeriv`).\n\n- **Accessors:**\n    - Provides convenience accessor methods to read from and write to position, rest positions, velocities, forces, displacements, and normal vectors. These accessors use helper classes `ReadAccessor`, `WriteAccessor`, and `WriteOnlyAccessor` to facilitate safe and efficient data access.\n\n- **Forces Accumulation:**\n    - Includes a member variable `accumulatedForces` of type `AccumulationVecId<TDataTypes, V_DERIV, V_READ>` for managing the cumulative sum of all force containers. Methods `addToTotalForces()` and `removeFromTotalForces()` allow adding or removing specific force vectors from this accumulation.\n\n- **Vector ID Based Access:**\n    - Offers virtual methods `write(VecCoordId v)`, `read(ConstVecCoordId v)`, `write(VecDerivId v)`, `read(ConstVecDerivId v)`, and others for writing to and reading from vectors using a generic identifier (`VecId`). These methods are pure virtual, meaning they must be implemented by derived classes.\n\n- **BaseData Access:**\n    - Implements overridden methods `baseWrite(VecId v)` and `baseRead(ConstVecId v)` that provide access to the underlying `objectmodel::BaseData` objects associated with a given vector identifier. This allows for more generic data manipulation within the SOFA framework.\n\n- **Bounding Box Computation:**\n    - Implements methods `computeBBox()` and an overridden version `computeBBox(const core::ExecParams* params, bool onlyVisible=false)` to compute the bounding box encompassing all points in the state's coordinate vectors. The latter method takes into account visibility parameters when computing the bounding box.\n\n### Usage:\n- This class is typically inherited by more specialized classes like `MechanicalState` which manage additional mechanical data or `MappedModel`, used for components that do not use mechanical data, such as visual models.\n- It enables a consistent and structured way to handle state-related data across different types of simulation models within the SOFA framework.",
  "summary": "The `State` class in the SOFA framework is a templated base component managing position and velocity vectors for non-mechanical mappings. It provides methods to access various vector data, manage force accumulations, and compute bounding boxes.",
  "maths": "The `State` class in the SOFA framework serves as a fundamental component for managing position and velocity vectors, providing an interface to handle various vector data types such as positions, velocities, forces, displacements, and normals. It does not directly implement governing equations or operators (e.g., mass matrix $M$, stiffness matrix $K$, internal force $f_{int}$, residual $R$) but rather provides a structured way to access and manipulate these quantities.\n\n### Constitutive / Kinematic Laws:\n- The class itself does not encode any constitutive laws such as strain measures, stress tensors, hyperelastic potentials, or damping models. However, it is designed to be extended by classes that do implement such laws (e.g., `MechanicalState`).\n- The class defines several internal types: scalar values (`Real`), position values (`Coord`), derivative values such as velocity and force (`Deriv`), containers for vectors of coordinates (`VecCoord`) and derivatives (`VecDeriv`), and a vector of Jacobians for sparse constraint matrices (`MatrixDeriv`).\n\n### Role in the FEM Pipeline:\n- **Data Access:** The `State` class provides methods to read from and write to position, rest positions, velocities, forces, displacements, and normal vectors. These accessors use helper classes such as `ReadAccessor`, `WriteAccessor`, and `WriteOnlyAccessor` to facilitate safe and efficient data manipulation.\n- **Forces Accumulation:** It includes a member variable `accumulatedForces` of type `AccumulationVecId<TDataTypes, V_DERIV, V_READ>` for managing the cumulative sum of all force containers. Methods `addToTotalForces()` and `removeFromTotalForces()` allow adding or removing specific force vectors from this accumulation.\n- **Vector ID Based Access:** The class offers virtual methods like `write(VecCoordId v)` and `read(ConstVecCoordId v)`, which must be implemented by derived classes to provide generic access to vector data using identifiers (`VecId`).\n\n### Numerical Methods / Discretization Choices:\n- While the `State` class itself does not discretize or integrate governing equations, it provides a framework for managing discrete state variables such as positions and velocities. These are essential components in the FEM pipeline.\n- The methods like `computeBBox()` compute the bounding box encompassing all points in the state's coordinate vectors, which is useful for spatial queries and collision detection.\n\n### Variational / Lagrangian Mechanics Framework:\n- Although the `State` class does not directly contribute to variational formulations or Lagrangian mechanics, it serves as a critical component by storing the positions ($\textbf{q}$) and velocities ($\textbf{\boldsymbol{\boldsymbol{\boldsymbol{\boldsymbol{\boldsymbol{\boldsymbol{\boldsymbol{\boldsymbol{\boldsymbol{\boldsymbol{\boldsymbol{\boldsymbol{\boldsymbol{\boldsymbol{\boldsymbol{\boldsymbol{\boldsymbol{\boldsymbol{\boldsymbol{\\dot q}}}}}}}}}}}}}}}}}}$) that are fundamental in Lagrangian mechanics. For example, the Lagrangian $\\mathcal{L}(q, \\dot{q}) = T(q, \\dot{q}) - V(q)$ relies on these quantities.\n\nIn summary, the `State` class is a foundational component for managing discrete state data in SOFA simulations, enabling consistent and structured access to positions, velocities, forces, and other derived quantities.",
  "abstract": "`State` manages position and velocity vectors, providing an interface for non-mechanical mappings within the simulation model.",
  "sheet": "# State\n\n## Overview\nThe `State` class in SOFA is a templated base component that stores and provides access to position and velocity vectors. It serves as a source or destination of regular (non-mechanical) mappings, defining an interface for accessing various vector data types such as positions (`Coord`), velocities (`Deriv`), forces, displacements, and normals.\n\n## Parameters and Data\nThe `State` class does not expose any significant Data fields. Its functionality is primarily through methods that provide access to position, velocity, force, displacement, and normal vectors.\n\n## Dependencies and Connections\nThis component typically requires or exchanges data with other components such as MechanicalState or MappedModel, which specialize the state management for mechanical simulations or non-mechanical models like visual representations. It fits into the scene graph by serving as a foundational interface for accessing state-related data."
}