`BaseMechanicalState` manages state vectors (positions, velocities, forces) for simulated bodies without performing active computations.
sheet
# BaseMechanicalState
## Overview
The `BaseMechanicalState` class is an abstract base component in the SOFA framework that stores all state vectors of a simulated body, including positions (`position`), velocities (`velocity`), forces (`force`), and displacements (`dx`). It does not handle active computations but serves as a data container for other components such as Mass, ForceField, and LagrangianConstraint.
## Parameters and Data
The `BaseMechanicalState` class manages several predefined state vectors:
- **Position:** Stores the spatial coordinates of points within the object (`position`).
- **Velocity:** Represents the time derivatives of positions (`velocity`).
- **Force:** Captures forces acting on the object (`force`).
- **Displacement:** Indicates changes in position over time (`dx`).
Additionally, it supports dynamic allocation and reallocation of vectors for temporary values.
## Dependencies and Connections
`BaseMechanicalState` is typically used in conjunction with other components such as Mass, ForceField, and LagrangianConstraint. These components rely on the state data managed by `BaseMechanicalState` to perform their respective computations.
name
BaseMechanicalState
author
category
Component
componentName
BaseMechanicalState
componentNamespace
sofa::core::behavior
headerFile
BaseMechanicalState.h
briefDescription
Abstract class for mechanical states.
detailedDescription
The `BaseMechanicalState` is an abstract class in the Sofa framework that serves as a foundation for implementing various types of mechanical state models. It provides methods and interfaces necessary to manage physical properties such as positions, velocities, forces, etc., which are essential for simulating deformable objects or rigid bodies.
### Key Features:
- **Mechanical State Management**: This class defines the interface that any concrete implementation must adhere to in order to represent a mechanical state within Sofa simulations. The state can include properties like position, velocity, force, and other attributes relevant to physical simulation.
- **Vector Operations**: Implements methods for vector operations such as addition, scalar multiplication, etc., on different types of data (positions, velocities, forces). These are crucial for the numerical integration schemes used in time-stepping solvers.
- **Integration with Linear Algebra Libraries**: Provides mechanisms to interface with Sofa's linear algebra libraries, allowing for efficient matrix and vector manipulations required for solving systems of equations that arise from discretization of physical laws (e.g., Newton's laws).
- **Data Output**: Includes methods for outputting the state data in formats suitable for visualization or analysis.
### Usage:
The `BaseMechanicalState` is not meant to be instantiated directly but rather serves as a base class. Concrete implementations like `MechanicalObject`, which represent specific types of mechanical states (e.g., deformable objects, rigid bodies), inherit from this abstract class and provide their own specialized behavior.
### Example:
The following is an example of how one might define a concrete implementation inheriting from `BaseMechanicalState`:
```cpp
namespace sofa::core::behavior {
class MyCustomObject : public BaseMechanicalState {
public:
SOFA_CLASS(MyCustomObject, BaseMechanicalState);
// Implement required methods here...
};
}
```
In this example, `MyCustomObject` would need to implement all the pure virtual functions defined in `BaseMechanicalState`, providing specific functionality for managing its mechanical state.
The `BaseMechanicalState` class in the SOFA (Simulation Open-Framework Architecture) framework is designed to manage mechanical states, which include position, velocity, force, and other related physical properties for objects within a simulation. This class serves as an abstract base for various concrete implementations that might handle specific types of objects or interactions.
### Mathematical Description
#### Vectors and Operations
- **Vectors:** The `BaseMechanicalState` uses different vectors to store the state of objects, such as positions (`x`), velocities (`v`), accelerations (`a`), forces (`f`), etc. These are represented using vector identifiers (e.g., `VecId`, `ConstVecId`).
- **Operations on Vectors:** The class provides methods for performing linear operations on these vectors, such as addition and scalar multiplication.
#### Linear Vector Accumulation Operation
The method `vMultiOp` allows for the accumulation of multiple vector operations in a single step. For example, given an operation defined by:
- `r_i = sum_j (v_j * f_{ij})`
This can be used to compute expressions like:
- `v = v + a*dt`
- `x = x + v*dt`
Here's the decomposition of operations if `nop` is the number of operands:
1. If there are no operands, perform a zero operation: `vOp(params, r)`.
2. If one operand with scalar 1.0: `vOp(params, r, operands[0].first.getId(this))`.
3. Otherwise, accumulate operations in multiple steps, where each step is defined by `vOp(params, r, r, operands[i].first.getId(this), operands[i].second)`.
### Physical Description
#### Mechanical State Management
- **Position and Displacement:** The position vectors represent the spatial coordinates of points within the object. Changes in these positions are displacements.
- **Velocity and Acceleration:** Velocities are the time derivatives of positions, while accelerations are the time derivatives of velocities.
- **Forces and Potentials:** Forces can be derived from potential energy functions or external forces applied to the system. These forces influence acceleration through Newton's second law: `F = m*a` (where `m` is mass).
#### Handling State Changes
The method `handleStateChange()` allows for updating the state of objects when there are changes in topology, such as adding or removing elements from a mesh.
### Data Operations
- **Copy and Transfer:** Methods like `copyToBaseVector`, `addToBaseVector`, etc., allow for transferring data between different representations (e.g., local vectors to global base vectors) used internally by the framework. These operations are critical for maintaining consistency between various components of SOFA.
### Data Output
The class supports methods for printing and exporting data, allowing users to visualize or log mechanical states during simulations.
{
"name": "BaseMechanicalState",
"main": {
"name": "BaseMechanicalState",
"namespace": "sofa::core::behavior",
"module": "Sofa.framework.Core",
"include": "sofa/core/behavior/BaseMechanicalState.h",
"doc": "Component storing all state vectors of a simulated body (position, velocity, etc).\n This class only contains the data of the body and not any of its\n <i>active</i> computations, which are handled by the Mass, ForceField, and\n LagrangianConstraint components.\n Two types of vectors are used :\n \\li \\code VecCoord \\endcode : containing positions.\n \\li \\code VecDeriv \\endcode : derivative values, i.e. velocity, forces, displacements.\n In most cases they are the same (i.e. 3D/2D point particles), but they can\n be different (rigid frames for instance).\n Several pre-defined vectors are stored :\n \\li \\code position \\endcode\n \\li \\code velocity \\endcode\n \\li \\code force \\endcode\n \\li \\code dx \\endcode (displacement)\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": [
"BaseState"
],
"templates": [],
"data_fields": [],
"links": [],
"methods": [
{
"name": "toBaseMechanicalState",
"return_type": "const BaseMechanicalState *",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getPX",
"return_type": "SReal",
"params": [
{
"name": "",
"type": "int"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getPY",
"return_type": "SReal",
"params": [
{
"name": "",
"type": "int"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getPZ",
"return_type": "SReal",
"params": [
{
"name": "",
"type": "int"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "vAvail",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "v",
"type": "VecCoordId &"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "vAvail",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "v",
"type": "VecDerivId &"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "vAlloc",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "v",
"type": "VecCoordId"
},
{
"name": "properties",
"type": "const core::VecIdProperties &"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "vAlloc",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "v",
"type": "VecDerivId"
},
{
"name": "properties",
"type": "const core::VecIdProperties &"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "vRealloc",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "v",
"type": "VecCoordId"
},
{
"name": "properties",
"type": "const core::VecIdProperties &"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "vRealloc",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "v",
"type": "VecDerivId"
},
{
"name": "properties",
"type": "const core::VecIdProperties &"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "vFree",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "v",
"type": "VecCoordId"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "vFree",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "v",
"type": "VecDerivId"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "vInit",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "v",
"type": "VecCoordId"
},
{
"name": "vSrc",
"type": "ConstVecCoordId"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "vInit",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "v",
"type": "VecDerivId"
},
{
"name": "vSrc",
"type": "ConstVecDerivId"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "vOp",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "v",
"type": "VecId"
},
{
"name": "a",
"type": "ConstVecId"
},
{
"name": "b",
"type": "ConstVecId"
},
{
"name": "f",
"type": "SReal"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "vMultiOp",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "ops",
"type": "const VMultiOp &"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "vDot",
"return_type": "SReal",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "a",
"type": "ConstVecId"
},
{
"name": "b",
"type": "ConstVecId"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "vSum",
"return_type": "SReal",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "a",
"type": "ConstVecId"
},
{
"name": "l",
"type": "unsigned int"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "vMax",
"return_type": "SReal",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "a",
"type": "ConstVecId"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "vSize",
"return_type": "int",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "v",
"type": "ConstVecId"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "vThreshold",
"return_type": "void",
"params": [
{
"name": "a",
"type": "VecId"
},
{
"name": "threshold",
"type": "SReal"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "beginIntegration",
"return_type": "void",
"params": [
{
"name": "",
"type": "SReal"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "endIntegration",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "",
"type": "SReal"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "resetForce",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "f",
"type": "VecDerivId"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "resetAcc",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "a",
"type": "VecDerivId"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "accumulateForce",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const ExecParams *"
},
{
"name": "f",
"type": "VecDerivId"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "resetConstraint",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const ConstraintParams *"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "getConstraintJacobian",
"return_type": "void",
"params": [
{
"name": "params",
"type": "const ConstraintParams *"
},
{
"name": "J",
"type": "sofa::linearalgebra::BaseMatrix *"
},
{
"name": "off",
"type": "unsigned int &"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "buildIdentityBlocksInJacobian",
"return_type": "void",
"params": [
{
"name": "list_n",
"type": "const int &"
},
{
"name": "mID",
"type": "core::MatrixDerivId &"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "constraintBlocks",
"return_type": "int",
"params": [
{
"name": "",
"type": "const int &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getConstraintJacobianTimesVecDeriv",
"return_type": "SReal",
"params": [
{
"name": "",
"type": "unsigned int"
},
{
"name": "",
"type": "ConstVecId"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "handleStateChange",
"return_type": "void",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "handleStateChange",
"return_type": "void",
"params": [
{
"name": "t",
"type": "core::topology::Topology *"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "writeState",
"return_type": "void",
"params": [
{
"name": "out",
"type": "int &"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"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": "applyTranslation",
"return_type": "void",
"params": [
{
"name": "dx",
"type": "const SReal"
},
{
"name": "dy",
"type": "const SReal"
},
{
"name": "dz",
"type": "const SReal"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "applyRotation",
"return_type": "void",
"params": [
{
"name": "",
"type": "const SReal"
},
{
"name": "",
"type": "const SReal"
},
{
"name": "",
"type": "const SReal"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "applyRotation",
"return_type": "void",
"params": [
{
"name": "q",
"type": "const type::Quat<SReal>"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "applyScale",
"return_type": "void",
"params": [
{
"name": "",
"type": "const SReal"
},
{
"name": "",
"type": "const SReal"
},
{
"name": "",
"type": "const SReal"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "getScale",
"return_type": "type::Vec3",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "addBBox",
"return_type": "bool",
"params": [
{
"name": "",
"type": "SReal *"
},
{
"name": "",
"type": "SReal *"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "pickParticles",
"return_type": "bool",
"params": [
{
"name": "",
"type": "const ExecParams *"
},
{
"name": "",
"type": "double"
},
{
"name": "",
"type": "double"
},
{
"name": "",
"type": "double"
},
{
"name": "",
"type": "double"
},
{
"name": "",
"type": "double"
},
{
"name": "",
"type": "double"
},
{
"name": "",
"type": "double"
},
{
"name": "",
"type": "double"
},
{
"name": "",
"type": "int &"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getMatrixBlockSize",
"return_type": "int",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getMatrixSize",
"return_type": "int",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "copyToBaseVector",
"return_type": "void",
"params": [
{
"name": "dest",
"type": "linearalgebra::BaseVector *"
},
{
"name": "src",
"type": "ConstVecId"
},
{
"name": "offset",
"type": "unsigned int &"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "copyFromBaseVector",
"return_type": "void",
"params": [
{
"name": "dest",
"type": "VecId"
},
{
"name": "src",
"type": "const linearalgebra::BaseVector *"
},
{
"name": "offset",
"type": "unsigned int &"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "copyToBaseMatrix",
"return_type": "void",
"params": [
{
"name": "dest",
"type": "linearalgebra::BaseMatrix *"
},
{
"name": "src",
"type": "ConstMatrixDerivId"
},
{
"name": "offset",
"type": "unsigned int &"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"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": true,
"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": true,
"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": true,
"is_static": false,
"access": "public"
},
{
"name": "addToBaseVector",
"return_type": "void",
"params": [
{
"name": "dest",
"type": "linearalgebra::BaseVector *"
},
{
"name": "src",
"type": "ConstVecId"
},
{
"name": "offset",
"type": "unsigned int &"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "addFromBaseVectorSameSize",
"return_type": "void",
"params": [
{
"name": "dest",
"type": "VecId"
},
{
"name": "src",
"type": "const linearalgebra::BaseVector *"
},
{
"name": "offset",
"type": "unsigned int &"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "addFromBaseVectorDifferentSize",
"return_type": "void",
"params": [
{
"name": "dest",
"type": "VecId"
},
{
"name": "src",
"type": "const linearalgebra::BaseVector *"
},
{
"name": "offset",
"type": "unsigned int &"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "printDOF",
"return_type": "void",
"params": [
{
"name": "v",
"type": "ConstVecId"
},
{
"name": "out",
"type": "int &"
},
{
"name": "firstIndex",
"type": "int"
},
{
"name": "range",
"type": "int"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "printDOFWithElapsedTime",
"return_type": "unsigned int",
"params": [
{
"name": "",
"type": "ConstVecId"
},
{
"name": "",
"type": "unsigned int"
},
{
"name": "",
"type": "unsigned int"
},
{
"name": "",
"type": "int &"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "initGnuplot",
"return_type": "void",
"params": [
{
"name": "",
"type": "const int"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "exportGnuplot",
"return_type": "void",
"params": [
{
"name": "",
"type": "SReal"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "writeVec",
"return_type": "void",
"params": [
{
"name": "v",
"type": "ConstVecId"
},
{
"name": "out",
"type": "int &"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "readVec",
"return_type": "void",
"params": [
{
"name": "v",
"type": "VecId"
},
{
"name": "in",
"type": "int &"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "compareVec",
"return_type": "SReal",
"params": [
{
"name": "v",
"type": "ConstVecId"
},
{
"name": "in",
"type": "int &"
}
],
"is_virtual": true,
"is_pure_virtual": true,
"is_static": false,
"access": "public"
},
{
"name": "insertInNode",
"return_type": "bool",
"params": [
{
"name": "node",
"type": "objectmodel::BaseNode *"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "removeInNode",
"return_type": "bool",
"params": [
{
"name": "node",
"type": "objectmodel::BaseNode *"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
}
]
},
"desc": {
"name": "BaseMechanicalState",
"author": "",
"category": "Component",
"componentName": "BaseMechanicalState",
"componentNamespace": "sofa::core::behavior",
"headerFile": "BaseMechanicalState.h",
"briefDescription": "Abstract class for mechanical states.",
"detailedDescription": "The `BaseMechanicalState` is an abstract class in the Sofa framework that serves as a foundation for implementing various types of mechanical state models. It provides methods and interfaces necessary to manage physical properties such as positions, velocities, forces, etc., which are essential for simulating deformable objects or rigid bodies.\n\n### Key Features:\n- **Mechanical State Management**: This class defines the interface that any concrete implementation must adhere to in order to represent a mechanical state within Sofa simulations. The state can include properties like position, velocity, force, and other attributes relevant to physical simulation.\n\n- **Vector Operations**: Implements methods for vector operations such as addition, scalar multiplication, etc., on different types of data (positions, velocities, forces). These are crucial for the numerical integration schemes used in time-stepping solvers.\n\n- **Integration with Linear Algebra Libraries**: Provides mechanisms to interface with Sofa's linear algebra libraries, allowing for efficient matrix and vector manipulations required for solving systems of equations that arise from discretization of physical laws (e.g., Newton's laws).\n\n- **Data Output**: Includes methods for outputting the state data in formats suitable for visualization or analysis.\n\n### Usage:\nThe `BaseMechanicalState` is not meant to be instantiated directly but rather serves as a base class. Concrete implementations like `MechanicalObject`, which represent specific types of mechanical states (e.g., deformable objects, rigid bodies), inherit from this abstract class and provide their own specialized behavior.\n\n### Example:\nThe following is an example of how one might define a concrete implementation inheriting from `BaseMechanicalState`:\n```cpp\nnamespace sofa::core::behavior {\n\nclass MyCustomObject : public BaseMechanicalState {\npublic:\n SOFA_CLASS(MyCustomObject, BaseMechanicalState);\n \n // Implement required methods here...\n};\n}\n```\nIn this example, `MyCustomObject` would need to implement all the pure virtual functions defined in `BaseMechanicalState`, providing specific functionality for managing its mechanical state.",
"inheritance": [
{
"type": "objectmodel::Component",
"name": "sofa::core::objectmodel::Base"
}
],
"implementsInterfaces": [],
"providesServices": []
},
"maths": {
"maths": "The `BaseMechanicalState` class in the SOFA (Simulation Open-Framework Architecture) framework is designed to manage mechanical states, which include position, velocity, force, and other related physical properties for objects within a simulation. This class serves as an abstract base for various concrete implementations that might handle specific types of objects or interactions.\n\n### Mathematical Description\n\n#### Vectors and Operations\n- **Vectors:** The `BaseMechanicalState` uses different vectors to store the state of objects, such as positions (`x`), velocities (`v`), accelerations (`a`), forces (`f`), etc. These are represented using vector identifiers (e.g., `VecId`, `ConstVecId`).\n- **Operations on Vectors:** The class provides methods for performing linear operations on these vectors, such as addition and scalar multiplication.\n\n#### Linear Vector Accumulation Operation\nThe method `vMultiOp` allows for the accumulation of multiple vector operations in a single step. For example, given an operation defined by:\n- `r_i = sum_j (v_j * f_{ij})`\n\nThis can be used to compute expressions like:\n- `v = v + a*dt`\n- `x = x + v*dt`\n\nHere's the decomposition of operations if `nop` is the number of operands:\n1. If there are no operands, perform a zero operation: `vOp(params, r)`.\n2. If one operand with scalar 1.0: `vOp(params, r, operands[0].first.getId(this))`.\n3. Otherwise, accumulate operations in multiple steps, where each step is defined by `vOp(params, r, r, operands[i].first.getId(this), operands[i].second)`.\n\n### Physical Description\n\n#### Mechanical State Management\n- **Position and Displacement:** The position vectors represent the spatial coordinates of points within the object. Changes in these positions are displacements.\n- **Velocity and Acceleration:** Velocities are the time derivatives of positions, while accelerations are the time derivatives of velocities.\n- **Forces and Potentials:** Forces can be derived from potential energy functions or external forces applied to the system. These forces influence acceleration through Newton's second law: `F = m*a` (where `m` is mass).\n\n#### Handling State Changes\nThe method `handleStateChange()` allows for updating the state of objects when there are changes in topology, such as adding or removing elements from a mesh.\n\n### Data Operations\n- **Copy and Transfer:** Methods like `copyToBaseVector`, `addToBaseVector`, etc., allow for transferring data between different representations (e.g., local vectors to global base vectors) used internally by the framework. These operations are critical for maintaining consistency between various components of SOFA.\n\n### Data Output\nThe class supports methods for printing and exporting data, allowing users to visualize or log mechanical states during simulations."
},
"summary": {
"abstract": "`BaseMechanicalState` manages state vectors (positions, velocities, forces) for simulated bodies without performing active computations.",
"sheet": "# BaseMechanicalState\n\n## Overview\nThe `BaseMechanicalState` class is an abstract base component in the SOFA framework that stores all state vectors of a simulated body, including positions (`position`), velocities (`velocity`), forces (`force`), and displacements (`dx`). It does not handle active computations but serves as a data container for other components such as Mass, ForceField, and LagrangianConstraint.\n\n## Parameters and Data\nThe `BaseMechanicalState` class manages several predefined state vectors:\n- **Position:** Stores the spatial coordinates of points within the object (`position`).\n- **Velocity:** Represents the time derivatives of positions (`velocity`).\n- **Force:** Captures forces acting on the object (`force`).\n- **Displacement:** Indicates changes in position over time (`dx`).\n\nAdditionally, it supports dynamic allocation and reallocation of vectors for temporary values.\n\n## Dependencies and Connections\n`BaseMechanicalState` is typically used in conjunction with other components such as Mass, ForceField, and LagrangianConstraint. These components rely on the state data managed by `BaseMechanicalState` to perform their respective computations."
}
}