Methods

{
  "name": "LinearSolver",
  "namespace": "sofa::core::behavior",
  "module": "Sofa.framework.Core",
  "include": "sofa/core/behavior/LinearSolver.h",
  "doc": "Abstract interface for linear system solvers",
  "inherits": [
    "BaseLinearSolver"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "getLinearSystem",
      "description": "Retrieves a pointer to the linear system being solved.",
      "return_type": "sofa::core::behavior::BaseMatrixLinearSystem*"
    },
    {
      "name": "solveSystem",
      "description": "Solves the system as constructed using previously set parameters and values. This method is pure virtual, meaning all derived classes must implement this function.",
      "return_type": "void"
    },
    {
      "name": "invertSystem",
      "description": "Inverts the system matrix, an optional operation called when solveSystem() is invoked for the first time.",
      "return_type": "void"
    },
    {
      "name": "addMInvJt",
      "description": "Multiplies the inverse of the system matrix by the transpose of a given matrix J and adds the result to another matrix. Used in scenarios where constraint forces need to be projected into the state space.",
      "return_type": "bool"
    },
    {
      "name": "buildComplianceMatrix",
      "description": "Builds the Jacobian of constraints, forming the compliance matrix using a visitor pattern.",
      "return_type": "bool"
    },
    {
      "name": "applyConstraintForce",
      "description": "Applies contact forces according to the formula dx = Minv * J^t * f and stores the result in the designated vector.",
      "return_type": "void"
    },
    {
      "name": "computeResidual",
      "description": "Computes the residual due to constraint forces during Newton iteration steps.",
      "return_type": "void"
    }
  ],
  "description": "The LinearSolver class in the SOFA (Simulation Open Framework Architecture) framework is an abstract base class for implementing various types of linear solvers used to solve systems of linear equations arising from finite element analysis, physics simulation, and other computational tasks. This component serves as a fundamental building block for numerical simulations that require solving linear systems.",
  "parameters": {
    "isAsyncSolver": {
      "description": "Indicates if the solver updates the system in parallel.",
      "type": "bool",
      "default_value": "false"
    },
    "supportNonSymmetricSystem": {
      "description": "Returns true if the solver supports non-symmetric systems.",
      "type": "bool",
      "default_value": "false"
    }
  },
  "implementation_notes": "The LinearSolver class provides an abstract interface for various linear solvers and includes several pure virtual methods that must be implemented by derived classes. Methods like setSystemMBKMatrix, hasUpdatedMatrix, updateSystemMatrix, getSystemBaseMatrix, getSystemRHBaseVector, getSystemLHBaseVector, getSystemInverseBaseMatrix have been marked as deprecated due to changes in SOFA's architecture and assembly process.",
  "usage_example": "Derived classes from LinearSolver such as CGLinearSolver or SparseLDLSolver would implement the specific algorithms for solving linear systems. These derived solvers are then used within simulation pipelines to compute displacements, forces, and other physical properties based on the equations of motion and constraints specified in a SOFA scene.",
  "dependencies": [
    "sofa::core",
    "sofa::linearalgebra"
  ],
  "maths": "The **LinearSolver** class in the SOFA framework is an abstract interface designed to provide various linear system solvers for finite element analysis and physics simulation tasks. This class plays a crucial role in solving the linear systems that arise during the assembly phase of FEM simulations, particularly during the solution of nonlinear equations through Newton-Raphson iterations.\n\n### Governing Equations / Operators\n- **Mass Matrix** (\\(M\ngg)): Represents the inertial properties of the system and is assembled from contributions of each finite element. It appears in the dynamic equation: \\\\[ M \\ddot{u} + K u = f_{ext} \\\nwhere \\\\(K\\\\) is the stiffness matrix, \\\\(f_{ext}\\ngg) are external forces, and \\\\(u\\ngg) represents displacements.\n\n- **Stiffness Matrix** (\\(K\\ngg)): Captures the elastic response of the system. It can be derived from constitutive laws such as linear elasticity or hyperelasticity models through the weak form and element-wise assembly.\n\n- **Residual Vector** (\\(R\\ngg)): Represents the nonlinear residual in the Newton-Raphson method: \\\\[ R(u) = M \\frac{u_{n+1} - u_n}{\\Delta t} - K (u_{n+1}) + f_{int}(u_{n+1}) - f_{ext} = 0 \\\nwhere \\\\(f_{int}\\ngg) are internal forces.\n\n### Constitutive / Kinematic Laws Involved\n- **Strain Measures**: Depending on the constitutive law, strain measures such as Green-Lagrange strain or engineering strains can be used to compute stresses from displacements through a hyperelastic potential \\\\(W(\\epsilon)\\\\).\n- **Stress Tensors**: Derived using the second Piola-Kirchhoff stress tensor for large deformation formulations.\n\n### Role in Global FEM Pipeline\n1. **Assembly Phase**: The mass matrix, stiffness matrix, and internal force contributions are assembled element-wise into global matrices \\\\(M\\\\) and \\\\(K\\ngg), and vector \\\\(f_{int}\\ngg).\n2. **Time Integration**: During implicit time integration (e.g., Backward Euler), the linear system \\\\[ M \\ddot{u} + K u = f_{ext} \\\nis solved at each time step.\n3. **Nonlinear Solve**: In Newton-Raphson iterations, the Jacobian matrix is assembled as \\\\(J(u) = \\frac{1}{\\Delta t}M - \\Delta t K(u)\\ngg), and the linear system \\\\[ J(u_k) \\delta u_k = -R(u_k) \\\nis solved to update displacements.\n4. **Linear Solve**: Solves the assembled linear systems using iterative (e.g., Conjugate Gradient, GMRES) or direct methods (e.g., LU factorization).\n\n### Numerical Methods / Discretization Choices\n- **Iterative Solvers**: Krylov subspace methods are commonly used for solving large sparse matrices efficiently.\n- **Direct Solvers**: Sparse matrix factorizations like LU decomposition can be employed, especially for smaller systems or when higher accuracy is required.\n- **Constraint Handling**: Methods such as Lagrange multipliers and Schur complements are supported to handle constraints within the system.\n\n### Fit into Variational / Lagrangian Mechanics Framework\nThe LinearSolver component fits into a broader variational framework where the weak form of PDEs derived from Lagrangian mechanics is discretized using FEM. It ensures that linear systems arising in each iteration of nonlinear solvers are efficiently and accurately solved, preserving physical consistency and numerical stability.\n\nIn summary, **LinearSolver** is an abstract interface for various linear system solvers critical for solving the assembled equations in finite element simulations within SOFA's simulation pipeline.",
  "abstract": "The `LinearSolver` abstract interface in SOFA provides various linear system solvers for finite element analysis and physics simulation tasks, handling the assembly and solution of mass and stiffness matrices.",
  "sheet": "\n# LinearSolver\n\n## Overview\n\nThe `LinearSolver` is an abstract base class that defines the interface for implementing different types of linear solvers in SOFA. It handles the assembly and solution of linear systems arising from finite element analysis, including mass and stiffness matrices.\n\n## Mathematical Model\n\nIn the context of FEM simulations, the `LinearSolver` deals with solving linear systems derived from the discretization of partial differential equations (PDEs). The governing equations include:\n\n- **Mass Matrix** (\\(M\ngg)): Represents inertial properties and appears in dynamic equations: \\[ M \\\ndot{u} + K u = f_{ext} \\\nwhere \\(K\\) is the stiffness matrix, \\(f_{ext}\ngg) are external forces, and \\(u\ngg) represents displacements.\n\n- **Stiffness Matrix** (\\(K\ngg)): Captures elastic response through constitutive laws such as linear elasticity or hyperelasticity models.\n\n- **Residual Vector** (\\(R\ngg)): Represents nonlinear residuals in the Newton-Raphson method: \\[ R(u) = M \\\frac{u_{n+1} - u_n}{\\Delta t} - K (u_{n+1}) + f_{int}(u_{n+1}) - f_{ext} = 0 \\\nwhere \\(f_{int}\ngg) are internal forces.\n\n## Practical Notes\n\n- **Numerical Methods**: Iterative solvers like Conjugate Gradient and GMRES, as well as direct methods such as LU factorization, can be used depending on the problem size and required accuracy.\n- **Constraint Handling**: The component supports constraint handling through Lagrange multipliers and Schur complements to manage constraints within the system."
}