Methods

{
  "name": "BaseMatrixProjectionMethod",
  "namespace": "sofa::component::linearsystem",
  "module": "Sofa.Component.LinearSystem",
  "include": "sofa/component/linearsystem/BaseMatrixProjectionMethod.h",
  "doc": "A component associated to a pair of @BaseMechanicalState able to perform\nthe projection of a matrix from the space of the @BaseMechanicalState's\nto the main space using the mapping graph.\nBasically, if K is the matrix to be projected, it computes J, and then the\nproduct J^T * K * J. The J matrix comes from the chain of mappings from\nthe @BaseMechanicalState to its top most parents.",
  "inherits": [],
  "templates": [
    "linearalgebra::CompressedRowSparseMatrix<SReal>"
  ],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "hasPairStates",
      "return_type": "bool",
      "params": [
        {
          "name": "pairStates",
          "type": "const int &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setPairStates",
      "return_type": "void",
      "params": [
        {
          "name": "pairStates",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "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": true,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `BaseMatrixProjectionMethod` is a template class in the SOFA framework, part of the `Sofa.Component.LinearSystem` module and defined within the `sofa::component::linearsystem` namespace. It serves as an abstract base class that performs the projection of matrices from the space of mechanical states to the main global space using a mapping graph. This component is associated with pairs of `BaseMechanicalState`, allowing it to compute the Jacobian matrix J and then perform the product J^T * K * J, where K is the matrix to be projected.\n\nThe key interactions in this component are:\n- It inherits from `core::behavior::StateAccessor` for mechanical state access.\n- The method `projectMatrixToGlobalMatrix()` computes the projection by taking as input a mapping graph, a matrix to project, and a global matrix where the result is stored. This method is pure virtual, meaning it must be implemented by derived classes.\n\nFor practical usage:\n- Ensure that pairs of mechanical states are set using `setPairStates()`, which sets up the internal state for the projection process.\n- Use `hasPairStates()` to check if a particular pair of mechanical states has been configured.\n- Implementations of this class will need to provide the concrete logic for projecting matrices via `projectMatrixToGlobalMatrix().`",
  "maths": "<p>The <code>BaseMatrixProjectionMethod</code> is an abstract class in the SOFA framework that performs the projection of matrices from a local space (defined by mechanical states) to a global space using mappings. This is particularly useful for handling transformations and projections between different mechanical state spaces, which might arise when dealing with complex multi-body systems or hierarchical decompositions.</p>\n\n<p>The core functionality of this class lies in the method <code>projectMatrixToGlobalMatrix</code>, which computes the projection of a given matrix. Given:</p>\n<ul>\n\t<li><span style=\"background-color: rgba(249, 249, 251, 0.88);\"><em>K</em></span>: The local matrix to be projected.</li>\n\t<li><span style=\"background-color: rgba(249, 249, 251, 0.88);\">J</span>: The Jacobian matrix derived from a chain of mappings.</li>\n\t<li><span style=\"background-color: rgba(249, 249, 251, 0.88);\">globalMatrix</span>: The resulting global matrix after projection.</li>\n</ul>\n\n<p>The projection is computed as follows:</p>\n\n<p>\\[\nJ^T \\cdot K \\cdot J = \\text{globalMatrix}\n\\]</p>\n\n<ul>\n\t<li><em>J</em>: This Jacobian matrix <span style=\"background-color: rgba(249, 249, 251, 0.88);\">J</span> is derived from a chain of mappings that link the local mechanical state to its global counterpart.</li>\n\t<li><em>K</em>: The matrix <span style=\"background-color: rgba(249, 249, 251, 0.88);\">K</span> can represent any relevant matrix in the context of the simulation (e.g., stiffness matrices, mass matrices).</li>\n\t<li><em>J^T</em>: The transpose of the Jacobian.</li>\n</ul>\n\n<p>The following steps summarize its functionality:</p>\n\n<ol>\n\t<li>Set pairs of mechanical states using <code>setPairStates()</code>.</li>\n\t<li>Verify if a specific pair of mechanical states has been configured via <code>hasPairStates()</code>.</li>\n\t<li><em>Implementations</em>: Derived classes must provide the logic for computing the mappings and projecting matrices.</li>\n</ol>",
  "abstract": "The `BaseMatrixProjectionMethod` performs the projection of matrices from local mechanical state spaces to global space using mappings, computing the product J^T * K * J where K is the matrix to be projected and J is derived from a chain of mappings.",
  "sheet": "# BaseMatrixProjectionMethod\n\n**Overview:**\nThis abstract class in the SOFA framework handles the projection of matrices from local mechanical state spaces to global space using mappings. It computes the product \\(J^T \\cdot K \\cdot J\\), where \\(K\\) is the matrix to be projected and \\(J\\) is derived from a chain of mappings.\n\n**Mathematical Model:**\nThe core functionality involves projecting a local matrix \\(K\\) into global space using the Jacobian matrix \\(J\\). The projection is computed as:\n\\[\nJ^T \\cdot K \\cdot J = \\text{globalMatrix}\n\\]\nwhere \\(J\\) represents the chain of mappings linking the local mechanical state to its global counterpart.\n\n**Parameters and Data:**\nThe component does not expose any significant data fields or parameters.\n\n**Dependencies and Connections:**\nThis component is typically used in conjunction with pairs of `BaseMechanicalState` components. It requires a mapping graph to derive the Jacobian matrix \\(J\\).\n\n**Practical Notes:**\nDerived classes must implement the logic for computing mappings and projecting matrices via the `projectMatrixToGlobalMatrix()` method."
}