{
  "name": "BaseMatrixLinearSystem",
  "main": {
    "name": "BaseMatrixLinearSystem",
    "namespace": "sofa::core::behavior",
    "module": "Sofa.framework.Core",
    "include": "sofa/core/behavior/BaseMatrixLinearSystem.h",
    "doc": "Base class for components storing and assembling a linear system represented as a matrix.\nThe matrix data structure is defined in derived classes.",
    "inherits": [
      "BaseObject"
    ],
    "templates": [],
    "data_fields": [
      {
        "name": "d_matrixSize",
        "type": "sofa::type::Vec2u",
        "xmlname": "matrixSize",
        "help": "Size of the global matrix"
      },
      {
        "name": "d_enableAssembly",
        "type": "bool",
        "xmlname": "enableAssembly",
        "help": "Allows to assemble the system matrix"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "getSystemBaseMatrix",
        "return_type": "linearalgebra::BaseMatrix *",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getSystemRHSBaseVector",
        "return_type": "linearalgebra::BaseVector *",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getSystemSolutionBaseVector",
        "return_type": "linearalgebra::BaseVector *",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "buildSystemMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getMatrixSize",
        "return_type": "sofa::type::Vec2u",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "resizeSystem",
        "return_type": "void",
        "params": [
          {
            "name": "n",
            "type": "int"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "clearSystem",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setRHS",
        "return_type": "void",
        "params": [
          {
            "name": "v",
            "type": "core::MultiVecDerivId"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setSystemSolution",
        "return_type": "void",
        "params": [
          {
            "name": "v",
            "type": "core::MultiVecDerivId"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "dispatchSystemSolution",
        "return_type": "void",
        "params": [
          {
            "name": "v",
            "type": "core::MultiVecDerivId"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "dispatchSystemRHS",
        "return_type": "void",
        "params": [
          {
            "name": "v",
            "type": "core::MultiVecDerivId"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": true,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "preAssembleSystem",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "const core::MechanicalParams *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "assembleSystem",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "const core::MechanicalParams *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "postAssembleSystem",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "const core::MechanicalParams *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "description": "The `BaseMatrixLinearSystem` is an abstract base class in the SOFA framework, specifically within the `sofa::core::behavior` namespace. It serves as a foundation for components that store and assemble linear systems represented by matrices. This class provides methods to manage matrix sizes, enable assembly operations, and handle system solutions and right-hand side vectors (RHS). \n\nIn the SOFA ecosystem, `BaseMatrixLinearSystem` interacts with other components through its API, particularly by returning pointers to `linearalgebra::BaseMatrix` and `linearalgebra::BaseVector`. It also defines virtual methods for building and resizing the system matrix. The data fields include `matrixSize`, which specifies the dimensions of the global matrix, and `enableAssembly`, a boolean that controls whether the system matrix is assembled.\n\nPractical usage involves deriving concrete classes from `BaseMatrixLinearSystem` to implement specific linear solvers or systems. These derived classes must provide implementations for pure virtual methods such as `resizeSystem`, `clearSystem`, `setRHS`, and `dispatchSystemSolution`. The user can configure the matrix size via the `matrixSize` field, though this is typically set at initialization time and marked as read-only."
  },
  "maths": {
    "maths": "<p>The `BaseMatrixLinearSystem` is an abstract base class in the SOFA framework designed to manage linear systems represented as matrices. This class serves as a foundational interface for components that store and assemble these linear systems.</p>\n\n<h3>Mathematical Representation</h3>\n\n<p>In the context of numerical simulations, particularly finite element analysis (FEA) or other physical system modeling, linear systems are often expressed in matrix form:</p>\n\n\\[\n    \\mathbf{Ax} = \\mathbf{b}\n\\]\n\n<p>where:</p>\n\n<ul>\n<li><span class=\"math inline\">\\(\\mathbf{A}\\)</span>: The coefficient matrix, typically a square matrix of size <span class=\"math inline\">\\(n \\times n\\)</span>.</li>\n<li><span class=\"math inline\">\\(\\mathbf{x}\\)</span>: The solution vector of length <span class=\"math inline\">\\(n\\)</span>.</li>\n<li><span class=\"math inline\">\\(\\mathbf{b}\\)</span>: The right-hand side (RHS) vector of length <span class=\"math inline\">\\(n\\)</span>, representing the known values or forcing terms.</li>\n</ul>\n\n<h3>Component Interface and Operations</h3>\n\n<p>The `BaseMatrixLinearSystem` provides several methods to interact with the linear system:</p>\n\n<ul>\n<li><code>getSystemBaseMatrix()</code>: Returns a pointer to the coefficient matrix <span class=\"math inline\">\\(\\mathbf{A}\\)</span>.</li>\n<li><code>getSystemRHSBaseVector()</code>: Returns a pointer to the RHS vector <span class=\"math inline\">\\(\\mathbf{b}\\)</span>.</li>\n<li><code>getSystemSolutionBaseVector()</code>: Returns a pointer to the solution vector <span class=\"math inline\">\\(\\mathbf{x}\\)</span>.</li>\n</ul>\n\n<p>The `buildSystemMatrix()` method is responsible for constructing and assembling the linear system matrix. This process typically involves:</p>\n\n<ul>\n<li><code>preAssembleSystem()</code>: Prepares any necessary setup or initialization steps.</li>\n<li><code>assembleSystem()</code>: Assembles the individual contributions from various components into the global system matrix <span class=\"math inline\">\\(\\mathbf{A}\\)</span>.</li>\n<li><code>postAssembleSystem()</code>: Completes any post-processing or finalization steps.</li>\n</ul>\n\n<h3>Data Fields and Configuration</h3>\n\n<ul>\n<li><strong><code>d_matrixSize</code></strong>: Specifies the size of the global matrix <span class=\"math inline\">\\(\\mathbf{A}\\)</span> as a vector <span class=\"math inline\">\\((n, n)\\)</span>. This field is read-only and typically set during initialization.</li>\n<li><strong><code>d_enableAssembly</code></strong>: A boolean flag that controls whether the system matrix assembly process should be enabled. If disabled (<code>false</code>), the linear system is not assembled, effectively bypassing the <code>preAssembleSystem()</code>, <code>assembleSystem()</code>, and <code>postAssembleSystem()</code> methods.</li>\n</ul>\n\n<h3>User Interaction and Derived Classes</h3>\n\n<p>To utilize `BaseMatrixLinearSystem`, users must derive concrete classes that provide specific implementations for the pure virtual methods:</p>\n\n<ul>\n<li><strong><code>resizeSystem(n)</code></strong>: Resizes both the coefficient matrix <span class=\"math inline\">\\(\\mathbf{A}\\)</span> and the solution vector <span class=\"math inline\">\\(\\mathbf{x}\\)</span>, as well as the RHS vector <span class=\"math inline\">\\(\\mathbf{b}\\)</span>, to size <span class=\"math inline\">\\(n \\times n\\)</span>.</li>\n<li><strong><code>clearSystem()</code></strong>: Clears or resets the linear system matrix and vectors.</li>\n<li><strong><code>setRHS(v)</code></strong>: Sets the values of the RHS vector <span class=\"math inline\">\\(\\mathbf{b}\\)</span> from the provided (Mechanical/Physical) state objects.</li>\n<li><strong><code>setSystemSolution(v)</code></strong>: Initializes the solution vector <span class=\"math inline\">\\(\\mathbf{x}\\)</span> using values from the (Mechanical/Physical) state objects. This initial estimate is replaced by the actual system solution after solving.</li>\n<li><strong><code>dispatchSystemSolution(v)</code></strong>: Dispatches or distributes the computed solution vector <span class=\"math inline\">\\(\\mathbf{x}\\)</span> back to the (Mechanical/Physical) state objects for further use in simulation steps.</li>\n</ul>"
  },
  "summary": {
    "abstract": "The `BaseMatrixLinearSystem` manages linear systems represented as matrices in SOFA simulations, providing methods for building, assembling, and managing these matrices.",
    "sheet": "# BaseMatrixLinearSystem\n\n## Overview\n\nThe `BaseMatrixLinearSystem` is an abstract base class that serves as a foundation for components managing linear systems represented by matrices. It provides methods to build, assemble, and manage the system matrix, right-hand side (RHS) vector, and solution vector.\n\n## Mathematical Model\n\nIn numerical simulations, particularly finite element analysis (FEA), linear systems are often expressed in matrix form:\n\n\\[\n    \\mathbf{Ax} = \\mathbf{b}\n\\]\n\nwhere:\n- \\(\\mathbf{A}\\): The coefficient matrix, typically a square matrix of size \\(n \\times n\\).\n- \\(\\mathbf{x}\\): The solution vector of length \\(n\\).\n- \\(\\mathbf{b}\\): The right-hand side (RHS) vector of length \\(n\\), representing the known values or forcing terms.\n\nThe `BaseMatrixLinearSystem` provides methods to interact with this linear system, including:\n- `getSystemBaseMatrix()`: Returns a pointer to the coefficient matrix \\(\\mathbf{A}\\).\n- `getSystemRHSBaseVector()`: Returns a pointer to the RHS vector \\(\\mathbf{b}\\).\n- `getSystemSolutionBaseVector()`: Returns a pointer to the solution vector \\(\\mathbf{x}\\).\n\nThe `buildSystemMatrix()` method constructs and assembles the linear system matrix through:\n- `preAssembleSystem()`: Prepares any necessary setup or initialization steps.\n- `assembleSystem()`: Assembles individual contributions from various components into the global system matrix \\(\\mathbf{A}\\).\n- `postAssembleSystem()`: Completes any post-processing or finalization steps.\n\n## Parameters and Data\n\nThe significant data fields exposed by this component are:\n- **`matrixSize`**: Specifies the size of the global matrix \\(\\mathbf{A}\\) as a vector \\((n, n)\\). This field is read-only and typically set during initialization.\n- **`enableAssembly`**: A boolean flag that controls whether the system matrix assembly process should be enabled. If disabled (`false`), the linear system is not assembled."
  }
}