{
  "name": "CompositeLinearSystem",
  "main": {
    "name": "CompositeLinearSystem",
    "namespace": "sofa::component::linearsystem",
    "module": "Sofa.Component.LinearSystem",
    "include": "sofa/component/linearsystem/CompositeLinearSystem.h",
    "doc": "Component acting like a linear system, but delegates the linear system functionalities to a list of real linear systems.",
    "inherits": [
      "TypedMatrixLinearSystem"
    ],
    "templates": [
      "BlockDiagonalMatrix<3, SReal>, FullVector<SReal>",
      "DiagonalMatrix<SReal>, FullVector<SReal>",
      "FullMatrix<SReal>, FullVector<SReal>",
      "RotationMatrix<SReal>, FullVector<SReal>",
      "SparseMatrix<SReal>, FullVector<SReal>"
    ],
    "data_fields": [],
    "links": [
      {
        "name": "l_linearSystems",
        "target": "BaseMatrixLinearSystem",
        "kind": "multi",
        "xmlname": "linearSystems",
        "help": "List of linear systems to assemble"
      },
      {
        "name": "l_solverLinearSystem",
        "target": "TypedMatrixLinearSystem<TMatrix, TVector>",
        "kind": "single",
        "xmlname": "solverLinearSystem",
        "help": "Among the list of linear systems, which one is to be used by the linear solver"
      }
    ],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getSystemMatrix",
        "return_type": "TMatrix *",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getRHSVector",
        "return_type": "TVector *",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getSolutionVector",
        "return_type": "TVector *",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getSystemBaseMatrix",
        "return_type": "sofa::linearalgebra::BaseMatrix *",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "buildSystemMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const core::MechanicalParams *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "resizeSystem",
        "return_type": "void",
        "params": [
          {
            "name": "n",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "clearSystem",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setRHS",
        "return_type": "void",
        "params": [
          {
            "name": "v",
            "type": "core::MultiVecDerivId"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setSystemSolution",
        "return_type": "void",
        "params": [
          {
            "name": "v",
            "type": "core::MultiVecDerivId"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "dispatchSystemSolution",
        "return_type": "void",
        "params": [
          {
            "name": "v",
            "type": "core::MultiVecDerivId"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "dispatchSystemRHS",
        "return_type": "void",
        "params": [
          {
            "name": "v",
            "type": "core::MultiVecDerivId"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "name": "CompositeLinearSystem",
    "description": "The CompositeLinearSystem is a component in the SOFA (Simulation Open-Framework Architecture) that acts as a linear system but delegates its functionalities to multiple underlying linear systems, allowing for complex and flexible matrix assembly scenarios.",
    "parameters": [
      {
        "name": "l_linearSystems",
        "description": "A list of real linear systems whose functionalities are combined by the CompositeLinearSystem. These underlying linear systems can each represent different aspects or parts of the overall global matrix.",
        "type": "MultiLink"
      },
      {
        "name": "l_solverLinearSystem",
        "description": "Identifies which specific system from l_linearSystems should be used for solving linear equations, typically representing the global assembled matrix in a simulation context.",
        "type": "SingleLink"
      }
    ],
    "methods": [
      {
        "name": "getSystemMatrix()",
        "return": "TMatrix*",
        "description": "Returns the global system matrix managed by one of the underlying systems (usually identified through l_solverLinearSystem)."
      },
      {
        "name": "getRHSVector()",
        "return": "TVector*",
        "description": "Provides access to the right-hand side vector used in solving linear equations, typically associated with forces or external inputs."
      },
      {
        "name": "getSolutionVector()",
        "return": "TVector*",
        "description": "Returns a reference to the solution vector where results of matrix-vector operations are stored."
      },
      {
        "name": "buildSystemMatrix(mechanicalParams)",
        "parameters": [
          {
            "name": "mechanicalParams",
            "type": "core::MechanicalParams*"
          }
        ],
        "return": "void",
        "description": "Constructs or updates the global system matrix based on mechanical parameters and contributions from individual systems."
      },
      {
        "name": "resizeSystem(n)",
        "parameters": [
          {
            "name": "n",
            "type": "sofa::Size"
          }
        ],
        "return": "void",
        "description": "Resizes all underlying linear systems to accommodate a new size 'n' for the global matrix, typically used during initialization or when system dimensions change."
      },
      {
        "name": "clearSystem()",
        "return": "void",
        "description": "Clears the contents of the global system matrix and associated vectors, resetting them to initial states (useful before rebuilding the system)."
      },
      {
        "name": "setRHS(rhs)",
        "parameters": [
          {
            "name": "rhs",
            "type": "core::MultiVecDerivId"
          }
        ],
        "return": "void",
        "description": "Sets the right-hand side vector for all underlying linear systems, essential for solving equations of motion or other physical models."
      },
      {
        "name": "setSystemSolution(solution)",
        "parameters": [
          {
            "name": "solution",
            "type": "core::MultiVecDerivId"
          }
        ],
        "return": "void",
        "description": "Assigns a solution vector to the system, often used after solving linear systems where results need to be distributed across different parts of the simulation."
      },
      {
        "name": "dispatchSystemSolution(solution)",
        "parameters": [
          {
            "name": "solution",
            "type": "core::MultiVecDerivId"
          }
        ],
        "return": "void",
        "description": "Distributes or dispatches the solution vector from the identified solver system (l_solverLinearSystem) to other systems or components in the simulation."
      },
      {
        "name": "dispatchSystemRHS(rhs)",
        "parameters": [
          {
            "name": "rhs",
            "type": "core::MultiVecDerivId"
          }
        ],
        "return": "void",
        "description": "Dispatches the right-hand side vector to different underlying linear systems, enabling localized processing or application of forces/effects within the simulation framework."
      }
    ]
  },
  "maths": {
    "maths": "The **CompositeLinearSystem** is designed to handle complex linear system operations within the context of numerical simulations, particularly in scenarios where multiple matrices are required for a partial assembly. This approach allows flexibility and modularity in constructing global system matrices by combining various linear systems, such as full matrices, sparse matrices, or diagonal matrices. The functionality of this component involves delegating its operations to these underlying systems while maintaining consistency and integrity in the simulation framework.\n\n### Mathematical Description:\n\n#### Linear Systems Representation:\n- **Full Matrix:** A dense matrix where each element is explicitly stored and can represent complex interactions with full generality.\n  - Example: \\(A = [a_{ij}]\\) for a square matrix of size \\(N \\times N\\).\n- **Sparse Matrix:** Represents matrices with many zero entries, efficiently storing only non-zero elements. Common formats include the Compressed Row Storage (CRS) format.\n  - Example: In CRS format, \\(A = [row_ptr, col_ind, val]\\), where `row_ptr` points to the start of each row's data in `col_ind` and `val`, which store column indices and values respectively.\n- **Diagonal Matrix:** A matrix with non-zero entries only on its diagonal. It is useful for representing scalar interactions or scaling operations.\n  - Example: \\(D = [d_{ii}]\\) where all off-diagonal elements are zero.\n\n#### CompositeLinearSystem:\n- The **CompositeLinearSystem** manages a list of these linear systems, each of which may represent different physical phenomena or mathematical properties (e.g., stiffness matrix, mass matrix).\n  - Example: Suppose \\(A_1\\) is the global stiffness matrix and \\(A_2\\) is only the rotational component. The composite system can manage both simultaneously.\n- Each linear system within the composite may have its own specific representation format (full, sparse, diagonal), allowing for efficient computation tailored to the particular application.\n\n#### Operations:\n- **Get System Matrix:** Returns the matrix representing the current state of one of the underlying systems, typically used for solving linear equations or applying transformations.\n  - Example: \\(A = getSystemMatrix()\\).\n- **Resize System:** Modifies the dimensions of the matrices to accommodate changes in the simulation setup (e.g., adding/removing degrees of freedom).\n  - Example: \\(resize(n)\\), where `n` is the new number of rows/columns.\n- **Clear System:** Resets the linear system by clearing all stored elements, effectively starting with a zero matrix.\n  - Example: \\(clearSystem()\\).\n- **Set Right-Hand Side (RHS):** Assigns values to the right-hand side vector in the equation \\(Ax = b\\), where `b` is the RHS vector and `x` represents unknown variables.\n  - Example: \\(setRHS(b)\\).\n- **Set Solution Vector:** Stores the solution vector after solving a linear system, often representing displacements or forces in simulations.\n  - Example: \\(setSolutionVector(x)\\).\n\n### Physical Description:\nIn physical systems modeled within SOFA, such as mechanical models involving deformable objects and rigid bodies, multiple matrices may be required to represent different aspects of the model accurately. For instance:\n- **Stiffness Matrix:** Encodes how forces are generated in response to displacements.\n- **Mass Matrix:** Captures inertia effects for dynamic simulations.\n\nBy allowing these matrices to be managed together within a single composite system, users can easily construct and manipulate complex linear systems that accurately reflect the physics of the modeled scenario."
  },
  "summary": {
    "abstract": "The CompositeLinearSystem manages a list of underlying linear systems, each with different matrix representations (full, sparse, diagonal), enabling flexible and modular construction of global system matrices in SOFA simulations.",
    "sheet": "# CompositeLinearSystem\n\n## Overview\n\nThe **CompositeLinearSystem** is a component that acts as a linear system but delegates its functionalities to multiple underlying linear systems. It supports various matrix types (full, sparse, diagonal) and provides methods for managing these matrices within the SOFA simulation framework.\n\n## Parameters and Data\n\n- **l_linearSystems**: List of linear systems to assemble (`BaseMatrixLinearSystem`, multi).\n- **l_solverLinearSystem**: Among the list of linear systems, which one is to be used by the linear solver (`TypedMatrixLinearSystem<TMatrix, TVector>`, single).\n\n## Dependencies and Connections\n\nThe **CompositeLinearSystem** typically requires multiple underlying linear system components (e.g., `BaseMatrixLinearSystem`) and exchanges data with them. It fits into the scene graph as a composite component that manages and delegates operations to these underlying systems."
  }
}