Methods

{
  "name": "SparseLDLSolver",
  "namespace": "sofa::component::linearsolver::direct",
  "module": "Sofa.Component.LinearSolver.Direct",
  "include": "sofa/component/linearsolver/direct/SparseLDLSolver.h",
  "doc": "Direct linear solver using a Sparse LDL^T factorization.",
  "inherits": [],
  "templates": [
    "CompressedRowSparseMatrix< type::Mat<3,3,SReal> >, FullVector<SReal>",
    "CompressedRowSparseMatrix<SReal>, FullVector<SReal>"
  ],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "parse",
      "return_type": "void",
      "params": [
        {
          "name": "arg",
          "type": "sofa::core::objectmodel::BaseObjectDescription *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "solve",
      "return_type": "void",
      "params": [
        {
          "name": "M",
          "type": "Matrix &"
        },
        {
          "name": "x",
          "type": "Vector &"
        },
        {
          "name": "b",
          "type": "Vector &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "invert",
      "return_type": "void",
      "params": [
        {
          "name": "M",
          "type": "Matrix &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "doAddJMInvJtLocal",
      "return_type": "bool",
      "params": [
        {
          "name": "result",
          "type": "ResMatrixType *"
        },
        {
          "name": "J",
          "type": "const JMatrixType *"
        },
        {
          "name": "fact",
          "type": "SReal"
        },
        {
          "name": "data",
          "type": "int *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addJMInvJtLocal",
      "return_type": "bool",
      "params": [
        {
          "name": "M",
          "type": "TMatrix *"
        },
        {
          "name": "result",
          "type": "ResMatrixType *"
        },
        {
          "name": "J",
          "type": "const JMatrixType *"
        },
        {
          "name": "fact",
          "type": "SReal"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "createInvertData",
      "return_type": "MatrixInvertData *",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "factorize",
      "return_type": "bool",
      "params": [
        {
          "name": "M",
          "type": "Matrix &"
        },
        {
          "name": "invertData",
          "type": "int *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "showInvalidSystemMessage",
      "return_type": "void",
      "params": [
        {
          "name": "reason",
          "type": "const int &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "category": "Linear Solvers",
  "description": "Direct linear solver based on Sparse LDL^T factorization, implemented with the CSPARSE library.",
  "authors": [
    "jeremie.allard@insimo.fr (InSimo)"
  ],
  "contact": "contact@sofa-framework.org",
  "parameters": [
    {
      "name": "template TMatrix",
      "description": "The type of matrix to be solved. Usually a CompressedRowSparseMatrix template with the element type, e.g., SReal or Mat<3,3,SReal>.",
      "type": "class"
    },
    {
      "name": "template TVector",
      "description": "The type of vector used in linear operations. Typically FullVector with the same element type as TMatrix.",
      "type": "class"
    },
    {
      "name": "template TThreadManager (optional)",
      "description": "Class that manages threading for parallel computations. Default is NoThreadManager which implies no parallelism.",
      "type": "class"
    }
  ],
  "detailed_description": "The SparseLDLSolver component in SOFA (Simulation Open-Framework Architecture) is a direct linear solver designed to solve sparse systems of equations using the LDL^T factorization method. This solver leverages the CSPARSE library for its computations.\n\n### Key Features:\n- **Sparse Matrix Support**: It works with sparse matrices, which are common in large-scale simulations where most entries are zero.\n- **Template-based**: The solver is template-based, allowing flexibility in choosing matrix and vector types. Common choices include CompressedRowSparseMatrix for the matrix type and FullVector for the vector type, both parameterized by element type (like SReal or Mat<3,3,SReal>).\n- **Parallel Processing (Optional)**: By default, it does not use parallel processing but supports threading through an optional template argument TThreadManager. This allows customization of how tasks are distributed across threads.\n\n### Usage:\nTo use the SparseLDLSolver in a SOFA simulation, you would typically define it as part of your mechanical system, specifying the appropriate matrix and vector types. The default configuration without parallel processing can be defined as follows:\n```cpp\nSparseLDLSolver<CompressedRowSparseMatrix<SReal>, FullVector<SReal>>\n```\nFor scenarios requiring parallel computation capabilities, you could specify a threading manager like so (assuming TThreadManager is your custom thread management class):\n```cpp\nSparseLDLSolver<CompressedRowSparseMatrix<SReal>, FullVector<SReal>, TThreadManager>\n```\n\n### Methods and Functionality:\nThe component provides methods for initializing the solver, parsing configuration options, solving linear systems, and inverting matrices. It also supports operations that involve multiplying the inverse of the system matrix with the transpose of a given matrix.\n\n- **Initialization**: The `init` method prepares the solver for use, ensuring it is properly configured.\n- **Parsing Configuration**: The `parse` method handles parsing of configuration options passed to the component. This allows customization of behavior based on input parameters.\n- **Solving Systems**: The `solve` method performs the actual solving of a linear system, given a matrix and vectors for the unknowns and constants.\n- **Matrix Inversion**: The `invert` method inverts the provided matrix using the LDL^T factorization.\n\n### Customization:\nThe solver supports customization through template parameters, allowing it to adapt to different scenarios by changing the underlying matrix and vector types. Additionally, the optional threading manager parameter enables support for parallel processing which can be crucial for performance optimization in large-scale simulations.",
  "example": "Below is an example of how you might define a SparseLDLSolver with specific matrix and vector types in a SOFA scene file:\n```xml\n<LinearSolver>\n    <SparseLDLSolver>\n        <!-- Configuration options can be added here -->\n    </SparseLDLSolver>\n</LinearSolver>\n```\nFor scenarios requiring parallel processing, you would specify your custom threading manager as well.",
  "notes": "This component is part of the SOFA (Simulation Open-Framework Architecture) and is designed for efficient solving of linear systems in simulation frameworks. The CSPARSE library it uses provides robust support for sparse matrix operations which are essential for performance in large-scale simulations.",
  "maths": "The **SparseLDLSolver** in the SOFA framework is a direct linear solver that employs a Sparse LDL^T factorization, implemented using the CSPARSE library. It operates on matrices in compressed row sparse format and vectors for solving systems of linear equations arising from the discretized weak form used in finite element simulations.\n\n### Governing Equations and Operators:\nThe primary function of this component is to solve linear systems of the form:\n\\[ Ax = b \\]\nwhere $A$ is a symmetric matrix, typically representing either the mass matrix ($M$) or stiffness matrix ($K$), and $b$ is a vector. In the context of FEM simulations within SOFA, these matrices arise from spatial discretization of partial differential equations in variational form.\n\n### Constitutive Laws:\nThe component itself does not directly implement any constitutive laws related to material behavior; rather, it provides the numerical tools required for solving linear systems that are derived from such laws during assembly or time integration steps.\n\n### Role in FEM Pipeline:\n- **Assembly Phase**: The SparseLDLSolver is involved after the global matrix $A$ (usually representing a combination of mass and stiffness contributions) has been assembled based on weak form discretization.\n- **Linear Resolution**: During the nonlinear solve process, it addresses the linear systems that arise from Newton-Raphson iterations. Specifically, given a residual equation at an iteration:\n\\[ R(x_{k+1}) = M\\frac{x_{k+1}-x_k}{\\Delta t} - \\Delta t f_{int}(x_{k+1}) - \\Delta t f_{ext} = 0 \\]\nit solves for the incremental displacement $\\delta x$ in each iteration step using linear system solutions.\n- **Constraint Handling**: It also plays a role in constraint projection by solving systems associated with Lagrange multipliers and constraint Jacobians, ensuring that constraints are satisfied within the simulation.\n\n### Numerical Methods:\nThe solver uses a direct factorization method where $A$ is decomposed into:\n\\[ A = LDL^T \\]\nwhere $L$ is a lower triangular matrix, $D$ is a diagonal matrix, and $L^T$ is the transpose of $L$. This factorization allows for efficient solution to linear systems by reducing them to simpler forward and backward substitution operations.\n\n### Variational Mechanics Framework:\nThe SparseLDLSolver fits into the broader variational mechanics framework by ensuring that the numerical solution process maintains consistency with the underlying physics-based model. Specifically, it helps in accurately resolving the discretized weak forms that represent physical laws of continuum mechanics.",
  "abstract": "The SparseLDLSolver performs direct linear system solutions using Sparse LDL^T factorization for symmetric matrices in compressed row sparse format within SOFA simulations.",
  "sheet": "# SparseLDLSolver\n\n**Overview:**\nThe SparseLDLSolver is a component of the Sofa.Component.LinearSolver.Direct module, providing a direct linear solver based on Sparse LDL^T factorization. It operates on matrices and vectors in compressed row sparse format to solve systems of linear equations arising from finite element simulations.\n\n**Mathematical Model:**\nThe primary function of this component is to solve linear systems of the form:\n\\[ Ax = b \\]\nwhere $A$ is a symmetric matrix, typically representing either the mass matrix ($M$) or stiffness matrix ($K$), and $b$ is a vector. The solver uses a direct factorization method where $A$ is decomposed into:\n\\[ A = LDL^T \\]\nwhere $L$ is a lower triangular matrix, $D$ is a diagonal matrix, and $L^T$ is the transpose of $L$. This factorization allows for efficient solution to linear systems by reducing them to simpler forward and backward substitution operations.\n\n**Practical Notes:**\nThe SparseLDLSolver ensures numerical stability through direct factorization methods. However, users should be aware that the efficiency and performance can depend on the sparsity pattern of the matrix $A$. Proper preconditioning or reordering techniques may enhance its effectiveness in certain scenarios."
}