BTDMatrix

The BTDMatrix is a specialized matrix implementation in the Sofa framework used for simulations involving rigid bodies and large-scale deformable models. It stands for Block Tridiagonal Decomposition Matrix, which stores only the blocks that are likely to be non-zero in matrices representing certain types of physical systems.

abstract: BTDMatrix is a block tridiagonal decomposition matrix implementation in SOFA, designed for simulations involving rigid bodies and large-scale deformable models.
sheet: # BTDMatrix ## Overview The `BTDMatrix` is a specialized matrix container that implements the Block Tridiagonal Decomposition (BTD) method. It inherits from `BaseMatrix` and is particularly useful in simulations involving rigid bodies and large-scale deformable models, where matrices often have a block tridiagonal structure. ## Methods - **getSubMatrixDim**: Returns the dimension of submatrix blocks. - **ptr**: Provides access to internal block pointers. - **bloc**: Retrieves a specific block from the matrix. - **resize**: Resizes the matrix dimensions. - **rowSize** and **colSize**: Return the number of rows and columns, respectively. - **element**: Accesses an individual element in the matrix. - **asub** and **sub**: Retrieve submatrix blocks with specified indices. - **getSubMatrix** and **getAlignedSubMatrix**: Extracts a submatrix from the main matrix. - **setSubMatrix** and **setAlignedSubMatrix**: Sets a submatrix within the main matrix. - **set**: Assigns a value to an element in the matrix. - **add**: Adds a value or matrix block to an element or submatrix. - **clear**, **clearRow**, **clearCol**, **clearRowCol**: Clear elements, rows, columns, and row-columns respectively. - **operator***: Performs matrix-vector multiplication.

name

BTDMatrix

description

parameters

{'name': 'N', 'description': 'The size of submatrices (blocks). The BTDMatrix implementation is templated on N.', 'type': 'integer'}
{'name': 'T', 'description': 'The data type used for the matrix elements, often a real number type such as SReal.', 'type': 'data_type'}

methods

{'name': 'BTDMatrix()', 'description': 'Constructor that initializes an empty BTDMatrix.'}
{'name': 'BTDMatrix(Index nbRow, Index nbCol)', 'description': 'Constructor that creates a BTDMatrix with the specified number of rows and columns.', 'parameters': ['nbRow', 'nbCol']}
{'name': '~BTDMatrix()', 'description': 'Destructor that cleans up allocated resources.'}
{'name': 'Block* ptr() const', 'description': 'Returns a pointer to the underlying block storage.'}
{'name': 'const Block& bloc(Index bi, Index bj) const', 'description': 'Gets a reference to the specified block (bi, bj).'}
{'name': 'Block& bloc(Index bi, Index bj)', 'description': 'Gets a non-const reference to the specified block (bi, bj).'}
{'name': 'resize(Index nbRow, Index nbCol)', 'description': 'Resizes the BTDMatrix to have nbRow rows and nbCol columns.', 'parameters': ['nbRow', 'nbCol']}
{'name': 'Index rowSize() const', 'description': 'Returns the number of rows in the matrix.'}
{'name': 'Index colSize() const', 'description': 'Returns the number of columns in the matrix.'}
{'name': 'SReal element(Index i, Index j) const', 'description': 'Gets the value at position (i,j).'}
{'name': 'const Block& sub(Index i, Index j, Index nrow, Index ncol)', 'description': 'Gets a submatrix starting from (i,j) with dimensions nrow x ncol.', 'parameters': ['Index i', 'Index j', 'Index nrow', 'Index ncol']}
{'name': 'Block& sub(Index i, Index j, Index nrow, Index ncol)', 'description': 'Gets a non-const reference to the submatrix starting from (i,j) with dimensions nrow x ncol.', 'parameters': ['Index i', 'Index j', 'Index nrow', 'Index ncol']}
{'name': 'set(Index i, Index j, double v)', 'description': 'Sets the value at position (i,j).', 'parameters': ['Index i', 'Index j', 'double v']}
{'name': 'add(Index i, Index j, double v)', 'description': 'Adds a value to the element at position (i,j).', 'parameters': ['Index i', 'Index j', 'double v']}
{'name': 'clear(Index i, Index j)', 'description': 'Sets the value at position (i,j) to zero.'}
{'name': 'clearRow(Index i)', 'description': 'Clears (sets to zero) all values in row i.'}
{'name': 'clearCol(Index j)', 'description': 'Clears (sets to zero) all values in column j.'}

example_usage

This BTDMatrix can be used as a sparse matrix representation that is efficient for certain types of simulation problems where the interaction between rigid bodies or large deformable models is localized and can be represented with blocks along the main diagonal and diagonals adjacent to it. ```cpp #include <sofa/linearalgebra/BTDMatrix.h> using namespace sofa::defaulttype; typedef BTDMatrix<6, SReal> RigidBTDMatrix; RigidBTDMatrix mat(100, 100); mat.set(5, 5, 3.14); double val = mat.element(5, 5); // will return 3.14 ```

notes

This class is specialized for use in physics simulations and does not provide a full matrix implementation (such as inversion). It's particularly optimized for systems where interactions are localizable within blocks of a certain size N.

componentDescription

{
  "description": "The BTDMatrix (Block Tridiagonal Decomposition Matrix) is a specialized matrix implementation designed for efficient storage and manipulation of matrices that represent certain physical systems, particularly those involving rigid bodies and deformable models in the Sofa simulation framework. This data structure stores only the blocks that are likely to be non-zero, optimizing memory usage and computational efficiency.",
  "mathematicalDescription": {
    "blockDimension": "N x N where N is a predefined dimension (e.g., 6 for rigid bodies)",
    "blocks": [
      {
        "diagonalBlocks": "Diagonal blocks store interactions within the same block of indices.",
        "subDiagonalBlocks": "Sub-diagonal blocks store interactions between adjacent blocks where j = i-1.",
        "superDiagonalBlocks": "Super-diagonal blocks store interactions between adjacent blocks where j = i+1."
      }
    ],
    "matrixDimension": {
      "colSize": "nTCol",
      "rowSize": "nTRow"
    },
    "matrixType": "Block Tridiagonal Matrix",
    "resizingBehavior": {
      "dynamicResizing": "The matrix can be resized dynamically with the \u0027resize\u0027 method, maintaining the block tridiagonal structure."
    },
    "storageScheme": "Stores only the blocks on the main diagonal, sub-diagonal, and super-diagonal."
  },
  "methodsAndOperations": {
    "blockManipulation": {
      "clearOperations": [
        {
          "clearElement": "Clears a single element at (i,j)."
        },
        {
          "clearRow": "Resets an entire row."
        },
        {
          "clearCol": "Resets an entire column."
        },
        {
          "clearRowCol": "Resets both the specified row and column."
        }
      ],
      "setBlock": [
        {
          "setSubMatrix": "Sets a submatrix in the specified location using the provided matrix B."
        },
        {
          "add": "Adds values to specific elements or blocks within the matrix, supporting optimized contributions of block-sized matrices for larger N."
        }
      ]
    },
    "elementAccess": {
      "getBlock": [
        {
          "asub": "Returns a specific sub-block based on block indices."
        },
        {
          "sub": "Returns a submatrix of the given size starting from a particular index."
        }
      ],
      "getElement": "Returns an element at specified indices (i, j) in the overall matrix."
    },
    "matrixMultiplication": {
      "multiplyByVector": "Computes the product of this matrix with a vector, returning another vector."
    },
    "resize": "Resizes the matrix while maintaining its block tridiagonal structure. Ensures that only necessary blocks are allocated."
  },
  "name": "BTDMatrix",
  "namespace": "sofa::linearalgebra",
  "physicalDescription": {
    "advantages": [
      "Efficient memory usage by storing only relevant blocks.",
      "Optimized computational efficiency due to the sparse storage format.",
      "Well-suited for systems where interactions are primarily local (e.g., adjacent rigid bodies or nodes in a deformable model)."
    ],
    "applicationDomain": [
      "Rigid Body Simulations",
      "Deformable Models"
    ]
  }
}

{
  "name": "BTDMatrix",
  "main": {
    "name": "BTDMatrix",
    "namespace": "sofa::linearalgebra",
    "module": "Sofa.framework.LinearAlgebra",
    "include": "sofa/linearalgebra/BTDMatrix.h",
    "doc": "Simple BTD matrix container",
    "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": "add",
        "return_type": "void",
        "params": [
          {
            "name": "row",
            "type": "Index"
          },
          {
            "name": "col",
            "type": "Index"
          },
          {
            "name": "v",
            "type": "const type::Mat<BSIZE, BSIZE, Real> &"
          }
        ],
        "is_virtual": false,
        "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": {
    "name": "BTDMatrix",
    "description": "The BTDMatrix is a specialized matrix implementation in the Sofa framework used for simulations involving rigid bodies and large-scale deformable models. It stands for Block Tridiagonal Decomposition Matrix, which stores only the blocks that are likely to be non-zero in matrices representing certain types of physical systems.",
    "parameters": [
      {
        "name": "N",
        "description": "The size of submatrices (blocks). The BTDMatrix implementation is templated on N.",
        "type": "integer"
      },
      {
        "name": "T",
        "description": "The data type used for the matrix elements, often a real number type such as SReal.",
        "type": "data_type"
      }
    ],
    "methods": [
      {
        "name": "BTDMatrix()",
        "description": "Constructor that initializes an empty BTDMatrix."
      },
      {
        "name": "BTDMatrix(Index nbRow, Index nbCol)",
        "description": "Constructor that creates a BTDMatrix with the specified number of rows and columns.",
        "parameters": [
          "nbRow",
          "nbCol"
        ]
      },
      {
        "name": "~BTDMatrix()",
        "description": "Destructor that cleans up allocated resources."
      },
      {
        "name": "Block* ptr() const",
        "description": "Returns a pointer to the underlying block storage."
      },
      {
        "name": "const Block& bloc(Index bi, Index bj) const",
        "description": "Gets a reference to the specified block (bi, bj)."
      },
      {
        "name": "Block& bloc(Index bi, Index bj)",
        "description": "Gets a non-const reference to the specified block (bi, bj)."
      },
      {
        "name": "resize(Index nbRow, Index nbCol)",
        "description": "Resizes the BTDMatrix to have nbRow rows and nbCol columns.",
        "parameters": [
          "nbRow",
          "nbCol"
        ]
      },
      {
        "name": "Index rowSize() const",
        "description": "Returns the number of rows in the matrix."
      },
      {
        "name": "Index colSize() const",
        "description": "Returns the number of columns in the matrix."
      },
      {
        "name": "SReal element(Index i, Index j) const",
        "description": "Gets the value at position (i,j)."
      },
      {
        "name": "const Block& sub(Index i, Index j, Index nrow, Index ncol)",
        "description": "Gets a submatrix starting from (i,j) with dimensions nrow x ncol.",
        "parameters": [
          "Index i",
          "Index j",
          "Index nrow",
          "Index ncol"
        ]
      },
      {
        "name": "Block& sub(Index i, Index j, Index nrow, Index ncol)",
        "description": "Gets a non-const reference to the submatrix starting from (i,j) with dimensions nrow x ncol.",
        "parameters": [
          "Index i",
          "Index j",
          "Index nrow",
          "Index ncol"
        ]
      },
      {
        "name": "set(Index i, Index j, double v)",
        "description": "Sets the value at position (i,j).",
        "parameters": [
          "Index i",
          "Index j",
          "double v"
        ]
      },
      {
        "name": "add(Index i, Index j, double v)",
        "description": "Adds a value to the element at position (i,j).",
        "parameters": [
          "Index i",
          "Index j",
          "double v"
        ]
      },
      {
        "name": "clear(Index i, Index j)",
        "description": "Sets the value at position (i,j) to zero."
      },
      {
        "name": "clearRow(Index i)",
        "description": "Clears (sets to zero) all values in row i."
      },
      {
        "name": "clearCol(Index j)",
        "description": "Clears (sets to zero) all values in column j."
      }
    ],
    "example_usage": "This BTDMatrix can be used as a sparse matrix representation that is efficient for certain types of simulation problems where the interaction between rigid bodies or large deformable models is localized and can be represented with blocks along the main diagonal and diagonals adjacent to it.\n\n```cpp\n#include <sofa/linearalgebra/BTDMatrix.h>\nusing namespace sofa::defaulttype;\ntypedef BTDMatrix<6, SReal> RigidBTDMatrix;\nRigidBTDMatrix mat(100, 100);\nmat.set(5, 5, 3.14);\ndouble val = mat.element(5, 5); // will return 3.14\n```",
    "notes": "This class is specialized for use in physics simulations and does not provide a full matrix implementation (such as inversion). It's particularly optimized for systems where interactions are localizable within blocks of a certain size N."
  },
  "maths": {
    "componentDescription": {
      "name": "BTDMatrix",
      "namespace": "sofa::linearalgebra",
      "description": "The BTDMatrix (Block Tridiagonal Decomposition Matrix) is a specialized matrix implementation designed for efficient storage and manipulation of matrices that represent certain physical systems, particularly those involving rigid bodies and deformable models in the Sofa simulation framework. This data structure stores only the blocks that are likely to be non-zero, optimizing memory usage and computational efficiency.",
      "mathematicalDescription": {
        "matrixType": "Block Tridiagonal Matrix",
        "blockDimension": "N x N where N is a predefined dimension (e.g., 6 for rigid bodies)",
        "storageScheme": "Stores only the blocks on the main diagonal, sub-diagonal, and super-diagonal.",
        "blocks": [
          {
            "diagonalBlocks": "Diagonal blocks store interactions within the same block of indices.",
            "subDiagonalBlocks": "Sub-diagonal blocks store interactions between adjacent blocks where j = i-1.",
            "superDiagonalBlocks": "Super-diagonal blocks store interactions between adjacent blocks where j = i+1."
          }
        ],
        "matrixDimension": {
          "rowSize": "nTRow",
          "colSize": "nTCol"
        },
        "resizingBehavior": {
          "dynamicResizing": "The matrix can be resized dynamically with the 'resize' method, maintaining the block tridiagonal structure."
        }
      },
      "physicalDescription": {
        "applicationDomain": [
          "Rigid Body Simulations",
          "Deformable Models"
        ],
        "advantages": [
          "Efficient memory usage by storing only relevant blocks.",
          "Optimized computational efficiency due to the sparse storage format.",
          "Well-suited for systems where interactions are primarily local (e.g., adjacent rigid bodies or nodes in a deformable model)."
        ]
      },
      "methodsAndOperations": {
        "resize": "Resizes the matrix while maintaining its block tridiagonal structure. Ensures that only necessary blocks are allocated.",
        "elementAccess": {
          "getElement": "Returns an element at specified indices (i, j) in the overall matrix.",
          "getBlock": [
            {
              "asub": "Returns a specific sub-block based on block indices."
            },
            {
              "sub": "Returns a submatrix of the given size starting from a particular index."
            }
          ]
        },
        "blockManipulation": {
          "setBlock": [
            {
              "setSubMatrix": "Sets a submatrix in the specified location using the provided matrix B."
            },
            {
              "add": "Adds values to specific elements or blocks within the matrix, supporting optimized contributions of block-sized matrices for larger N."
            }
          ],
          "clearOperations": [
            {
              "clearElement": "Clears a single element at (i,j)."
            },
            {
              "clearRow": "Resets an entire row."
            },
            {
              "clearCol": "Resets an entire column."
            },
            {
              "clearRowCol": "Resets both the specified row and column."
            }
          ]
        },
        "matrixMultiplication": {
          "multiplyByVector": "Computes the product of this matrix with a vector, returning another vector."
        }
      }
    }
  },
  "summary": {
    "abstract": "BTDMatrix is a block tridiagonal decomposition matrix implementation in SOFA, designed for simulations involving rigid bodies and large-scale deformable models.",
    "sheet": "# BTDMatrix\n\n## Overview\n\nThe `BTDMatrix` is a specialized matrix container that implements the Block Tridiagonal Decomposition (BTD) method. It inherits from `BaseMatrix` and is particularly useful in simulations involving rigid bodies and large-scale deformable models, where matrices often have a block tridiagonal structure.\n\n## Methods\n\n- **getSubMatrixDim**: Returns the dimension of submatrix blocks.\n- **ptr**: Provides access to internal block pointers.\n- **bloc**: Retrieves a specific block from the matrix.\n- **resize**: Resizes the matrix dimensions.\n- **rowSize** and **colSize**: Return the number of rows and columns, respectively.\n- **element**: Accesses an individual element in the matrix.\n- **asub** and **sub**: Retrieve submatrix blocks with specified indices.\n- **getSubMatrix** and **getAlignedSubMatrix**: Extracts a submatrix from the main matrix.\n- **setSubMatrix** and **setAlignedSubMatrix**: Sets a submatrix within the main matrix.\n- **set**: Assigns a value to an element in the matrix.\n- **add**: Adds a value or matrix block to an element or submatrix.\n- **clear**, **clearRow**, **clearCol**, **clearRowCol**: Clear elements, rows, columns, and row-columns respectively.\n- **operator***: Performs matrix-vector multiplication."
  }
}