Data Fields

Methods

{
  "name": "TypedMatrixLinearSystem",
  "namespace": "sofa::component::linearsystem",
  "module": "Sofa.Component.LinearSystem",
  "include": "sofa/component/linearsystem/TypedMatrixLinearSystem.h",
  "doc": "Component storing a global matrix representing a linear system",
  "inherits": [
    "BaseMatrixLinearSystem"
  ],
  "templates": [
    "BlockDiagonalMatrix<3, double>, FullVector<double>",
    "BlockDiagonalMatrix<3, float>, FullVector<float>",
    "DiagonalMatrix<double>, FullVector<double>",
    "DiagonalMatrix<float>, FullVector<float>",
    "FullMatrix<double>, FullVector<double>",
    "FullMatrix<float>, FullVector<float>",
    "RotationMatrix<double>, FullVector<double>",
    "RotationMatrix<float>, FullVector<float>",
    "SparseMatrix<double>, FullVector<double>",
    "SparseMatrix<float>, FullVector<float>"
  ],
  "data_fields": [
    {
      "name": "d_matrixChanged",
      "type": "bool",
      "xmlname": "factorizationInvalidation",
      "help": "Internal Data indicating a change in the matrix"
    },
    {
      "name": "m_linearSystem",
      "type": "TMatrix, TVector"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "GetCustomTemplateName",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "public"
    },
    {
      "name": "getSystemMatrix",
      "return_type": "TMatrix *",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getRHSVector",
      "return_type": "TVector *",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getSolutionVector",
      "return_type": "TVector *",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getSystemBaseMatrix",
      "return_type": "linearalgebra::BaseMatrix *",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getSystemRHSBaseVector",
      "return_type": "linearalgebra::BaseVector *",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getSystemSolutionBaseVector",
      "return_type": "linearalgebra::BaseVector *",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "resizeSystem",
      "return_type": "void",
      "params": [
        {
          "name": "n",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "clearSystem",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setRHS",
      "return_type": "void",
      "params": [
        {
          "name": "v",
          "type": "core::MultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setSystemSolution",
      "return_type": "void",
      "params": [
        {
          "name": "v",
          "type": "core::MultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "dispatchSystemSolution",
      "return_type": "void",
      "params": [
        {
          "name": "v",
          "type": "core::MultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "dispatchSystemRHS",
      "return_type": "void",
      "params": [
        {
          "name": "v",
          "type": "core::MultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getSolveContext",
      "return_type": "core::objectmodel::BaseContext *",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "preAssembleSystem",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const core::MechanicalParams *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "associateLocalMatrixToComponents",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "const core::MechanicalParams *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "allocateSystem",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "resizeVectors",
      "return_type": "void",
      "params": [
        {
          "name": "n",
          "type": "int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "copyLocalVectorToGlobalVector",
      "return_type": "void",
      "params": [
        {
          "name": "v",
          "type": "core::MultiVecDerivId"
        },
        {
          "name": "globalVector",
          "type": "TVector *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getContributionFactor",
      "return_type": "SReal",
      "params": [
        {
          "name": "mparams",
          "type": "const sofa::core::MechanicalParams *"
        },
        {
          "name": "object",
          "type": "const int *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": true,
      "access": "protected"
    }
  ],
  "description": "The `TypedMatrixLinearSystem` is a SOFA component that stores and manages a global matrix representing a linear system, typically used in the context of solving systems of equations for simulation purposes. It inherits from `BaseMatrixLinearSystem`, indicating its role in the management and representation of linear systems within the SOFA framework.\n\nThe component supports various types of matrices (e.g., FullMatrix, SparseMatrix, DiagonalMatrix) and vectors (FullVector), allowing flexibility in representing different forms of linear systems. It provides methods to access matrix data such as system matrix, right-hand side (RHS) vector, solution vector, and base matrix/vector representations through the API.\n\n`TypedMatrixLinearSystem` interacts with other SOFA components by managing dependencies and relationships between mechanical states and their associated components via a `MappingGraph`. It also handles operations like resizing vectors, clearing systems, setting RHS and solutions, and dispatching results back to local vectors. The internal field `d_matrixChanged` indicates changes in the matrix state for synchronization purposes.\n\nThis component is essential for assembling global matrices from local contributions (force fields, masses) and solving linear equations that arise during simulation steps.",
  "maths": "The `TypedMatrixLinearSystem` component in the SOFA framework is designed to manage a global matrix representing a linear system, which is fundamental for solving systems of equations that arise during finite element simulations. This component supports various types of matrices (e.g., FullMatrix, SparseMatrix, DiagonalMatrix) and vectors (FullVector), providing flexibility in handling different forms of linear systems. The mathematical description can be summarized as follows:\n\n### Governing Equations and Operators\nThe `TypedMatrixLinearSystem` manages the global matrix system that typically takes the form of a linear equation represented by:\n\begin{align*}\nA \bm{x} = \bm{b},\n\tag{1}\n\tag{Global Linear System}\n\tag{where A is the coefficient matrix, x represents the unknown vector, and b is the right-hand side (RHS) vector. The component provides methods to access and manipulate these entities through:\n\n- `getSystemMatrix()`: Accesses the global coefficient matrix $A$.\n- `getRHSVector()`: Retrieves the RHS vector $\bm{b}$.\n- `getSolutionVector()`: Obtains the solution vector $\bm{x}$.}\n\n### Role in FEM Pipeline\nIn the context of FEM simulations, this component plays a critical role in assembling and solving global matrices. This process typically involves:\n\n1. **Matrix Assembly**: The system matrix $A$ is assembled from contributions by various force fields, masses, constraints, and mappings.\n2. **Solving Linear Systems**: After assembly, the linear system (Equation 1) is solved to obtain the solution vector $\bm{x}$, which represents the nodal displacements or other unknowns in a mechanical system.\n\n### Numerical Methods and Discretization Choices\nThe `TypedMatrixLinearSystem` supports various types of matrices to accommodate different discretization choices:\n- **FullMatrix**: Suitable for dense systems where all elements are stored explicitly.\n- **SparseMatrix**: Efficient for sparse systems with many zero entries, where only non-zero elements are stored.\n- **DiagonalMatrix**: Used when the matrix is diagonal, simplifying storage and computations to just the diagonal elements.\n\n### Constraint Handling\nThe component interacts with constraint projections by managing dependencies and relationships between mechanical states through a `MappingGraph`. This ensures that constraints (holonomic or non-holonomic) are properly enforced within the linear system solution process.\n\n### Mapping and Projection\n- **`copyLocalVectorToGlobalVector()`**: Transforms local vectors to global vectors for assembly into the global matrix.\n- **`dispatchSystemSolution()`** and **`dispatchSystemRHS()`**: Distribute global results back to local vectors, ensuring consistency across different levels of simulation detail.\n\n### Integration with Variational Mechanics Framework\nThe `TypedMatrixLinearSystem` is integrated within a broader variational mechanics framework where the linear system (Equation 1) arises from spatial and temporal discretization steps. It supports implicit time integration schemes such as Backward Euler, where the global matrix $A$ includes contributions from mass and stiffness matrices (and possibly damping), leading to equations of motion in the form:\n\begin{align*}\nM \bm{\frac{x_{n+1}-x_n}{\\Delta t}} + K(\bm{x}_{n+1}) = \\bm{f}_{ext}(t_{n+1}).\n\tag{2}\n\tag{Nonlinear ODE System in Nodal DOFs.}\n\nHere, $M$ represents the mass matrix, $K$ is the stiffness matrix (potentially nonlinear), and $\bm{f}_{ext}$ are external forces.\n\n### Conclusion\nThe `TypedMatrixLinearSystem` is a versatile component within SOFA that manages linear systems arising from FEM simulations. It supports various types of matrices for efficient storage and solution of large-scale problems, integrates seamlessly with constraint handling and mapping operations, and fits into the broader framework of variational mechanics by supporting implicit time integration schemes.",
  "abstract": "The `TypedMatrixLinearSystem` manages a global matrix representing a linear system in SOFA simulations, supporting various matrix types for efficient storage and solution of large-scale problems.",
  "sheet": "# TypedMatrixLinearSystem\n\n## Overview\nThe `TypedMatrixLinearSystem` is a component that stores and manages a global matrix representing a linear system. It supports different matrix types (e.g., FullMatrix, SparseMatrix) and vectors (FullVector), enabling efficient storage and solution of large-scale problems in SOFA simulations.\n\n## Mathematical Model\nThe `TypedMatrixLinearSystem` handles the assembly and solving of linear systems represented by:\n\\[ A \\mathbf{x} = \\mathbf{b}, \\]\nwhere $A$ is the coefficient matrix, $\\mathbf{x}$ represents the unknown vector, and $\\mathbf{b}$ is the right-hand side (RHS) vector. This component supports various types of matrices for efficient storage and solution:\n- **FullMatrix**: Suitable for dense systems.\n- **SparseMatrix**: Efficient for sparse systems with many zero entries.\n- **DiagonalMatrix**: Used when the matrix is diagonal, simplifying storage to just the diagonal elements.\n\n## Parameters and Data\nThe component exposes significant data fields that control its behavior:\n- `d_matrixChanged`: A boolean indicating a change in the matrix state for synchronization purposes (`factorizationInvalidation`).\n- `m_linearSystem`: Stores the linear system as a pair of matrix and vector types (`TMatrix, TVector`)."
}