Methods

{
  "name": "RotationMatrix",
  "namespace": "sofa::linearalgebra",
  "module": "Sofa.framework.LinearAlgebra",
  "include": "sofa/linearalgebra/RotationMatrix.h",
  "doc": "3x3 block-diagonal matrix where each block is considered as a rotation.\n\\tparam TReal Type of scalar\nOne of the feature of this class is to rotate another matrix: if M is a matrix and R is a\nrotation matrix, it can compute M * R.",
  "inherits": [
    "BaseMatrix"
  ],
  "templates": [
    "double",
    "float"
  ],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "element(i,j)",
      "parameters": [
        {
          "name": "i",
          "type": "Index"
        },
        {
          "name": "j",
          "type": "sofa::SignedIndex"
        }
      ],
      "description": "Reads the value of the element at row i, column j (using 0-based indices).",
      "return_type": "SReal"
    },
    {
      "name": "resize(nbRow,nbCol)",
      "parameters": [
        {
          "name": "nbRow",
          "type": "sofa::SignedIndex"
        },
        {
          "name": "nbCol",
          "type": "sofa::SignedIndex"
        }
      ],
      "description": "Resizes the matrix and resets all values to 0. The number of rows (nbRow) should be a multiple of 3, as each block is 3x3."
    },
    {
      "name": "clear()",
      "parameters": [],
      "description": "Resets all elements in the matrix to 0.",
      "return_type": "void"
    },
    {
      "name": "setIdentity()",
      "parameters": [],
      "description": "Sets the matrix to be an identity rotation matrix, i.e., each block is set to the identity matrix.",
      "return_type": "void"
    },
    {
      "name": "set(i,j,v)",
      "parameters": [
        {
          "name": "i",
          "type": "sofa::SignedIndex"
        },
        {
          "name": "j",
          "type": "sofa::SignedIndex"
        },
        {
          "name": "v",
          "type": "double"
        }
      ],
      "description": "Writes the value v at row i, column j (using 0-based indices). The method is overridden from BaseMatrix.",
      "return_type": "void"
    },
    {
      "name": "add(i,j,v)",
      "parameters": [
        {
          "name": "i",
          "type": "sofa::SignedIndex"
        },
        {
          "name": "j",
          "type": "sofa::SignedIndex"
        },
        {
          "name": "v",
          "type": "double"
        }
      ],
      "description": "Adds v to the existing value at row i, column j (using 0-based indices). The method is overridden from BaseMatrix.",
      "return_type": "void"
    },
    {
      "name": "getVector()",
      "parameters": [],
      "description": "Returns a reference to the internal vector storing the matrix elements.",
      "return_type": "type::vector<Real>&"
    },
    {
      "name": "opMulV(result, v)",
      "parameters": [
        {
          "name": "result",
          "type": "linearalgebra::BaseVector*"
        },
        {
          "name": "v",
          "type": "const linearalgebra::BaseVector*"
        }
      ],
      "description": "Performs the matrix-vector multiplication and stores the result in the provided vector.",
      "return_type": "void"
    },
    {
      "name": "opMulTV(result, v)",
      "parameters": [
        {
          "name": "result",
          "type": "linearalgebra::BaseVector*"
        },
        {
          "name": "v",
          "type": "const linearalgebra::BaseVector*"
        }
      ],
      "description": "Performs the transpose matrix-vector multiplication and stores the result in the provided vector.",
      "return_type": "void"
    },
    {
      "name": "opMulTM(bresult, bm)",
      "parameters": [
        {
          "name": "bresult",
          "type": "linearalgebra::BaseMatrix *"
        },
        {
          "name": "bm",
          "type": "linearalgebra::BaseMatrix *"
        }
      ],
      "description": "Multiplies the transpose of this matrix with another matrix and stores the result in bresult.",
      "return_type": "void"
    },
    {
      "name": "rotateMatrix(mat, Jmat)",
      "parameters": [
        {
          "name": "mat",
          "type": "linearalgebra::BaseMatrix*"
        },
        {
          "name": "Jmat",
          "type": "const linearalgebra::BaseMatrix *"
        }
      ],
      "description": "Rotates the provided matrix (Jmat) by this rotation matrix and stores the result in mat.",
      "return_type": "void"
    }
  ],
  "description": "A 3x3 block-diagonal matrix where each block represents a rotation.",
  "properties": [
    {
      "name": "Data Type (float or double)",
      "type": "template parameter",
      "description": "The data type used for the elements of the RotationMatrix, can be either float or double."
    },
    {
      "name": "rowSize",
      "type": "sofa::SignedIndex",
      "description": "Returns the number of rows in the matrix. Each row corresponds to a 3x3 block representing a rotation."
    },
    {
      "name": "colSize",
      "type": "sofa::SignedIndex",
      "description": "Returns the number of columns in the matrix, which is equal to the number of rows as each block is square and represents a rotation."
    }
  ],
  "maths": "The `RotationMatrix` component in the SOFA framework represents a matrix with a specific structure: it is a block-diagonal matrix where each block is a $3 \\times 3$ rotation matrix. This matrix is used to perform rotations on vectors or other matrices, and can be useful for various operations within finite element simulations involving rigid body transformations.\n\n### Mathematical Description\n\n#### Structure of the Matrix\nThe `RotationMatrix` is defined as follows:\n\\[ R = \\begin{pmatrix}\nR_1 & 0 & \\cdots & 0 \\\\\n0 & R_2 & \\cdots & 0 \\\\\n\\vdots & \\vdots & \\ddots & \\vdots \\\\\n0 & 0 & \\cdots & R_n\n\\end{pmatrix} \\]\nwhere each $R_i$ is a $3 \\times 3$ rotation matrix, and the entire matrix has dimensions $(3N) \\times (3N)$ for $N$ blocks.\n\n#### Rotation Matrices\nEach $3 \\times 3$ block $R_i$ represents a rotation in three-dimensional space. The general form of a $3 \\times 3$ rotation matrix is given by:\n\\[ R_i = \\begin{pmatrix}\nc_{x_i}c_{y_i} & c_{x_i}s_{y_i}c_{z_i}-s_{x_i}s_{z_i} & c_{x_i}s_{y_i}s_{z_i}+s_{x_i}c_{z_i} \\\\\ns_{x_i}c_{y_i} & s_{x_i}s_{y_i}c_{z_i}+c_{x_i}s_{z_i} & s_{x_i}s_{y_i}s_{z_i}-c_{x_i}c_{z_i} \\\\\n-s_{y_i} & c_{y_i}c_{z_i} & c_{y_i}s_{z_i}\n\\end{pmatrix} \\]\nwhere $c_x = \\cos(\\theta_x)$, $s_x = \\sin(\\theta_x)$, and similarly for $y$ and $z$, with $\\theta_x$, $\\theta_y$, $\\theta_z$ being the rotation angles about the respective axes.\n\n#### Operations Supported by RotationMatrix\n1. **Element Access**\n   The element at row $i$, column $j$ can be accessed, where each block spans 3 rows and columns. The function `element(i, j)` retrieves this value.\n2. **Resize Operation**\n   The matrix can be resized to a new number of blocks, while maintaining the internal data structure.\n3. **Identity Initialization**\n   The matrix can be set to an identity matrix where each $R_i$ is the identity matrix:\n   \\[ R_i = I_3 = \\begin{pmatrix}\n1 & 0 & 0 \\\\\n0 & 1 & 0 \\\\\n0 & 0 & 1\n\\end{pmatrix} \\]\n4. **Matrix-Vector Multiplication**\n   The `opMulV` and `opMulTV` methods perform multiplication of the matrix by a vector, with `opMulV` computing $Rv$ and `opMulTV` computing $R^Tv$. These operations ensure that each block operates on consecutive elements in the vector.\n5. **Matrix-Matrix Multiplication**\n   The `opMulTM` method computes the product of the matrix's transpose with another matrix, storing the result in a specified matrix object.\n6. **Rotation Operations**\n   The `rotateSparseMatrix` and `rotateMatrix` methods allow for more complex operations involving sparse matrices or dense matrices, where the rotation is applied to specific elements based on the structure of the input matrix $Jmat$.\n\n### Numerical Methods and Discretization Choices\nThe `RotationMatrix` class does not involve any constitutive laws or discretization choices that would be typical in a finite element simulation pipeline. Instead, it operates at a more fundamental level, providing operations for performing rotations on vectors and matrices. These operations are essential for transformations within the context of deformable body simulations but do not directly contribute to the governing equations such as mass matrix $M$, stiffness matrix $K$, or internal forces $f_{int}$.\n\n### Role in FEM Pipeline\nIn the broader variational/Lagrangian mechanics framework, the `RotationMatrix` component plays a supporting role by enabling transformations that may be necessary for setting up boundary conditions, applying constraints, or handling rigid body components within the deformable system. For instance, rotations might be needed to align elements properly in pre-processing steps, or to apply specific motions during simulation.",
  "abstract": "The `RotationMatrix` represents a block-diagonal matrix where each $3 \\times 3$ block is a rotation matrix, enabling transformations on vectors or other matrices in finite element simulations.",
  "sheet": "# RotationMatrix\n\n**Overview**\n\nThe `RotationMatrix` component in the SOFA framework is a specialized linear algebra class designed to handle rotations. It represents a block-diagonal matrix where each $3 \\times 3$ block corresponds to a rotation matrix, facilitating operations such as rotating vectors or other matrices within finite element simulations.\n\n**Mathematical Model**\n\nThe `RotationMatrix` is defined as follows:\n\\[ R = \\begin{pmatrix}\nR_1 & 0 & \\cdots & 0 \\\\\n0 & R_2 & \\cdots & 0 \\\\\n\\vdots & \\vdots & \\ddots & \\vdots \\\\\n0 & 0 & \\cdots & R_n\n\\end{pmatrix} \\]\nwhere each $R_i$ is a $3 \\times 3$ rotation matrix, and the entire matrix has dimensions $(3N) \\times (3N)$ for $N$ blocks.\n\nEach $3 \\times 3$ block $R_i$ represents a rotation in three-dimensional space. The general form of a $3 \\times 3$ rotation matrix is given by:\n\\[ R_i = \\begin{pmatrix}\nc_{x_i}c_{y_i} & c_{x_i}s_{y_i}c_{z_i}-s_{x_i}s_{z_i} & c_{x_i}s_{y_i}s_{z_i}+s_{x_i}c_{z_i} \\\\\ns_{x_i}c_{y_i} & s_{x_i}s_{y_i}c_{z_i}+c_{x_i}s_{z_i} & s_{x_i}s_{y_i}s_{z_i}-c_{x_i}c_{z_i} \\\\\n-s_{y_i} & c_{y_i}c_{z_i} & c_{y_i}s_{z_i}\n\\end{pmatrix} \\]\nwhere $c_x = \\cos(\\theta_x)$, $s_x = \\sin(\\theta_x)$, and similarly for $y$ and $z$, with $\\theta_x$, $\\theta_y$, $\\theta_z$ being the rotation angles about the respective axes.\n\n**Operations Supported by RotationMatrix**\n1. **Element Access**: The element at row $i$, column $j$ can be accessed using `element(i, j)`, where each block spans 3 rows and columns.\n2. **Resize Operation**: The matrix can be resized to a new number of blocks while maintaining the internal data structure.\n3. **Identity Initialization**: The matrix can be set to an identity matrix where each $R_i$ is the identity matrix:\n\\[ R_i = I_3 = \\begin{pmatrix}\n1 & 0 & 0 \\\\\n0 & 1 & 0 \\\\\n0 & 0 & 1\n\\end{pmatrix} \\]\n4. **Matrix-Vector Multiplication**: The `opMulV` and `opMulTV` methods perform multiplication of the matrix by a vector, with `opMulV` computing $Rv$ and `opMulTV` computing $R^Tv$. These operations ensure that each block operates on consecutive elements in the vector.\n5. **Matrix-Matrix Multiplication**: The `opMulTM` method computes the product of the matrix's transpose with another matrix, storing the result in a specified matrix object.\n6. **Rotation Operations**: The `rotateSparseMatrix` and `rotateMatrix` methods allow for more complex operations involving sparse matrices or dense matrices, where the rotation is applied to specific elements based on the structure of the input matrix $Jmat$."
}