`BlockFullMatrix` is a specialized matrix class used for efficient storage and manipulation of block matrices in SOFA, enabling computational efficiency in large-scale simulations.
sheet
# BlockFullMatrix
## Overview
The `BlockFullMatrix` is a specialized matrix class that inherits from `BaseMatrix`. It provides methods to efficiently store and manipulate block matrices, which are composed of sub-matrices (blocks). This component is particularly useful for computational efficiency in large-scale simulations involving multiple interacting components.
## Mathematical Model
A block matrix is defined as a partitioned matrix where each element is itself a matrix (block). For example, consider a 6x6 block matrix with 2x2 sub-blocks:
egin{equation}
A = egin{bmatrix}
A_{11} & A_{12} & A_{13} \\
A_{21} & A_{22} & A_{23} \\
A_{31} & A_{32} & A_{33}
end{bmatrix},
ext{where each } A_{ij} ext{ is a 2x2 sub-matrix.}
\end{equation}
Operations on block matrices include setting elements, clearing rows and columns, accessing blocks, and resizing. Each block can be manipulated individually or as part of the entire matrix:
egin{equation}
A_{ij} = egin{bmatrix}
a & b \\c & d
\end{bmatrix},
\text{where } a, b, c, \text{ and } d \text{ are scalar values.}
\end{equation}
component
{
"category": "Constraint Solvers",
"dependencies": [
{
"component_name": "BlockFullMatrix6",
"description": "A matrix type that stores elements in a block-wise fashion, with each block being a 6x6 submatrix. This is crucial for representing and operating on matrices with the specific band structure required by BTDLinearSolver."
}
],
"description": "The BTDLinearSolver is a specialized solver designed for efficiently solving systems of linear equations with symmetric matrices that have a specific band structure, often found in certain types of mechanical systems simulations. It employs a Block Tridiagonal Decomposition (BTD) method to factorize and solve the system.",
"example_code": [
{
"description": "This example demonstrates how to create an instance of the BTDLinearSolver and solve a linear system with verbose output.",
"snippet": "BTDLinearSolver solver;\nsolver.setVerbose(true);\nsolver.solve(systemMatrix, externalForces, solution);"
}
],
"input_properties": [
{
"description": "The external forces acting on the system.",
"name": "externalForces",
"type": "VecDeriv"
},
{
"description": "The mass matrix of the system, which is required for solving certain types of dynamic systems.",
"name": "massMatrix",
"type": "SparseMatrixMatNullSparsity"
}
],
"limitations": [
"This solver is tailored for systems where the coefficient matrix has a specific band (tridiagonal or nearly tridiagonal) structure. It may not perform well on general sparse matrices.",
"The performance gains are most pronounced when the problem size is large and the system matrix is particularly structured."
],
"name": "BTDLinearSolver",
"output_properties": [
{
"description": "The solution vector representing the computed displacements or velocities.",
"name": "solution",
"type": "VecDeriv"
},
{
"description": "The residual error after solving the linear system, which can be used to assess the accuracy of the solution.",
"name": "residual",
"type": "VecDeriv"
}
],
"parameters": [
{
"default_value": "false",
"description": "If enabled, it prints detailed information during the solving process.",
"name": "verbose",
"type": "bool"
},
{
"default_value": "false",
"description": "Forces the diagonal elements of the matrix to be strictly positive. This can help in cases where numerical issues might cause zero or negative values on the diagonal.",
"name": "constrainDiagonalElements",
"type": "bool"
},
{
"default_value": "true",
"description": "Stores the solution vector as part of the internal state, which can be useful for debugging and analysis purposes.",
"name": "storeSolutionInternalState",
"type": "bool"
}
],
"performance_tips": [
"Ensure that the input matrix conforms to the expected block-tridiagonal structure for optimal performance.",
"Enable verbose mode during debugging to get insight into the solving process and identify potential issues."
],
"related_components": [
{
"component_name": "SparseLDLSolver",
"description": "A more general-purpose sparse solver that can be used as an alternative when the specific band structure required by BTDLinearSolver is not present in the problem."
},
{
"component_name": "BlockFullMatrix6",
"description": "The specialized matrix type used internally to represent and manipulate matrices with a block-tridiagonal structure."
}
],
"usage_notes": [
"The BTDLinearSolver is particularly effective when dealing with systems where the matrix has a tridiagonal or nearly tridiagonal block structure.",
"Before using this solver, ensure that the system\u0027s matrix conforms to the expected structure and that all necessary properties (such as external forces and mass matrix) are correctly set up."
]
}
maths
The `BlockFullMatrix` is a specialized matrix class used in the Simulation Open-Framework Architecture (SOFA) for efficient storage and manipulation of block matrices. Block matrices are matrices composed of sub-matrices, or blocks, which can be manipulated individually to improve computational efficiency and memory usage.
### Mathematical Description:
- **Block Matrix Definition**: A block matrix is a partitioned matrix where each element is itself a matrix (block). For example, if we have a 6x6 block matrix with 3x3 sub-blocks, it can be represented as follows:
egin{equation}
A = \begin{bmatrix}
A_{11} & A_{12} & A_{13} \\
A_{21} & A_{22} & A_{23} \\
A_{31} & A_{32} & A_{33}
\end{bmatrix},
\end{equation}
where each $A_{ij}$ is a 2x2 sub-matrix.
- **Operations on Block Matrices**: The `BlockFullMatrix` class provides operations such as setting elements, clearing rows and columns, accessing blocks, and resizing. Each block can be manipulated individually or as part of the entire matrix:
egin{equation}
A_{ij} = \begin{bmatrix}
a & b \\
c & d
\end{bmatrix},
\end{equation}
where $a, b, c,$ and $d$ are scalar values.
### Physical Description:
- **Use Case**: The `BlockFullMatrix` class is particularly useful in simulations where the system's state or properties can be divided into smaller, more manageable components (blocks). For example, in multi-body dynamics, each body might have its own set of 2x2 blocks representing local stiffness matrices.
- **Efficiency and Memory Usage**: By storing and manipulating sub-matrices as blocks, the `BlockFullMatrix` can significantly reduce memory usage and improve computational efficiency. This is especially beneficial for large-scale simulations where standard matrix operations can be computationally expensive.
### Example:
Consider a 6x6 matrix with 2x2 block structure used to represent stiffness or mass properties in a multi-body system. Each 2x2 sub-block could represent the interaction between two bodies or local properties of a single body. Using `BlockFullMatrix`, these blocks can be accessed and manipulated efficiently, allowing for more complex simulations without significant computational overhead.
egin{equation}
K = \begin{bmatrix}
K_{11} & K_{12} \\
K_{21} & K_{22}
\end{bmatrix},
\end{equation}
where $K_{ij}$ are 3x3 sub-blocks representing stiffness matrices.
### Conclusion:
The `BlockFullMatrix` class provides a powerful and efficient way to handle block structures in simulations, making it an essential component for large-scale physical simulations where memory usage and computational efficiency are critical.
{
"name": "BlockFullMatrix",
"main": {
"name": "BlockFullMatrix",
"namespace": "sofa::linearalgebra",
"module": "Sofa.framework.LinearAlgebra",
"include": "sofa/linearalgebra/BlockFullMatrix.h",
"doc": "Simple block full matrix container (used for InvMatrixType)",
"inherits": [
"BaseMatrix"
],
"templates": [
"6, SReal"
],
"data_fields": [],
"links": [],
"methods": [
{
"name": "getSubMatrixDim",
"return_type": "Index",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": true,
"access": "public"
},
{
"name": "ptr",
"return_type": "Block *",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "bloc",
"return_type": "const Block &",
"params": [
{
"name": "bi",
"type": "Index"
},
{
"name": "bj",
"type": "Index"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "resize",
"return_type": "void",
"params": [
{
"name": "nbRow",
"type": "Index"
},
{
"name": "nbCol",
"type": "Index"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "rowSize",
"return_type": "Index",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "colSize",
"return_type": "Index",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "element",
"return_type": "SReal",
"params": [
{
"name": "i",
"type": "Index"
},
{
"name": "j",
"type": "Index"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "asub",
"return_type": "const Block &",
"params": [
{
"name": "bi",
"type": "Index"
},
{
"name": "bj",
"type": "Index"
},
{
"name": "",
"type": "Index"
},
{
"name": "",
"type": "Index"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "sub",
"return_type": "const Block &",
"params": [
{
"name": "i",
"type": "Index"
},
{
"name": "j",
"type": "Index"
},
{
"name": "",
"type": "Index"
},
{
"name": "",
"type": "Index"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getSubMatrix",
"return_type": "void",
"params": [
{
"name": "i",
"type": "Index"
},
{
"name": "j",
"type": "Index"
},
{
"name": "nrow",
"type": "Index"
},
{
"name": "ncol",
"type": "Index"
},
{
"name": "m",
"type": "B &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "getAlignedSubMatrix",
"return_type": "void",
"params": [
{
"name": "bi",
"type": "Index"
},
{
"name": "bj",
"type": "Index"
},
{
"name": "nrow",
"type": "Index"
},
{
"name": "ncol",
"type": "Index"
},
{
"name": "m",
"type": "B &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setSubMatrix",
"return_type": "void",
"params": [
{
"name": "i",
"type": "Index"
},
{
"name": "j",
"type": "Index"
},
{
"name": "nrow",
"type": "Index"
},
{
"name": "ncol",
"type": "Index"
},
{
"name": "m",
"type": "const B &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "setAlignedSubMatrix",
"return_type": "void",
"params": [
{
"name": "bi",
"type": "Index"
},
{
"name": "bj",
"type": "Index"
},
{
"name": "nrow",
"type": "Index"
},
{
"name": "ncol",
"type": "Index"
},
{
"name": "m",
"type": "const B &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "set",
"return_type": "void",
"params": [
{
"name": "i",
"type": "Index"
},
{
"name": "j",
"type": "Index"
},
{
"name": "v",
"type": "double"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "add",
"return_type": "void",
"params": [
{
"name": "i",
"type": "Index"
},
{
"name": "j",
"type": "Index"
},
{
"name": "v",
"type": "double"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "clear",
"return_type": "void",
"params": [
{
"name": "i",
"type": "Index"
},
{
"name": "j",
"type": "Index"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "clearRow",
"return_type": "void",
"params": [
{
"name": "i",
"type": "Index"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "clearCol",
"return_type": "void",
"params": [
{
"name": "j",
"type": "Index"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "clearRowCol",
"return_type": "void",
"params": [
{
"name": "i",
"type": "Index"
}
],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "clear",
"return_type": "void",
"params": [],
"is_virtual": true,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "operator*",
"return_type": "FullVector<Real2>",
"params": [
{
"name": "v",
"type": "const FullVector<Real2> &"
}
],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": false,
"access": "public"
},
{
"name": "Name",
"return_type": "const char *",
"params": [],
"is_virtual": false,
"is_pure_virtual": false,
"is_static": true,
"access": "public"
}
]
},
"desc": {
"component": {
"name": "BTDLinearSolver",
"category": "Constraint Solvers",
"description": "The BTDLinearSolver is a specialized solver designed for efficiently solving systems of linear equations with symmetric matrices that have a specific band structure, often found in certain types of mechanical systems simulations. It employs a Block Tridiagonal Decomposition (BTD) method to factorize and solve the system.",
"parameters": [
{
"name": "verbose",
"type": "bool",
"description": "If enabled, it prints detailed information during the solving process.",
"default_value": "false"
},
{
"name": "constrainDiagonalElements",
"type": "bool",
"description": "Forces the diagonal elements of the matrix to be strictly positive. This can help in cases where numerical issues might cause zero or negative values on the diagonal.",
"default_value": "false"
},
{
"name": "storeSolutionInternalState",
"type": "bool",
"description": "Stores the solution vector as part of the internal state, which can be useful for debugging and analysis purposes.",
"default_value": "true"
}
],
"input_properties": [
{
"name": "externalForces",
"type": "VecDeriv",
"description": "The external forces acting on the system."
},
{
"name": "massMatrix",
"type": "SparseMatrixMatNullSparsity",
"description": "The mass matrix of the system, which is required for solving certain types of dynamic systems."
}
],
"output_properties": [
{
"name": "solution",
"type": "VecDeriv",
"description": "The solution vector representing the computed displacements or velocities."
},
{
"name": "residual",
"type": "VecDeriv",
"description": "The residual error after solving the linear system, which can be used to assess the accuracy of the solution."
}
],
"dependencies": [
{
"component_name": "BlockFullMatrix6",
"description": "A matrix type that stores elements in a block-wise fashion, with each block being a 6x6 submatrix. This is crucial for representing and operating on matrices with the specific band structure required by BTDLinearSolver."
}
],
"usage_notes": [
"The BTDLinearSolver is particularly effective when dealing with systems where the matrix has a tridiagonal or nearly tridiagonal block structure.",
"Before using this solver, ensure that the system's matrix conforms to the expected structure and that all necessary properties (such as external forces and mass matrix) are correctly set up."
],
"example_code": [
{
"snippet": "BTDLinearSolver solver;\nsolver.setVerbose(true);\nsolver.solve(systemMatrix, externalForces, solution);",
"description": "This example demonstrates how to create an instance of the BTDLinearSolver and solve a linear system with verbose output."
}
],
"related_components": [
{
"component_name": "SparseLDLSolver",
"description": "A more general-purpose sparse solver that can be used as an alternative when the specific band structure required by BTDLinearSolver is not present in the problem."
},
{
"component_name": "BlockFullMatrix6",
"description": "The specialized matrix type used internally to represent and manipulate matrices with a block-tridiagonal structure."
}
],
"limitations": [
"This solver is tailored for systems where the coefficient matrix has a specific band (tridiagonal or nearly tridiagonal) structure. It may not perform well on general sparse matrices.",
"The performance gains are most pronounced when the problem size is large and the system matrix is particularly structured."
],
"performance_tips": [
"Ensure that the input matrix conforms to the expected block-tridiagonal structure for optimal performance.",
"Enable verbose mode during debugging to get insight into the solving process and identify potential issues."
]
}
},
"maths": {
"maths": "The `BlockFullMatrix` is a specialized matrix class used in the Simulation Open-Framework Architecture (SOFA) for efficient storage and manipulation of block matrices. Block matrices are matrices composed of sub-matrices, or blocks, which can be manipulated individually to improve computational efficiency and memory usage.\n\n### Mathematical Description:\n- **Block Matrix Definition**: A block matrix is a partitioned matrix where each element is itself a matrix (block). For example, if we have a 6x6 block matrix with 3x3 sub-blocks, it can be represented as follows:\n\n\begin{equation}\nA = \\begin{bmatrix}\n A_{11} & A_{12} & A_{13} \\\\\n A_{21} & A_{22} & A_{23} \\\\\n A_{31} & A_{32} & A_{33}\n\\end{bmatrix},\n\\end{equation}\nwhere each $A_{ij}$ is a 2x2 sub-matrix.\n\n- **Operations on Block Matrices**: The `BlockFullMatrix` class provides operations such as setting elements, clearing rows and columns, accessing blocks, and resizing. Each block can be manipulated individually or as part of the entire matrix:\n\n\begin{equation}\nA_{ij} = \\begin{bmatrix}\na & b \\\\\nc & d\n\\end{bmatrix},\n\\end{equation}\nwhere $a, b, c,$ and $d$ are scalar values.\n\n### Physical Description:\n- **Use Case**: The `BlockFullMatrix` class is particularly useful in simulations where the system's state or properties can be divided into smaller, more manageable components (blocks). For example, in multi-body dynamics, each body might have its own set of 2x2 blocks representing local stiffness matrices.\n\n- **Efficiency and Memory Usage**: By storing and manipulating sub-matrices as blocks, the `BlockFullMatrix` can significantly reduce memory usage and improve computational efficiency. This is especially beneficial for large-scale simulations where standard matrix operations can be computationally expensive.\n\n### Example:\nConsider a 6x6 matrix with 2x2 block structure used to represent stiffness or mass properties in a multi-body system. Each 2x2 sub-block could represent the interaction between two bodies or local properties of a single body. Using `BlockFullMatrix`, these blocks can be accessed and manipulated efficiently, allowing for more complex simulations without significant computational overhead.\n\n\begin{equation}\nK = \\begin{bmatrix}\n K_{11} & K_{12} \\\\\n K_{21} & K_{22}\n\\end{bmatrix},\n\\end{equation}\nwhere $K_{ij}$ are 3x3 sub-blocks representing stiffness matrices.\n\n### Conclusion:\nThe `BlockFullMatrix` class provides a powerful and efficient way to handle block structures in simulations, making it an essential component for large-scale physical simulations where memory usage and computational efficiency are critical."
},
"summary": {
"abstract": "`BlockFullMatrix` is a specialized matrix class used for efficient storage and manipulation of block matrices in SOFA, enabling computational efficiency in large-scale simulations.",
"sheet": "# BlockFullMatrix\n\n## Overview\nThe `BlockFullMatrix` is a specialized matrix class that inherits from `BaseMatrix`. It provides methods to efficiently store and manipulate block matrices, which are composed of sub-matrices (blocks). This component is particularly useful for computational efficiency in large-scale simulations involving multiple interacting components.\n\n## Mathematical Model\nA block matrix is defined as a partitioned matrix where each element is itself a matrix (block). For example, consider a 6x6 block matrix with 2x2 sub-blocks:\n\n\begin{equation}\nA = \begin{bmatrix}\n A_{11} & A_{12} & A_{13} \\\\\n A_{21} & A_{22} & A_{23} \\\\\n A_{31} & A_{32} & A_{33}\n\rend{bmatrix},\n\text{where each } A_{ij} \text{ is a 2x2 sub-matrix.}\n\\end{equation}\n\nOperations on block matrices include setting elements, clearing rows and columns, accessing blocks, and resizing. Each block can be manipulated individually or as part of the entire matrix:\n\n\begin{equation}\nA_{ij} = \begin{bmatrix}\na & b \\\\c & d\n\\end{bmatrix},\n\\text{where } a, b, c, \\text{ and } d \\text{ are scalar values.}\n\\end{equation}"
}
}