{
  "name": "FastTetrahedralCorotationalForceField",
  "main": {
    "name": "FastTetrahedralCorotationalForceField",
    "namespace": "sofa::component::solidmechanics::fem::elastic",
    "module": "Sofa.Component.SolidMechanics.FEM.Elastic",
    "include": "sofa/component/solidmechanics/fem/elastic/FastTetrahedralCorotationalForceField.h",
    "doc": "Fast Corotational Tetrahedral Mesh.",
    "inherits": [
      "BaseLinearElasticityFEMForceField"
    ],
    "templates": [
      "sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [
      {
        "name": "d_drawing",
        "type": "bool",
        "xmlname": "drawing",
        "help": " draw the forcefield if true"
      },
      {
        "name": "d_drawColor1",
        "type": "sofa::type::RGBAColor",
        "xmlname": "drawColor1",
        "help": " draw color for faces 1"
      },
      {
        "name": "d_drawColor2",
        "type": "sofa::type::RGBAColor",
        "xmlname": "drawColor2",
        "help": " draw color for faces 2"
      },
      {
        "name": "d_drawColor3",
        "type": "sofa::type::RGBAColor",
        "xmlname": "drawColor3",
        "help": " draw color for faces 3"
      },
      {
        "name": "d_drawColor4",
        "type": "sofa::type::RGBAColor",
        "xmlname": "drawColor4",
        "help": " draw color for faces 4"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addForce",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "const sofa::core::MechanicalParams *"
          },
          {
            "name": "dataF",
            "type": "DataVecDeriv &"
          },
          {
            "name": "dataX",
            "type": "const DataVecCoord &"
          },
          {
            "name": "dataV",
            "type": "const DataVecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addDForce",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "const sofa::core::MechanicalParams *"
          },
          {
            "name": "datadF",
            "type": "DataVecDeriv &"
          },
          {
            "name": "datadX",
            "type": "const DataVecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getPotentialEnergy",
        "return_type": "SReal",
        "params": [
          {
            "name": "",
            "type": "const core::MechanicalParams *"
          },
          {
            "name": "",
            "type": "const DataVecCoord &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addKToMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "m",
            "type": "sofa::linearalgebra::BaseMatrix *"
          },
          {
            "name": "kFactor",
            "type": "SReal"
          },
          {
            "name": "offset",
            "type": "unsigned int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "buildStiffnessMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "matrix",
            "type": "core::behavior::StiffnessMatrix *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "buildDampingMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "matrix",
            "type": "core::behavior::DampingMatrix *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "updateTopologyInformation",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setRotationDecompositionMethod",
        "return_type": "void",
        "params": [
          {
            "name": "m",
            "type": "const RotationDecompositionMethod"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "draw",
        "return_type": "void",
        "params": [
          {
            "name": "vparams",
            "type": "const core::visual::VisualParams *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computeQRRotation",
        "return_type": "void",
        "params": [
          {
            "name": "r",
            "type": "Mat3x3 &"
          },
          {
            "name": "dp",
            "type": "const Coord *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": true,
        "access": "protected"
      },
      {
        "name": "createTetrahedronRestInformation",
        "return_type": "void",
        "params": [
          {
            "name": "",
            "type": "Index"
          },
          {
            "name": "t",
            "type": "TetrahedronRestInformation &"
          },
          {
            "name": "",
            "type": "const core::topology::BaseMeshTopology::Tetrahedron &"
          },
          {
            "name": "",
            "type": "const int &"
          },
          {
            "name": "",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "getEdgeInfo",
        "return_type": "int &",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "name": "Fast Corotational Tetrahedral Mesh Force Field",
    "description": "This component implements a fast corotational finite element method for tetrahedral meshes, suitable for simulating deformable objects in real-time applications.",
    "parameters": [
      {
        "name": "method",
        "type": "string",
        "default_value": "",
        "description": "Method used to compute the rotation between rest and deformed configurations. Options are 'qr' (QR decomposition), 'polar', 'polar2', or 'none' for linear elastic behavior."
      },
      {
        "name": "drawing",
        "type": "bool",
        "default_value": "false",
        "description": "Whether to draw the force field visualization in the scene."
      },
      {
        "name": "drawColor1-4",
        "type": "RGBAColor",
        "default_value": "[0, 0, 0, 1]",
        "description": "Colors used for drawing different parts of the tetrahedron faces when 'drawing' is enabled."
      }
    ],
    "functionality": [
      {
        "name": "Initialization",
        "description": "Initializes the force field by computing rest configurations and setting up internal data structures for tetrahedrons, edges, and points."
      },
      {
        "name": "Force Computation",
        "description": "Computes forces acting on each node based on deformations from the rest configuration. Uses corotational formulation to separate rotations and linear elastic deformations."
      },
      {
        "name": "Stiffness Matrix Construction",
        "description": "Builds the global stiffness matrix by assembling contributions from individual tetrahedrons."
      },
      {
        "name": "Visualization",
        "description": "Provides optional visualization of the force field, highlighting different parts of each tetrahedron with specified colors."
      }
    ],
    "dependencies": [
      {
        "name": "core"
      },
      {
        "name": "topology"
      },
      {
        "name": "linearalgebra"
      }
    ]
  },
  "maths": {
    "maths": "## Mathematical Description\n\nThe Fast Corotational Tetrahedral Mesh (FastTetrahedralCorotationalForceField) is a finite element method designed for real-time simulation of deformable objects using tetrahedral meshes. The corotation method aims to separate large rotations from small elastic deformations, which allows the use of simpler linear elasticity models while still maintaining a high degree of accuracy.\n\n### Tetrahedron Shape Functions and Linear Elasticity Model\n\nThe shape functions for each tetrahedron are used to interpolate displacements within the element. For a tetrahedral mesh with vertices $i$, $j$, $k$, and $l$, let the displacement vector at vertex $a$ be denoted as $\boldsymbol{u}_a$. The linear elasticity model can then be expressed using the strain-displacement relationship and Hooke's Law.\n\n1. **Strain-Displacement Relationship:**\nThe Green-Lagrange strain tensor, $\boldsymbol{\textbf{E}}$, relates to the deformation gradient $\boldsymbol{F}$ via $\\mathbf{F} = \nabla \\boldsymbol{u} + I$ where $I$ is the identity matrix. For small deformations, we can approximate this with a linearized strain tensor:\n\n$$\n\\boldsymbol{E} \\approx \\frac{1}{2}(\\mathbf{F^T}\\mathbf{F}-I) = \\frac{1}{2}(\\nabla \\boldsymbol{u} + (\\nabla \\boldsymbol{u})^{\\text{T}}).\n$$\n\n2. **Hooke's Law:**\nThe stress tensor $\boldsymbol{\\sigma}$ is related to the strain via Hooke's law in linear elasticity:\n\n$$\n\\boldsymbol{\\sigma} = 2 \\mu \\boldsymbol{E} + \\lambda \\text{tr}(\\boldsymbol{E})I,\n$$\n\nwhere $\\mu$ and $\\lambda$ are the Lamé parameters, which can be derived from Young's modulus ($E$) and Poisson ratio ($\\nu$):\n\n$$\n\\mu = \\frac{E}{2(1+\\nu)}, \\quad \n\\lambda = \\frac{E\\nu}{(1+\\nu)(1-2\\nu)}.\n$$\n\n### Corotational Framework\nThe corotational method uses a polar decomposition of the deformation gradient $\\mathbf{F}$ to separate rigid body rotations from elastic deformations:\n\n$$\n\\mathbf{F} = \\mathbf{R}\\mathbf{U},\n$$\n\nwhere $\\mathbf{R}$ is a rotation matrix, and $\\mathbf{U}$ represents the stretching. The polar decomposition can be computed using QR or SVD (Singular Value Decomposition) methods.\n\nIn this component, rotations are stored in the `TetrahedronRestInformation` structure for each tetrahedron. For a given element with deformed vertices $\\boldsymbol{x}_i$, $\\boldsymbol{x}_j$, $\\boldsymbol{x}_k$, and $\\boldsymbol{x}_l$, we can compute the rotation matrix $\\mathbf{R}$ from the rest configuration to the current configuration using:\n\n$$\n\\mathbf{R} = \\text{polarDecomposition}(\\mathbf{F}).\n$$\n\n### Potential Energy and Forces\nThe potential energy of a tetrahedron is calculated based on the linearized strain-displacement relationship and stored in an internal data structure (e.g., `d_tetrahedronInfo`). The force contributions are computed by taking the negative gradient of this potential with respect to displacements.\n\n1. **Potential Energy:**\nThe total potential energy $U$ for a tetrahedral mesh can be written as:\n\n$$\nU = \\frac{1}{2}\\sum_{i=1}^{N_e} (\\boldsymbol{u}_{e_i}, \\mathbf{K}_e \\boldsymbol{u}_{e_i}),\n$$\n\nwhere $\\boldsymbol{u}_{e_i}$ is the displacement vector for element $i$, and $\\mathbf{K}_e$ is the stiffness matrix for the linear elastic model.\n\n2. **Forces:**\nThe internal forces are computed as:\n\n$$\n\\boldsymbol{f} = - \\frac{dU}{d\\boldsymbol{u}}.\n$$\n\n### Rotation Decomposition Methods\nThe component supports several methods for computing the rotation matrix $\\mathbf{R}$, including QR decomposition (`QR_DECOMPOSITION`), polar decomposition (`POLAR_DECOMPOSITION`), modified polar decomposition (`POLAR_DECOMPOSITION_MODIFIED`), and linear elasticity without rotation separation (`LINEAR_ELASTIC`).\n\n### Visualization\nThe component includes a method for visualizing the force field by drawing tetrahedra with different colors on each face.\n"
  },
  "summary": {
    "abstract": "The FastTetrahedralCorotationalForceField implements a fast corotational finite element method for tetrahedral meshes, separating large rotations from small elastic deformations using linear elasticity models.",
    "sheet": "# FastTetrahedralCorotationalForceField\n\n## Overview\nThis component implements the corotational finite element method (FEM) for tetrahedral meshes. It separates large rotations from small elastic deformations to enable efficient real-time simulations of deformable objects.\n\n## Mathematical Model\nThe corotational FEM uses a linear elasticity model with strain-displacement relationships and Hooke's Law:\n\n1. **Strain-Displacement Relationship:*\n$$\n\\boldsymbol{E} \\approx \\frac{1}{2}(\\mathbf{F^T}\\mathbf{F}-I) = \\frac{1}{2}(\\nabla \\boldsymbol{u} + (\\nabla \\boldsymbol{u})^{\\text{T}}).\n$$\n\n2. **Hooke's Law:*\n$$\n\\boldsymbol{σ} = 2 μ \\boldsymbol{E} + λ \\text{tr}(\\boldsymbol{E})I,\n$$\nwhere $\\mu$ and $\\lambda$ are the Lamé parameters derived from Young's modulus ($E$) and Poisson ratio ($ν$):\n$$\n\\mu = \\frac{E}{2(1+ν)},  \\quad\n\\lambda = \\frac{Eν}{(1+ν)(1-2ν)}.\n$$\n\nThe corotational framework decomposes the deformation gradient $\\mathbf{F}$ into a rotation matrix $\\mathbf{R}$ and stretching $\\mathbf{U}$:\n$$\n\\mathbf{F} = \\mathbf{R}\\mathbf{U},\n$$\nwhere $\\mathbf{R}$ is computed using polar decomposition.\n\n## Parameters and Data\nThe component exposes the following visualization settings:\n- `drawing`: Draw the forcefield if true (default: false).\n- `drawColor1`, `drawColor2`, `drawColor3`, `drawColor4`: Colors for faces 1, 2, 3, and 4.\n\n## Practical Notes\nThe corotational method ensures numerical stability by separating large rotations from small deformations. The choice of rotation decomposition method (QR or polar) can affect performance and accuracy."
  }
}