Data Fields

Links

Methods

{
  "name": "RotationMatrixSystem",
  "namespace": "sofa::component::linearsolver::preconditioner",
  "module": "Sofa.Component.LinearSolver.Preconditioner",
  "include": "sofa/component/linearsolver/preconditioner/RotationMatrixSystem.h",
  "doc": "Rotation matrix warping the main linear system.",
  "inherits": [
    "TypedMatrixLinearSystem"
  ],
  "templates": [
    "RotationMatrix<SReal>, FullVector<SReal>"
  ],
  "data_fields": [
    {
      "name": "d_assemblingRate",
      "type": "unsigned int",
      "xmlname": "assemblingRate",
      "help": "Rate of update of the preconditioner matrix"
    }
  ],
  "links": [
    {
      "name": "l_mainAssembledSystem",
      "target": "BaseMatrixLinearSystem",
      "kind": "single",
      "xmlname": "mainSystem",
      "help": "Main assembled linear system that will be warped"
    },
    {
      "name": "l_rotationFinder",
      "target": "BaseRotationFinder",
      "kind": "single",
      "xmlname": "rotationFinder",
      "help": "Link toward the rotation finder used to compute the rotation matrix"
    }
  ],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "reset",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "buildSystemMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "reinitAssemblyCounter",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "updateMatrixWithRotations",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `RotationMatrixSystem` is a preconditioner in SOFA that warps the main linear system using rotation matrices. It inherits from `TypedMatrixLinearSystem`, indicating its role in managing matrix and vector operations for linear systems.\n\n**Role and Purpose:**\n- **Warping Linear Systems**: This component modifies the main linear system by applying a rotation, which can be useful for preconditioning techniques to improve numerical stability or performance.\n- **Integration with SOFA Ecosystem**: It interacts closely with other components such as `BaseMatrixLinearSystem` and `BaseRotationFinder`, ensuring that the transformations are applied correctly and efficiently.\n\n**Interactions:**\n- **Link to Main Assembled System (`mainSystem`)**: This link points to the main linear system that will be warped. If not explicitly set, it defaults to the first available non-GraphScattered type system in the context.\n- **Rotation Finder (`rotationFinder`)**: A required dependency for computing rotation matrices used in warping operations. The component logs errors if this dependency is missing or improperly configured.\n\n**Data Fields:**\n- `assemblingRate`: An unsigned integer that controls how often the preconditioner matrix is updated, affecting the frequency of assembly operations.\n\n**Usage Guidance:**\n- Ensure that a valid `rotationFinder` and `mainSystem` are linked to this component for proper operation.\n- Adjust the `assemblingRate` based on the specific requirements of your linear system solution process.",
  "maths": "The `RotationMatrixSystem` is a preconditioner in the SOFA framework that modifies the main linear system by applying rotation matrices. This transformation can enhance numerical stability and improve solution performance for linear systems arising from discretized partial differential equations (PDEs) used in finite element analysis (FEM).\n\n### Governing Equations and Operators\nThe component contributes to modifying the primary linear system matrix, denoted as \\(A\\), using a rotation matrix \\(R\\). The transformation is given by:\n\n\begin{equation}\n    A' = RAR^T,\n\tag{1}\\end{equation}\n\nwhere \\(A\\) is the original linear system matrix, and \\(R\\) is a rotation matrix. This operation modifies the spectrum of \\(A\\), which can aid in preconditioning.\n\n### Constitutive or Kinematic Laws Involved\nThe `RotationMatrixSystem` does not directly involve constitutive laws such as stress-strain relations or hyperelastic potentials. Instead, it focuses on modifying linear system matrices used during iterative solution processes.\n\n### Role in the Global FEM Pipeline\n- **Assembly Phase**: During assembly, \\(A\\) is formed based on the underlying variational formulation and discretization method (e.g., finite elements).\n- **Time Integration and Linear Solve**: In implicit time integration schemes such as Backward Euler, the modified matrix \\(A'\\) can be used to solve for unknowns in the linear system:\n\n\begin{equation}\n    A'x = b.\n\tag{2}\\end{equation}\n\n### Numerical Methods and Discretization Choices\nThe component uses a rotation matrix obtained from the `BaseRotationFinder` linked component. The rate at which the preconditioner matrix is updated is controlled by the data field `d_assemblingRate`. This can be crucial for balancing computational cost and solution accuracy.\n\n### Integration into Variational / Lagrangian Mechanics Framework\nThe `RotationMatrixSystem` fits within a broader variational mechanics framework by improving the conditioning of linear systems derived from the discretization of weak forms. Better-conditioned matrices lead to more efficient and stable iterative solvers, which are crucial for real-time or high-fidelity simulations.",
  "abstract": "The `RotationMatrixSystem` modifies the main linear system by applying rotation matrices to improve numerical stability or performance in preconditioning techniques.",
  "sheet": "# RotationMatrixSystem\n\n## Overview\n\nThe `RotationMatrixSystem` is a preconditioner component that warps the main linear system using rotation matrices. It inherits from `TypedMatrixLinearSystem`, indicating its role in managing matrix and vector operations for linear systems.\n\n## Mathematical Model\n\nThe component modifies the primary linear system matrix, denoted as \\(A\\), by applying a rotation matrix \\(R\\). The transformation is given by:\n\n\\[ A' = RAR^T, \\]\n\nwhere \\(A\\) is the original linear system matrix and \\(R\\) is a rotation matrix. This operation modifies the spectrum of \\(A\\), which can aid in preconditioning.\n\n## Parameters and Data\n\n- **assemblingRate**: An unsigned integer that controls how often the preconditioner matrix is updated, affecting the frequency of assembly operations.\n\n## Dependencies and Connections\n\nThe component requires links to:\n\n- **mainSystem**: The main assembled linear system that will be warped. If not explicitly set, it defaults to the first available non-GraphScattered type system in the context.\n- **rotationFinder**: A required dependency for computing rotation matrices used in warping operations."
}