{
  "name": "AsyncSparseLDLSolver",
  "main": {
    "name": "AsyncSparseLDLSolver",
    "namespace": "sofa::component::linearsolver::direct",
    "module": "Sofa.Component.LinearSolver.Direct",
    "include": "sofa/component/linearsolver/direct/AsyncSparseLDLSolver.h",
    "doc": "Asynchronous direct Linear Solver using a Sparse LDL^T factorization.\n\nThis linear solver is based on SparseLDLSolver, a direct linear solver which factorizes the\nlinear system matrix. Its particularity is its asynchronous factorization.\nThe synchronous version performs the following operations (synchronously):\n1) Build the matrix\n2) Factorize the matrix\n3) Solve the system based on the factorization\nIn the asynchronous version, the factorization is performed asynchronously. A consequence is\nthat the solving process uses a factorization which may not be up to date. In practice,\nthe factorization is at least one time step old.\nBecause of this, the solver computes an approximation of the solution, based on an old\nfactorization. It changes the behavior compared to a synchronous version, but it also\nchanges the behavior depending on the duration of the factorization step. It may introduce\ninstabilities.",
    "inherits": [
      "SparseLDLSolver"
    ],
    "templates": [
      "CompressedRowSparseMatrix< type::Mat<3,3,SReal> >, FullVector<SReal>",
      "CompressedRowSparseMatrix<SReal>, FullVector<SReal>"
    ],
    "data_fields": [
      {
        "name": "d_enableAssembly",
        "type": "bool",
        "xmlname": "enableAssembly",
        "help": "Allow assembly of the linear system"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "isAsyncSolver",
        "return_type": "bool",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "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": "solveSystem",
        "return_type": "void",
        "params": [],
        "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": "TMatrix &"
          }
        ],
        "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": "isAsyncFactorizationFinished",
        "return_type": "bool",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "launchAsyncFactorization",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "asyncFactorization",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "swapInvertData",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "name": "AsyncSparseLDLSolver",
    "description": "This linear solver is based on SparseLDLSolver and performs factorization asynchronously.",
    "parameters": [
      {
        "name": "d_enableAssembly",
        "type": "bool",
        "description": "Enables or disables the matrix assembly."
      }
    ],
    "input": [
      {
        "name": "Matrix",
        "type": "CompressedRowSparseMatrix<SReal> / CompressedRowSparseMatrix<Mat<3, 3, SReal>>",
        "description": "Input linear system matrix to be solved"
      },
      {
        "name": "Vector",
        "type": "FullVector<SReal>",
        "description": "Right-hand side vector of the linear system equation Ax=b."
      }
    ],
    "output": [
      {
        "name": "Solution Vector",
        "type": "FullVector<SReal>",
        "description": "The solution vector x that satisfies the linear system equation Ax=b after factorization and solving process"
      }
    ],
    "details": "AsyncSparseLDLSolver is a specialized version of SparseLDLSolver designed for asynchronous operation, which enhances performance by parallelizing the matrix factorization step.\n\n**Operation Principle:**\n- **Asynchronous Factorization**: The solver starts by building the matrix, then it initiates an asynchronous task to perform the factorization. This allows the main thread to continue other operations while waiting for the factorization result.\n- **Outdated Factorization Usage**: Due to the nature of asynchronous execution, there can be a delay between when the matrix is built and when its factorization is completed. As a consequence, the solver might use an outdated factorization to solve the system, which could introduce some approximation or instability in the solution process.\n\n**Initialization & Reset**:\nThe `init()` method prepares the component for operation by allocating necessary data structures and setting up internal states. The `reset()` method clears these states when needed (e.g., at the beginning of a new simulation).\n\n**Solve System Process**: \nThe `solveSystem()` method orchestrates the overall solving process, including checking if an asynchronous factorization has been completed and swapping invert data between threads.\n- **`isAsyncFactorizationFinished()` checks whether the asynchronous factorization is complete. If so, it swaps the invert data to prepare for the next solve step using the most recent factorization results.\n- **`launchAsyncFactorization()`** triggers a new asynchronous task to perform matrix factorization in parallel.\n\n**Solve Method**: \nThe `solve(Matrix &M, Vector& x, Vector& b)` method solves the linear system equation Ax=b where M is A and x is the solution vector. The right-hand side vector b represents the input data for this solve operation.\n- **Inversion of Matrix**: The solver calls the `invert(TMatrix&M)` method to compute the factorization of matrix M in an asynchronous manner, which helps keep the main thread free from blocking operations while waiting for the computation results.\n\n**Thread Management**: \nThe class supports a default thread manager (`NoThreadManager`) but allows customization through template parameters. This means you can tailor how threads are managed according to your specific use case or hardware configuration.",
    "example": "To instantiate and use this solver, you would typically include it in the component list for a Sofa simulation node, specifying its matrix and vector types as needed.\n\nExample instantiation:\n```cpp\n// Include necessary headers\n#include <sofa/component/linearsolver/direct/AsyncSparseLDLSolver.h>\n...\n// Instantiate the solver with specific matrix and vector types\ntypedef sofa::linearalgebra::CompressedRowSparseMatrix<SReal> MatrixType;\ntypedef sofa::linearalgebra::FullVector<SReal> VectorType;\nauto asyncSolver = new AsyncSparseLDLSolver<MatrixType, VectorType>();\n```",
    "references": [
      {
        "text": "SparseLDLSolver Documentation",
        "url": ""
      },
      {
        "text": "Sofa Framework Documentation",
        "url": "https://www.sofa-framework.org/doc/user/html/index.html"
      }
    ]
  },
  "maths": {
    "maths": "The **AsyncSparseLDLSolver** in the SOFA framework is an asynchronous direct linear solver that performs factorization using a Sparse LDL^T decomposition. This solver extends the functionality provided by the base class `SparseLDLSolver` and introduces asynchrony to enhance performance for real-time simulations.\n\n### Governing Equations and Operators\n- **Mass Matrix (M)**: The mass matrix, which is typically assembled from material properties and element contributions, is part of the linear system that needs solving. In the context of FEM, this matrix represents inertia effects in the discretized equations.\n- **Stiffness Matrix (K)**: Similarly, the stiffness matrix arises from the variational formulation of the weak form. It captures the elastic or hyperelastic response of materials to deformation.\n- **Internal Force (\textbf{f}_{int})**: Represents the internal forces derived from the constitutive laws and discretization schemes, which are part of the right-hand side of the linear system.\n- **Residual (R)**: In the context of nonlinear systems, the residual is the difference between the applied external force and the internal force. For a direct solver like AsyncSparseLDLSolver, this is typically computed in the form of solving \\(Ax = b\\), where \\(A\\) can be a combination of mass, stiffness, and constraint matrices.\n\n### Constitutive or Kinematic Laws Involved\nThis component does not directly handle constitutive laws but is used to solve the linear systems derived from the variational formulation. The factorization process (LDL^T decomposition) is independent of specific material models, making it suitable for both linear and nonlinear elastic materials.\n\n### Role in the Global FEM Pipeline\n- **Assembly Phase**: Although the solver itself does not assemble matrices directly, it takes as input the assembled system matrix \\(A\\), right-hand side vector \\(b\\), and solution vector \\(x\\).\n- **Linear Solve**: In the linear solve phase, this solver is responsible for solving the linear system \\(Ax = b\\) using an asynchronous factorization.\n\n### Numerical Methods or Discretization Choices\nThe AsyncSparseLDLSolver uses a Sparse LDL^T factorization method to decompose the system matrix. The key aspect of this implementation is its asynchrony, where the factorization step is performed in a separate thread:\n- **Asynchronous Factorization**: Instead of waiting for the factorization to complete before solving the linear system (as in synchronous methods), the solver uses an older factorization while a new one is computed in parallel.\n\n### Integration into Variational/Lagrangian Mechanics Framework\nThis solver operates at the level of resolving the linearized equations derived from variational principles. The use of Sparse LDL^T factorization provides efficient and stable solutions to symmetric systems, making it suitable for real-time applications where computational efficiency is critical. However, due to its asynchronous nature, there can be a trade-off with accuracy compared to fully synchronous methods."
  },
  "summary": {
    "abstract": "The AsyncSparseLDLSolver performs asynchronous factorization using Sparse LDL^T decomposition for solving linear systems in SOFA simulations, improving real-time performance at the cost of potential instabilities.",
    "sheet": "# AsyncSparseLDLSolver\n\n## Overview\nThe AsyncSparseLDLSolver is an asynchronous direct linear solver that extends the functionality provided by `SparseLDLSolver`. It performs factorization asynchronously to enhance performance for real-time simulations. The solver uses Sparse LDL^T decomposition and can introduce instabilities due to its asynchronous nature.\n\n## Mathematical Model\nIn the context of FEM, the AsyncSparseLDLSolver solves linear systems derived from variational formulations. Given a system matrix \\(A\\), right-hand side vector \\(b\\), and solution vector \\(x\\), it performs factorization using Sparse LDL^T decomposition:\n\\[\nAx = b\n\\]\nThe solver uses an older factorization while a new one is computed in parallel, which can introduce instabilities but improves real-time performance.\n\n## Parameters and Data\n- **d_enableAssembly (bool)**: Controls whether the assembly of the linear system is allowed. Default value is not specified.\n\n## Dependencies and Connections\nThe AsyncSparseLDLSolver typically requires a matrix \\(A\\), right-hand side vector \\(b\\), and solution vector \\(x\\) from other components in the scene graph, such as force fields or constraint solvers.\n\n## Practical Notes\nDue to its asynchronous nature, the solver computes an approximation of the solution based on an old factorization. This can introduce instabilities, particularly if the factorization step duration is significant. Users should be cautious and monitor stability when using this solver in real-time simulations."
  }
}