Data Fields

Methods

{
  "name": "MatrixLinearSystem",
  "namespace": "sofa::component::linearsystem",
  "module": "Sofa.Component.LinearSystem",
  "include": "sofa/component/linearsystem/MatrixLinearSystem.h",
  "doc": "Linear system.\n\nAssemble the global matrix using local matrix components\nComponents add their contributions directly to the global matrix, through their local matrices.\nLocal matrices act as a proxy (they don't really store a local matrix). They have a link to the global matrix and\nan offset parameter to add the contribution into the right entry into the global matrix.\n@tparam TMatrix The type of the data structure used to represent the global matrix. In the general cases, this type\nderives from sofa::linearalgebra::BaseMatrix.\n@tparam TVector The type of the data structure used to represent the vectors of the linear system: the right-hand\nside and the solution. In the general cases, this type derives from sofa::linearalgebra::BaseVector.",
  "inherits": [
    "TypedMatrixLinearSystem"
  ],
  "templates": [
    "BlockDiagonalMatrix<3, SReal>, FullVector<SReal>",
    "DiagonalMatrix<SReal>, FullVector<SReal>",
    "FullMatrix<SReal>, FullVector<SReal>",
    "RotationMatrix<SReal>, FullVector<SReal>",
    "SparseMatrix<SReal>, FullVector<SReal>"
  ],
  "data_fields": [
    {
      "name": "d_assembleStiffness",
      "type": "bool",
      "xmlname": "assembleStiffness",
      "help": "If true, the stiffness is added to the global matrix"
    },
    {
      "name": "d_assembleMass",
      "type": "bool",
      "xmlname": "assembleMass",
      "help": "If true, the mass is added to the global matrix"
    },
    {
      "name": "d_assembleDamping",
      "type": "bool",
      "xmlname": "assembleDamping",
      "help": "If true, the damping is added to the global matrix"
    },
    {
      "name": "d_assembleGeometricStiffness",
      "type": "bool",
      "xmlname": "assembleGeometricStiffness",
      "help": "If true, the geometric stiffness of mappings is added to the global matrix"
    },
    {
      "name": "d_applyProjectiveConstraints",
      "type": "bool",
      "xmlname": "applyProjectiveConstraints",
      "help": "If true, projective constraints are applied on the global matrix"
    },
    {
      "name": "d_applyMappedComponents",
      "type": "bool",
      "xmlname": "applyMappedComponents",
      "help": "If true, mapped components contribute to the global matrix"
    },
    {
      "name": "d_checkIndices",
      "type": "bool",
      "xmlname": "checkIndices",
      "help": "If true, indices are verified before being added in to the global matrix, favoring security over speed"
    },
    {
      "name": "d_parallelAssemblyIndependentMatrices",
      "type": "bool",
      "xmlname": "parallelAssemblyIndependentMatrices",
      "help": "If true, independent matrices (global matrix vs mapped matrices) are assembled in parallel"
    },
    {
      "name": "m_needClearLocalMatrices",
      "type": "bool"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "getMappingGraph",
      "return_type": "const MappingGraph &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMassObserver",
      "return_type": "MappedMassMatrixObserver<Real> *",
      "params": [
        {
          "name": "mass",
          "type": "BaseMass *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "contribute",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "contributors",
          "type": "IndependentContributors &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "assembleSystem",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "makeLocalMatrixGroups",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "makeIndependentLocalMatrixGroups",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "associateLocalMatrixToComponents",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "cleanLocalMatrices",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getLocalMatrixMap",
      "return_type": "LocalMatrixMaps<c, Real> &",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "associateLocalMatrixTo",
      "return_type": "void",
      "params": [
        {
          "name": "component",
          "type": "int *"
        },
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "createLocalMatrixT",
      "return_type": "BaseAssemblingMatrixAccumulator<c> *",
      "params": [
        {
          "name": "object",
          "type": "int *"
        },
        {
          "name": "factor",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "createLocalMappedMatrixT",
      "return_type": "AssemblingMappedMatrixAccumulator<c, Real> *",
      "params": [
        {
          "name": "object",
          "type": "int *"
        },
        {
          "name": "factor",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "projectMappedMatrices",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "destination",
          "type": "linearalgebra::BaseMatrix *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "assembleMappedMatrices",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "applyProjectiveConstraints",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getSharedMatrix",
      "return_type": "int",
      "params": [
        {
          "name": "object",
          "type": "int *"
        },
        {
          "name": "pair",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getSharedMatrixSize",
      "return_type": "int",
      "params": [
        {
          "name": "object",
          "type": "int *"
        },
        {
          "name": "pair",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "setSharedMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "object",
          "type": "int *"
        },
        {
          "name": "pair",
          "type": "const int &"
        },
        {
          "name": "matrix",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getContributors",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "buildGroupsOfComponentAssociatedToMechanicalStates",
      "return_type": "void",
      "params": [
        {
          "name": "groups",
          "type": "int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "makeCreateDispatcher",
      "return_type": "void",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "makeIndexVerificationStrategy",
      "return_type": "int",
      "params": [
        {
          "name": "component",
          "type": "sofa::core::objectmodel::BaseObject *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "createMatrixMapping",
      "return_type": "int",
      "params": [
        {
          "name": "pair",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "findProjectionMethod",
      "return_type": "int *",
      "params": [
        {
          "name": "pair",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "assemblePrecomputedMappedMassMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "destination",
          "type": "linearalgebra::BaseMatrix *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "recomputeMappedMassMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "mass",
          "type": "BaseMass *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `MatrixLinearSystem` is a core component in the SOFA framework responsible for assembling and managing linear systems, particularly relevant for mechanical simulations involving global matrix operations. It assembles the global matrix by collecting contributions from local matrices associated with different components such as stiffness, mass, damping, and geometric stiffness.\n\nThis component supports various types of matrix representations (e.g., SparseMatrix, FullMatrix, DiagonalMatrix) and vectors through template parameters `TMatrix` and `TVector`. The assembly process is customizable via boolean data fields (`assembleStiffness`, `assembleMass`, etc.), which control whether specific contributions are added to the global matrix. Additional options include applying projective constraints and checking indices for safety.\n\nInteractions with other SOFA components occur primarily through mechanisms such as MechanicalParams, BaseForceField, BaseMass, BaseMapping, and BaseProjectiveConstraintSet. The component manages these interactions via its protected methods like `contribute`, `assembleSystem`, and `associateLocalMatrixToComponents`. It ensures the global matrix is correctly sized and updated based on contributions from local matrices.\n\nIn practical usage, users can configure options to include/exclude specific types of matrix contributions and enable parallel assembly for performance gains. The component also supports index verification for added safety during matrix assembly.",
  "maths": "The `MatrixLinearSystem` is a critical component in the SOFA framework that manages the assembly and manipulation of global linear systems, which are essential for mechanical simulations. The primary role of this component is to combine contributions from various local matrices associated with different types of components (e.g., stiffness, mass, damping) into a single global matrix. Below is a detailed mathematical and physical description:\n\n### Governing Equations and Operators\n\nThe `MatrixLinearSystem` contributes to the following governing equations in a mechanical system simulation:\n- **Mass Matrix** (\boldsymbol{M}): Represents the inertia of the system.\n  \\[ \boldsymbol{M} = \\sum_{i} \\rho_i N_i^T N_i d\\Omega \\]\n  where \\(N_i\\) are shape functions and \\(\rho_i\\) is the density.\n- **Stiffness Matrix** (\boldsymbol{K}): Represents the elastic forces of the system, derived from Hooke's law or more complex constitutive relations (e.g., hyperelasticity).\n  \\[ \boldsymbol{K} = \\sum_{i} B_i^T \\sigma_i d\\Omega \\]\n  where \\(B_i\\) are strain-displacement matrices and \\(\boldsymbol{σ}_i\\) is the stress tensor.\n- **Damping Matrix** (\boldsymbol{C}): Represents damping forces, often derived from Rayleigh damping or other forms of damping models.\n  \\[ \boldsymbol{C} = \\sum_{i} N_i^T C_i N_i d\\Omega \\]\n- **Geometric Stiffness Matrix**: Represents stiffness contributions due to large deformations.\n\nThe global matrix (\boldsymbol{A}) is assembled by summing these matrices:\n  \\[ \boldsymbol{A} = \boldsymbol{M} + \boldsymbol{K} + \boldsymbol{C} + \text{Geometric Stiffness Matrix} \\]\n\n### Constitutive and Kinematic Laws Involved\n\nThe `MatrixLinearSystem` can incorporate various constitutive models, such as:\n- **Linear Elasticity**: Hooke's law for small strains.\n  \\[ \boldsymbol{σ} = \boldsymbol{C} : \boldsymbol{ε}(\\mathbf{u}) \\]\n- **Hyperelastic Models** (St-Venant–Kirchhoff, Neo-Hookean, Mooney-Rivlin): For large deformations.\n  \\[ W(κ_1, κ_2, κ_3) = f(\text{invariants of } \boldsymbol{C}) \\]\n\nStrain measures used include Green-Lagrange strains for finite deformations:\n\\[ \boldsymbol{ε} = \\frac{1}{2}(\\nabla Υ + (Υ^T Υ - I)) \\]\n\n### Role in the Global FEM Pipeline\n\nThe `MatrixLinearSystem` plays a central role in the assembly phase of the global finite element system. Its primary functions include:\n- **Assembling Local Contributions**: The component collects contributions from local stiffness, mass, damping matrices and geometric stiffness into the global matrix.\n  \\[ \boldsymbol{A}_{ij} = \text{sum}(local\\_contributions) \\]\n- **Time Integration**: The assembled system is used in time integration schemes such as implicit Euler or Newmark methods to advance the state of the mechanical system over time.\n  \\[ M\frac{x_{n+1}-x_n}{Δ t}=v_{n+1} \\\n  v_{n+1}-v_n = Δ t M^{-1}(f_{ext} - f_{int}) \\]\n- **Nonlinear Solve**: In nonlinear dynamics, the global matrix is used in Newton-Raphson iterations to solve for the displacement field.\n  \\[ J(x_k)Δ x_k = -R(x_k) \\\n  x_{k+1} = x_k + Δ x_k \\]\n- **Constraint Handling**: The component supports projective constraints and enforces them on the global matrix.\n\n### Numerical Methods and Discretization Choices\n\nThe `MatrixLinearSystem` utilizes various numerical methods for discretization, including:\n- **Finite Element Method (FEM)**: Spatial discretization using shape functions to interpolate displacements within elements.\n  \\[ Υ(X) ≈ Σ_i N_i(X) u_i(t) \\]\n- **Gauss Quadrature**: Numerical integration for evaluating matrix and vector terms in the weak form.\n  \\[ \\int_{Ω} f(ξ)dξ ≈ Σ_q w_q f(ξ_q) \\]\n- **Sparse Matrix Storage**: Efficient storage formats like Compressed Row Sparse (CRS) for sparse matrices.\n\n### Broad Variational/Lagrangian Mechanics Framework Fit\n\nThe `MatrixLinearSystem` is integral to the variational mechanics framework of SOFA, where the Lagrangian formulation is used to derive equations of motion. The global matrix assembly process ensures that all components contributing to the system's energy (kinetic and potential) are properly accounted for in a consistent manner.\n\nIn summary, the `MatrixLinearSystem` component is pivotal for assembling and solving large-scale linear systems derived from variational formulations in mechanical simulations within SOFA.",
  "abstract": "The `MatrixLinearSystem` assembles the global linear system by collecting contributions from local matrices associated with stiffness, mass, damping, and geometric stiffness, supporting various matrix types through template parameters.",
  "sheet": "# MatrixLinearSystem\n\n## Overview\nThe `MatrixLinearSystem` is a core component in SOFA responsible for assembling the global matrix used in mechanical simulations. It collects contributions from local matrices associated with different components such as stiffness, mass, damping, and geometric stiffness. The assembly process can be customized via boolean data fields to include or exclude specific types of contributions.\n\n## Mathematical Model\nThe `MatrixLinearSystem` contributes to the following governing equations in a mechanical system simulation:\n- **Mass Matrix** (\\( \\mathbf{M} \\)): Represents the inertia of the system.\n  \\[ \\mathbf{M} = \\sum_{i} \\rho_i N_i^T N_i d\\Omega \\]\n  where \\(N_i\\) are shape functions and \\(\\rho_i\\) is the density.\n- **Stiffness Matrix** (\\( \\mathbf{K} \\)): Represents the elastic forces of the system, derived from Hooke's law or more complex constitutive relations (e.g., hyperelasticity).\n  \\[ \\mathbf{K} = \\sum_{i} B_i^T \\sigma_i d\\Omega \\]\n  where \\(B_i\\) are strain-displacement matrices and \\(\\boldsymbol{σ}_i\\) is the stress tensor.\n- **Damping Matrix** (\\( \\mathbf{C} \\)): Represents damping forces, often derived from Rayleigh damping or other forms of damping models.\n  \\[ \\mathbf{C} = \\sum_{i} N_i^T C_i N_i d\\Omega \\]\n- **Geometric Stiffness Matrix**: Represents stiffness contributions due to large deformations.\n\nThe global matrix (\\( \\mathbf{A} \\)) is assembled by summing these matrices:\n  \\[ \\mathbf{A} = \\mathbf{M} + \\mathbf{K} + \\mathbf{C} + \\text{Geometric Stiffness Matrix} \\]\n\n## Parameters and Data\nThe `MatrixLinearSystem` exposes several boolean data fields to control the assembly process:\n- **assembleStiffness**: If true, the stiffness is added to the global matrix.\n- **assembleMass**: If true, the mass is added to the global matrix.\n- **assembleDamping**: If true, the damping is added to the global matrix.\n- **assembleGeometricStiffness**: If true, the geometric stiffness of mappings is added to the global matrix.\n- **applyProjectiveConstraints**: If true, projective constraints are applied on the global matrix.\n- **applyMappedComponents**: If true, mapped components contribute to the global matrix.\n- **checkIndices**: If true, indices are verified before being added into the global matrix, favoring security over speed.\n- **parallelAssemblyIndependentMatrices**: If true, independent matrices (global matrix vs. mapped matrices) are assembled in parallel."
}