Methods

{
  "name": "MultiMatrixAccessor",
  "namespace": "sofa::core::behavior",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/behavior/MultiMatrixAccessor.h",
  "doc": "Abstract class allowing to find the part of the mechanical matrix\nassociated with a given MechanicalState or pair of MechanicalState\n(for interaction forces and mappings).",
  "inherits": [],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "addMechanicalState",
      "return_type": "void",
      "params": [
        {
          "name": "mstate",
          "type": "const BaseMechanicalState *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addMechanicalMapping",
      "return_type": "void",
      "params": [
        {
          "name": "mapping",
          "type": "BaseMapping *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addMappedMechanicalState",
      "return_type": "void",
      "params": [
        {
          "name": "mstate",
          "type": "const BaseMechanicalState *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getGlobalDimension",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getGlobalOffset",
      "return_type": "int",
      "params": [
        {
          "name": "mstate",
          "type": "const BaseMechanicalState *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMatrix",
      "return_type": "MatrixRef",
      "params": [
        {
          "name": "mstate",
          "type": "const BaseMechanicalState *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMatrix",
      "return_type": "InteractionMatrixRef",
      "params": [
        {
          "name": "mstate1",
          "type": "const BaseMechanicalState *"
        },
        {
          "name": "mstate2",
          "type": "const BaseMechanicalState *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": true,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `MultiMatrixAccessor` class in the SOFA framework is an abstract class designed to locate parts of the mechanical matrix associated with specific MechanicalStates or pairs of MechanicalStates, such as for interaction forces and mappings. This class plays a key role in managing and accessing submatrices within larger mechanical systems.\n\n**Role & Purpose:**\nThe primary purpose of `MultiMatrixAccessor` is to enable efficient access to different parts of the mechanical matrix that correspond to individual or interacting MechanicalStates. It supports both local state-specific matrices (via `getMatrix`) and interaction matrices between states (`InteractionMatrixRef`). This abstraction facilitates modular and flexible handling of complex mechanical systems.\n\n**Interactions with other Components:**\nThe class interacts primarily with `BaseMechanicalState` and `BaseMapping`. Methods like `addMechanicalState`, `addMappedMechanicalState`, and `addMechanicalMapping` allow for the registration of these components. The pure virtual methods `getGlobalOffset`, `getMatrix`, and `InteractionMatrixRef` ensure that derived classes must provide implementations to retrieve matrix references specific to MechanicalStates.\n\n**Practical Usage Guidance:**\nThe class is intended to be inherited by concrete matrix accessor implementations, which would then define the actual retrieval logic for mechanical matrices. Developers should implement methods like `getGlobalOffset`, `getMatrix`, and `InteractionMatrixRef` in derived classes to provide the necessary functionality for accessing submatrices.",
  "maths": "The `MultiMatrixAccessor` class in the SOFA framework serves as an abstract interface for accessing submatrices within a larger mechanical matrix. It is designed to handle different parts of the mechanical system associated with specific `BaseMechanicalState` instances or pairs thereof, such as interaction forces and mappings. Here is a detailed mathematical and physical description:\n\n### Governing Equations / Operators\n\nThe `MultiMatrixAccessor` does not directly implement governing equations or operators but provides mechanisms to access parts of the mechanical matrix that represent these operations. For example, in the context of FEM simulations:\n- **Mass Matrix** (\\(M\nd{t})): Describes the inertia properties.\n- **Stiffness Matrix** (\\(K\nd{t})): Represents the elastic forces and constraints.\n- **Internal Forces** (\\(f_{int}\nd{t})): Reflects internal stresses due to deformation.\n\n### Constitutive or Kinematic Laws Involved\n\nThe `MultiMatrixAccessor` does not define specific constitutive or kinematic laws. Instead, it facilitates the access to submatrices that may contain such information derived from these laws:\n- **Strain Measures**: The strain tensor \\\\(\\varepsilon\\\nd{t}) can be related to displacements through shape functions.\n- **Stress Tensors**: Stress tensors \\\\(\\sigma\\\nd{t}) are computed using constitutive relations like Hooke's Law or hyperelastic potentials.\n\n### Role in the Global FEM Pipeline\n\nThe `MultiMatrixAccessor` plays a crucial role in managing and accessing submatrices within the global mechanical system:\n- **Assembly Phase**: During assembly, it helps organize contributions from individual elements to form the global matrix.\n- **Time Integration**: It supports implicit time integration schemes by enabling access to specific parts of the mass and stiffness matrices.\n- **Nonlinear Resolution**: It aids in the nonlinear solve process by providing access to submatrices that contribute to the residual and Jacobian computations.\n\n### Numerical Methods or Discretization Choices\n\nThe `MultiMatrixAccessor` does not directly implement numerical methods but supports their application through efficient matrix access:\n- **Finite Element Method (FEM)**: It assists in FEM by organizing contributions from individual elements into a global system of equations.\n- **Implicit Time Integration**: It facilitates implicit time integration schemes like Backward Euler, where the mass and stiffness matrices are crucial for stability and accuracy.\n\n### Variational / Lagrangian Mechanics Framework\n\nThe `MultiMatrixAccessor` supports the broader variational/Lagrangian mechanics framework by enabling efficient access to submatrices that represent mechanical properties and interactions. This abstraction allows for modular handling of complex mechanical systems, ensuring consistency with the underlying physics:\n- **Variational Formulation**: It supports weak formulations where submatrices are assembled from contributions of individual elements.\n- **Constraints and Mappings**: It facilitates constraint handling by enabling access to relevant parts of the global matrix that enforce constraints or mappings between different states.\n\n### Methods Overview\n\nThe class defines several pure virtual methods:\n- `getGlobalDimension()`: Returns the total dimension of the mechanical matrix.\n- `getGlobalOffset(const BaseMechanicalState* mstate)`: Computes the offset in the global matrix corresponding to a specific MechanicalState.\n- `getMatrix(const BaseMechanicalState* mstate)`: Retrieves the submatrix associated with a given MechanicalState.\n- `getMatrix(const BaseMechanicalState* mstate1, const BaseMechanicalState* mstate2)`: Retrieves the interaction submatrix between two MechanicalStates.\n\nThese methods ensure that derived classes implement the necessary functionality to access and manage submatrices effectively.",
  "abstract": "The MultiMatrixAccessor class manages access to submatrices within the mechanical matrix associated with specific MechanicalStates or pairs of MechanicalStates, enabling efficient handling of complex mechanical systems.",
  "sheet": "# MultiMatrixAccessor\n\n**Overview:**\n\nThe `MultiMatrixAccessor` is an abstract class that facilitates the management and access to submatrices within a larger mechanical system. It handles parts of the mechanical matrix associated with specific `BaseMechanicalState` instances or pairs thereof, such as interaction forces and mappings.\n\n**Dependencies and Connections:*\n\nThis component interacts primarily with `BaseMechanicalState` and `BaseMapping`. Methods like `addMechanicalState`, `addMappedMechanicalState`, and `addMechanicalMapping` allow for the registration of these components. The pure virtual methods `getGlobalOffset`, `getMatrix`, and `InteractionMatrixRef` ensure that derived classes must provide implementations to retrieve matrix references specific to MechanicalStates.\n\n**Practical Notes:**\n\nThe class is intended to be inherited by concrete matrix accessor implementations, which would then define the actual retrieval logic for mechanical matrices. Developers should implement methods like `getGlobalOffset`, `getMatrix`, and `InteractionMatrixRef` in derived classes to provide the necessary functionality for accessing submatrices."
}