{
  "name": "BuiltConstraintSolver",
  "main": {
    "name": "BuiltConstraintSolver",
    "namespace": "sofa::component::constraint::lagrangian::solver",
    "module": "Sofa.Component.Constraint.Lagrangian.Solver",
    "include": "sofa/component/constraint/lagrangian/solver/BuiltConstraintSolver.h",
    "doc": "This component implements a generic way of building system for solvers that use a built\n version of the constraint matrix. Any solver that uses a build matrix should inherit from this.\n This component is purely virtual because doSolve is not defined and needs to be defined in the\n inherited class",
    "inherits": [
      "GenericConstraintSolver"
    ],
    "templates": [],
    "data_fields": [
      {
        "name": "d_multithreading",
        "type": "bool",
        "xmlname": "multithreading",
        "help": "Build compliances concurrently"
      },
      {
        "name": "d_useSVDForRegularization",
        "type": "bool",
        "xmlname": "useSVDForRegularization",
        "help": "Use SVD decomposiiton of the compliance matrix to project singular values smaller than regularization to the regularization term. Only works with built"
      },
      {
        "name": "d_svdSingularValueNullSpaceCriteriaFactor",
        "type": "SReal",
        "xmlname": "svdSingularValueNullSpaceCriteriaFactor",
        "help": "Fraction of the highest singular value bellow which a singular value will be supposed to belong to the nullspace"
      },
      {
        "name": "d_svdSingularVectorNullSpaceCriteriaFactor",
        "type": "SReal",
        "xmlname": "svdSingularVectorNullSpaceCriteriaFactor",
        "help": "Absolute value bellow which a component of a normalized base vector will be considered null"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "doBuildSystem",
        "return_type": "void",
        "params": [
          {
            "name": "cParams",
            "type": "const core::ConstraintParams *"
          },
          {
            "name": "problem",
            "type": "GenericConstraintProblem *"
          },
          {
            "name": "numConstraints",
            "type": "unsigned int"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "addRegularization",
        "return_type": "void",
        "params": [
          {
            "name": "W",
            "type": "linearalgebra::BaseMatrix &"
          },
          {
            "name": "regularization",
            "type": "const SReal"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "description": "The `BuiltConstraintSolver` is a virtual base class in the SOFA framework designed to build systems for solvers that utilize a built version of the constraint matrix. This component provides infrastructure for handling multithreading and regularization through Singular Value Decomposition (SVD). It inherits from `GenericConstraintSolver`. The primary purpose is to enable derived classes to define their specific solving algorithms while benefiting from standardized system building functionalities.\n\n**Interactions with Other Components:**\n- **Inheritance**: Any solver that uses a built matrix should inherit from `BuiltConstraintSolver` and implement the `doSolve` method.\n- **Data Fields**: \n  - `multithreading`: Enables concurrent computation of compliances for efficiency.\n  - `useSVDForRegularization`: Utilizes SVD to regularize singular values below a certain threshold, enhancing numerical stability.\n  - `svdSingularValueNullSpaceCriteriaFactor`: Sets the fraction criterion for identifying null space singular values using SVD.\n  - `svdSingularVectorNullSpaceCriteriaFactor`: Specifies the absolute value threshold for determining null components in normalized vectors.\n- **Methods**:\n  - `init()`: Initializes settings, including multithreading if enabled.\n  - `doBuildSystem(const core::ConstraintParams *cParams, GenericConstraintProblem *problem, unsigned int numConstraints)`: Constructs the system by computing and assembling compliance matrices from constraint corrections.\n  - `addRegularization(linearalgebra::BaseMatrix &W, const SReal regularization)`: Adds regularization to the matrix based on specified criteria or uses SVD for more precise control over singular values.\n\n**Usage Guidance:**\n- Ensure proper inheritance when defining new solvers that require a built constraint matrix.\n- Configure data fields as needed to balance between multithreading performance and numerical accuracy via SVD-based regularization."
  },
  "maths": {
    "maths": "The `BuiltConstraintSolver` in the SOFA framework is designed to manage the construction and regularization of constraint matrices used by solvers within the simulation environment. This class serves as a virtual base for solvers that require a 'built' version of the constraint matrix, meaning it precomputes and aggregates all contributions from individual constraints into a composite compliance matrix. The primary functionalities include handling multithreading for parallel computation efficiency and applying regularization techniques to improve numerical stability.\n\n### Mathematical Description:\n\n#### System Construction (`doBuildSystem` Method)\nThe system construction process is carried out via the `doBuildSystem` method, which involves several key steps:\n1. **Compliance Matrix Initialization**: The compliance matrix, denoted as $\\mathbf{W}$, is initialized to store contributions from individual constraints.\n2. **Constraint Contributions Aggregation**:\n   - Each active constraint correction (represented by the class `BaseConstraintCorrection`) contributes a local compliance submatrix. These are projected into the global constraint space and added to the composite matrix $\\mathbf{W}$.\n   - The method employs parallel execution strategies for efficient aggregation when multithreading is enabled, ensuring thread-safe updates to the shared $\\mathbf{W}$.\n\n#### Regularization (`addRegularization` Method)\nThe regularization process aims at improving the numerical stability of the system by adjusting the diagonal elements of the compliance matrix. This method can operate with or without Singular Value Decomposition (SVD) depending on user configuration:\n1. **With SVD**:\n   - The compliance matrix $\\mathbf{W}$ is decomposed using SVD into $\\mathbf{U}\\Sigma\\mathbf{V}^T$.\n   - A threshold criterion, defined by the parameter `svdSingularValueNullSpaceCriteriaFactor`, identifies singular values that are considered part of the null space. Specifically, if a singular value $s_i < s_0 \\cdot d_{\\text{singular}}$, where $s_0$ is the largest singular value and $d_{\\text{singular}}$ is `svdSingularValueNullSpaceCriteriaFactor`, it is deemed as part of the null space.\n   - Singular vectors corresponding to these identified values are used to determine constraints that lie in the null space. The threshold for vector components, set by `svdSingularVectorNullSpaceCriteriaFactor`, ensures only significant contributions from these singular vectors are considered.\n2. **Without SVD**:\n   - A simpler approach adds a constant regularization term uniformly across all diagonal elements of $\\mathbf{W}$, improving numerical conditioning without the computational overhead of SVD.\n\n### Physical Description:\n\nIn physical terms, the compliance matrix $\\mathbf{W}$ represents how individual constraints influence each other within the system. Each constraint correction contributes to this matrix, reflecting their interdependencies and interactions in the simulation environment. The regularization process ensures that the resulting matrix remains well-conditioned, thus facilitating stable and accurate solutions during numerical integration of the physical model.\n\nMultithreading provides an additional layer of performance optimization by enabling parallel computation of these contributions, significantly reducing the time required for system construction especially in large-scale simulations.\n\nOverall, `BuiltConstraintSolver` serves as a robust framework for managing complex constraint interactions within SOFA's simulation environment, ensuring both efficiency and numerical stability."
  },
  "summary": {
    "abstract": "The `BuiltConstraintSolver` is a virtual base class for solvers that use built constraint matrices, providing functionalities for multithreading and regularization through Singular Value Decomposition (SVD).",
    "sheet": "# BuiltConstraintSolver\n\n## Overview\nThe `BuiltConstraintSolver` serves as a virtual base class for solvers in the SOFA framework that require precomputed ('built') versions of constraint matrices. It supports multithreaded computation for efficiency and provides regularization techniques to enhance numerical stability.\n\n## Mathematical Model\n### System Construction (`doBuildSystem` Method)\nThe system construction process involves initializing and aggregating contributions from individual constraints into a composite compliance matrix \\(\\mathbf{W}\\).\n1. **Compliance Matrix Initialization**: The compliance matrix \\(\\mathbf{W}\\) is initialized.\n2. **Constraint Contributions Aggregation**:\n   - Each active constraint correction contributes a local compliance submatrix, which is projected into the global constraint space and added to \\(\\mathbf{W}\\).\n   - Multithreading can be enabled for efficient parallel aggregation of contributions.\n\n### Regularization (`addRegularization` Method)\nThe regularization process aims at improving numerical stability by adjusting the diagonal elements of the compliance matrix \\(\\mathbf{W}\\):\n1. **With SVD**:\n   - The compliance matrix \\(\\mathbf{W}\\) is decomposed using SVD into \\(\\mathbf{U}\\Sigma\\mathbf{V}^T\\).\n   - Singular values below a threshold defined by `svdSingularValueNullSpaceCriteriaFactor` are considered part of the null space.\n   - Singular vectors corresponding to these singular values determine constraints in the null space, with components below `svdSingularVectorNullSpaceCriteriaFactor` being considered negligible.\n2. **Without SVD**:\n   - A constant regularization term is added uniformly across all diagonal elements of \\(\\mathbf{W}\\).\n\n## Parameters and Data\n- **multithreading (`bool`)**: Enables concurrent computation of compliances for efficiency (default: `false`).\n- **useSVDForRegularization (`bool`)**: Utilizes SVD to regularize singular values below a certain threshold, enhancing numerical stability (default: `false`).\n- **svdSingularValueNullSpaceCriteriaFactor (`SReal`)**: Fraction of the highest singular value below which a singular value is considered part of the null space.\n- **svdSingularVectorNullSpaceCriteriaFactor (`SReal`)**: Absolute value below which a component of a normalized base vector is considered negligible.\n\n## Dependencies and Connections\nThe `BuiltConstraintSolver` inherits from `GenericConstraintSolver`. It requires derived classes to implement specific solving algorithms while benefiting from standardized system building functionalities. This class typically interacts with constraint corrections and other components that contribute to the construction of the compliance matrix."
  }
}