Data Fields

Methods

{
  "name": "MatrixProjectionMethod",
  "namespace": "sofa::component::linearsystem",
  "module": "Sofa.Component.LinearSystem",
  "include": "sofa/component/linearsystem/MatrixProjectionMethod.h",
  "doc": "Matrix mapping computing the matrix projection using the Eigen library.\n\nThe component is a @MatrixMapping computing the matrix projection using\nthe Eigen library.",
  "inherits": [
    "BaseMatrixProjectionMethod"
  ],
  "templates": [
    "sofa::linearalgebra::CompressedRowSparseMatrix<SReal>"
  ],
  "data_fields": [
    {
      "name": "d_areJacobiansConstant",
      "type": "bool",
      "xmlname": "areJacobiansConstant",
      "help": "True if mapping jacobians are considered constant over time. They are computed only the first time."
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "computeMatrixJacobians",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "mappingGraph",
          "type": "const MappingGraph &"
        },
        {
          "name": "matrixToProject",
          "type": "TMatrix *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "reinit",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "computeMatrixProduct",
      "return_type": "void",
      "params": [
        {
          "name": "mappingGraph",
          "type": "const MappingGraph &"
        },
        {
          "name": "matrixToProject",
          "type": "TMatrix *"
        },
        {
          "name": "globalMatrix",
          "type": "linearalgebra::BaseMatrix *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "projectMatrixToGlobalMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "mappingGraph",
          "type": "const MappingGraph &"
        },
        {
          "name": "matrixToProject",
          "type": "TMatrix *"
        },
        {
          "name": "globalMatrix",
          "type": "linearalgebra::BaseMatrix *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "identifyAffectedDoFs",
      "return_type": "int",
      "params": [
        {
          "name": "mstate",
          "type": "BaseMechanicalState *"
        },
        {
          "name": "crs",
          "type": "TMatrix *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "computeJacobiansFrom",
      "return_type": "MappingJacobians<TMatrix>",
      "params": [
        {
          "name": "mstate",
          "type": "BaseMechanicalState *"
        },
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "mappingGraph",
          "type": "const MappingGraph &"
        },
        {
          "name": "crs",
          "type": "TMatrix *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "getSolveContext",
      "return_type": "core::objectmodel::BaseContext *",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "addMappedMatrixToGlobalMatrixEigen",
      "return_type": "void",
      "params": [
        {
          "name": "mstatePair",
          "type": "int"
        },
        {
          "name": "mappedMatrix",
          "type": "TMatrix *"
        },
        {
          "name": "jacobians",
          "type": "int"
        },
        {
          "name": "mappingGraph",
          "type": "const MappingGraph &"
        },
        {
          "name": "globalMatrix",
          "type": "linearalgebra::BaseMatrix *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "makeEigenMap",
      "return_type": "int",
      "params": [
        {
          "name": "matrix",
          "type": "const TMatrix &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "computeProjection",
      "return_type": "void",
      "params": [
        {
          "name": "KMap",
          "type": "const int"
        },
        {
          "name": "",
          "type": "const int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "component": {
    "name": "MatrixProjectionMethod",
    "description": "The MatrixProjectionMethod is a component in the Sofa framework that implements matrix projection using the Eigen library. This component serves as an extension to BaseMatrixProjectionMethod and is specifically tailored for matrices represented by CompressedRowSparseMatrix<SReal>. It supports efficient computation of Jacobian matrices through mappings from a mechanical state to its top-most parent states.",
    "attributes": [
      {
        "name": "d_areJacobiansConstant",
        "type": "bool",
        "description": "A flag indicating whether the mapping jacobians are considered constant over time. If true, the jacobians are computed only once during the first execution."
      },
      {
        "name": "m_mappingJacobians",
        "type": "std::optional<sofa::type::fixed_array<MappingJacobians<TMatrix>, 2>>",
        "description": "Stores the mapping Jacobian matrices for each mechanical state. It is used in matrix projection operations."
      }
    ],
    "methods": [
      {
        "name": "computeMatrixJacobians",
        "parameters": [
          "core::MechanicalParams* mparams",
          "const MappingGraph& mappingGraph",
          "TMatrix* matrixToProject"
        ],
        "description": "Computes the Jacobian matrices of mappings from a mapped state to its top-most parent states."
      },
      {
        "name": "reinit",
        "parameters": [],
        "description": "Reinitializes the MatrixProjectionMethod component, typically called when changes in the simulation context necessitate resetting internal data structures or flags."
      },
      {
        "name": "computeMatrixProduct",
        "parameters": [
          "const MappingGraph& mappingGraph",
          "TMatrix* matrixToProject",
          "linearalgebra::BaseMatrix* globalMatrix"
        ],
        "description": "Computes the product of matrices using Eigen and adds it to the specified global matrix within the context of a given mapping graph."
      },
      {
        "name": "projectMatrixToGlobalMatrix",
        "parameters": [
          "const core::MechanicalParams* mparams",
          "const MappingGraph& mappingGraph",
          "TMatrix* matrixToProject",
          "linearalgebra::BaseMatrix* globalMatrix"
        ],
        "description": "Projects the local matrix into the main global matrix using Eigen library. This method handles efficient matrix operations and placements within the global matrix based on the given mechanical state mappings."
      },
      {
        "name": "identifyAffectedDoFs",
        "parameters": [
          "BaseMechanicalState* mstate",
          "TMatrix* crs"
        ],
        "description": "Identifies nodes affected by a specified matrix (CRS). Returns a list of indices corresponding to these nodes."
      },
      {
        "name": "computeJacobiansFrom",
        "parameters": [
          "BaseMechanicalState* mstate",
          "const core::MechanicalParams* mparams",
          "const MappingGraph& mappingGraph",
          "TMatrix* crs"
        ],
        "description": "Builds Jacobian matrices of mappings from a mechanical state to its top-most parent states. It applies the mappings in a bottom-up fashion and transfers these transformations into local matrix data structures."
      },
      {
        "name": "getSolveContext",
        "parameters": [],
        "description": "Retrieves the context associated with the linear solver used for solving the system of equations. This method ensures that the appropriate mechanical visitor has access to the correct simulation context during execution."
      }
    ],
    "usageNotes": [
      "The MatrixProjectionMethod leverages the Eigen library for efficient matrix operations, offering performance benefits over traditional methods.",
      "The 'd_areJacobiansConstant' attribute can be set to true if the mapping jacobians do not change over time, leading to computational savings by computing them only once."
    ],
    "dependencies": [
      "Eigen",
      "Sofa::Component::LinearSystem"
    ]
  },
  "maths": "### Mathematical and Physical Description\n\n#### Overview\nThe `MatrixProjectionMethod` is a component in the SOFA framework that handles matrix projection using the Eigen library. This component is responsible for projecting matrices from local spaces to a global space by computing Jacobian matrices, which are used to map between different mechanical states.\n\n#### Governing Equations and Operators\nThis component primarily deals with constructing and manipulating Jacobian matrices (denoted as $J$) and applying them to project matrices into the global matrix. The key operations include:\n- **Matrix Projection:** Projecting a local matrix $K$ using Jacobians $J_0$ and $J_1$.\n  \n  Given a matrix $K$, which represents some operator (e.g., mass, stiffness) in the local space, it projects this matrix into the global space via:\n  \\[ J^T K J = (J_0)^T K (J_1) \\]\n  where $J_0$ and $J_1$ are the Jacobian matrices corresponding to different mechanical states.\n\n- **Assembly:** The local matrix projection is added to a global matrix, typically representing an aggregated system of equations.\n\n#### Constitutive or Kinematic Laws Involved\nThe component itself does not involve any direct constitutive laws (e.g., stress-strain relationships). Instead, it operates at the level of linear algebra, specifically focusing on:\n- **Jacobian Matrices:** These matrices capture how changes in one mechanical state affect another through mappings. The Jacobian computation is a key step in projecting local matrices to global ones.\n\n#### Role in the Global FEM Pipeline\n1. **Matrix Projection and Assembly:*\n   - This component plays a crucial role during the assembly phase of the Finite Element Method (FEM). It ensures that contributions from different mechanical states (e.g., due to mappings or constraints) are correctly added into the global system matrices.\n2. *Time Integration:* While not directly responsible for time integration, its operations contribute to constructing the matrices used in implicit schemes such as Backward Euler.\n3. **Nonlinear Solve:** The projection of local matrices is necessary for maintaining consistency during nonlinear iterations where Jacobians are recomputed or reused based on their constancy over time.\n\n#### Numerical Methods and Discretization Choices\n- **Eigen Library Usage:** The component leverages the Eigen library for efficient sparse matrix operations. This choice ensures optimal performance in handling large, sparse matrices that arise from FEM discretizations.\n- **Sparse Matrix Operations:** The use of `CompressedRowSparseMatrix` facilitates memory-efficient storage and operations on sparse matrices, which are typical in FEM systems.\n\n#### Variational / Lagrangian Mechanics Framework\nWhile the `MatrixProjectionMethod` does not directly implement variational principles or derive weak forms from Lagrangians, it supports these principles by ensuring that matrix projections (which can represent operators derived from variational formulations) are correctly assembled into the global system. This aligns with the broader framework of maintaining consistency and numerical stability in FEM simulations.\n\n#### Summary\nThe `MatrixProjectionMethod` is a crucial component for projecting local matrices to the global space using Jacobian mappings, ensuring that contributions from different mechanical states are properly aggregated into the overall system matrices. It leverages efficient linear algebra techniques via the Eigen library to handle large-scale sparse matrix operations.",
  "abstract": "The MatrixProjectionMethod projects local matrices into global space using Jacobian mappings, ensuring proper aggregation of contributions from different mechanical states in FEM simulations.",
  "sheet": "\n# MatrixProjectionMethod\n\n## Overview\n\nThe `MatrixProjectionMethod` is a component that handles matrix projection using the Eigen library. It computes and uses Jacobian matrices to project local matrices into global space, which is essential for assembling contributions from various mechanical states in Finite Element Method (FEM) simulations.\n\n## Mathematical Model\n\nThe component projects a local matrix $K$ into the global space via Jacobians $J_0$ and $J_1$. The projection operation is given by:\n\\[ J^T K J = (J_0)^T K (J_1) \\]\nwhere $J_0$ and $J_1$ are the Jacobian matrices corresponding to different mechanical states. This projection ensures that contributions from local spaces are correctly added into the global system matrix.\n\n## Parameters and Data\n\n- **areJacobiansConstant**: `bool` (default: false)\n  - Indicates whether mapping jacobians are considered constant over time. If true, Jacobians are computed only once; otherwise, they are recomputed each time.\n"
}