Data Fields

Methods

{
  "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"
    }
  ],
  "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": "<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>",
  "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."
}