Data Fields

Methods

{
  "name": "TriangleFEMForceField",
  "namespace": "sofa::component::solidmechanics::fem::elastic",
  "module": "Sofa.Component.SolidMechanics.FEM.Elastic",
  "include": "sofa/component/solidmechanics/fem/elastic/TriangleFEMForceField.h",
  "doc": "Triangular finite elements for static topology.\n\nTriangle FEM force field using the QR decomposition of the deformation gradient, inspired from http://www-evasion.imag.fr/Publications/2005/NPF05 , to handle large displacements.\n  The material properties are uniform across the domain.\n  Two methods are proposed, one for small displacements and one for large displacements.\n  The method for small displacements has not been validated and we suspect that it is broke. Use it very carefully, and compare with the method for large displacements.",
  "inherits": [
    "BaseLinearElasticityFEMForceField"
  ],
  "templates": [
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "d_initialPoints",
      "type": "VecCoord",
      "xmlname": "initialPoints",
      "help": "Initial Position"
    },
    {
      "name": "d_thickness",
      "type": "Real",
      "xmlname": "thickness",
      "help": "Thickness of the elements"
    },
    {
      "name": "d_planeStrain",
      "type": "bool",
      "xmlname": "planeStrain",
      "help": "Plane strain or plane stress assumption"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "reinit",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addForce",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "f",
          "type": "DataVecDeriv &"
        },
        {
          "name": "x",
          "type": "const DataVecCoord &"
        },
        {
          "name": "v",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addDForce",
      "return_type": "void",
      "params": [
        {
          "name": "mparams",
          "type": "const core::MechanicalParams *"
        },
        {
          "name": "df",
          "type": "DataVecDeriv &"
        },
        {
          "name": "dx",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "addKToMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "mat",
          "type": "sofa::linearalgebra::BaseMatrix *"
        },
        {
          "name": "k",
          "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": "",
          "type": "core::behavior::DampingMatrix *"
        }
      ],
      "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": "computeBBox",
      "return_type": "void",
      "params": [
        {
          "name": "params",
          "type": "const core::ExecParams *"
        },
        {
          "name": "onlyVisible",
          "type": "bool"
        }
      ],
      "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": "getMethod",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "setMethod",
      "return_type": "void",
      "params": [
        {
          "name": "val",
          "type": "int"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getRotatedInitialElement",
      "return_type": "const int &",
      "params": [
        {
          "name": "elemId",
          "type": "Index"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getRotationMatrix",
      "return_type": "const Transformation &",
      "params": [
        {
          "name": "elemId",
          "type": "Index"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getMaterialStiffness",
      "return_type": "const MaterialStiffness &",
      "params": [
        {
          "name": "elemId",
          "type": "Index"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getStrainDisplacements",
      "return_type": "const StrainDisplacement &",
      "params": [
        {
          "name": "elemId",
          "type": "Index"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "applyStiffness",
      "return_type": "void",
      "params": [
        {
          "name": "f",
          "type": "VecCoord &"
        },
        {
          "name": "h",
          "type": "Real"
        },
        {
          "name": "x",
          "type": "const VecCoord &"
        },
        {
          "name": "kFactor",
          "type": "const Real &"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "computeMaterialStiffnesses",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "initSmall",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "accumulateForceSmall",
      "return_type": "void",
      "params": [
        {
          "name": "f",
          "type": "VecCoord &"
        },
        {
          "name": "p",
          "type": "const VecCoord &"
        },
        {
          "name": "implicit",
          "type": "bool"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "applyStiffnessSmall",
      "return_type": "void",
      "params": [
        {
          "name": "f",
          "type": "VecCoord &"
        },
        {
          "name": "h",
          "type": "Real"
        },
        {
          "name": "x",
          "type": "const VecCoord &"
        },
        {
          "name": "kFactor",
          "type": "const Real &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "initLarge",
      "return_type": "void",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "accumulateForceLarge",
      "return_type": "void",
      "params": [
        {
          "name": "f",
          "type": "VecCoord &"
        },
        {
          "name": "p",
          "type": "const VecCoord &"
        },
        {
          "name": "implicit",
          "type": "bool"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "applyStiffnessLarge",
      "return_type": "void",
      "params": [
        {
          "name": "f",
          "type": "VecCoord &"
        },
        {
          "name": "h",
          "type": "Real"
        },
        {
          "name": "x",
          "type": "const VecCoord &"
        },
        {
          "name": "kFactor",
          "type": "const Real &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    },
    {
      "name": "computeElementStiffnessMatrix",
      "return_type": "void",
      "params": [
        {
          "name": "S",
          "type": "StiffnessMatrix &"
        },
        {
          "name": "SR",
          "type": "StiffnessMatrix &"
        },
        {
          "name": "K",
          "type": "const MaterialStiffness &"
        },
        {
          "name": "J",
          "type": "const StrainDisplacement &"
        },
        {
          "name": "Rot",
          "type": "const Transformation &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "protected"
    }
  ],
  "description": "The `TriangleFEMForceField` is a SOFA component used for simulating triangular finite elements with static topology in solid mechanics simulations. It inherits from `BaseLinearElasticityFEMForceField`, making it suitable for both small and large displacements, though the method for small displacements has not been validated fully and should be used carefully. The component handles linear elasticity through a QR decomposition of the deformation gradient to manage large deformations.\n\nThis component interacts with other SOFA components by providing force calculations via methods like `addForce` and `addDForce`, which are essential for integrating forces into mechanical models. Additionally, it supports stiffness matrix construction (`buildStiffnessMatrix`) and matrix-vector products (`applyStiffness`).\n\nThe `TriangleFEMForceField` has several key data fields:\n- `initialPoints`: Initial positions of the points in the domain.\n- `thickness`: Thickness of the triangular elements, used for material stiffness calculations.\n- `planeStrain`: A boolean flag to determine whether the plane strain or plane stress assumption is applied.\n\nIt also includes methods for initialization (`init` and `reinit`), visualization (`draw`), and computing element stiffness matrices (`computeElementStiffnessMatrix`). The component allows users to switch between small and large displacement methods using the `setMethod` function, which can accept values indicating 'small' or 'large' displacements.\n\nIn practical usage, users need to provide initial positions for points and specify thickness and plane strain assumptions. It is important to validate the simulation setup carefully if using the method for small displacements.",
  "maths": "The `TriangleFEMForceField` component in the SOFA framework is designed for simulating triangular finite elements with static topology, particularly useful for solid mechanics simulations. It supports both small and large displacements, although the method for small displacements has not been fully validated. The component leverages linear elasticity through a QR decomposition of the deformation gradient to handle large deformations effectively.\n\n### Governing Equations and Operators\n- **Mass Matrix ($M$)**: Not explicitly mentioned in the provided context; typically part of the general FEM formulation where $M\\ddot{u} + K(u)u = f_{ext}$, with $K(u)$ being the stiffness matrix.\n- **Stiffness Matrix ($K$)**: The component computes and assembles element-wise stiffness matrices. These matrices represent the linearized relationship between nodal displacements and internal forces.\n- **Internal Force ($f_{int}$)**: The component calculates the internal force through `addForce` method, which is a critical contribution to the global system of equations $M\\ddot{u} + f_{int}(x) = f_{ext}$.\n- **Residual ($R$)**: Not explicitly mentioned; typically derived from the nonlinear equation $R(x_{n+1}) = M\\frac{x_{n+1}-x_n}{Δt} - Δ t f_{int}(x_{n+1}) - Δ t f_{ext}$ during time integration.\n\n### Constitutive and Kinematic Laws\n- **Strain Measures**: The component calculates strain using the strain-displacement matrix $J$.\n- **Stress Tensors**: Stresses are computed from strains via Hooke's law, with material properties encapsulated in the stiffness matrix $K$.\n- **Hyperelastic Potentials**: Not applicable here as the component is based on linear elasticity models (Hookean).\n\n### Role in Global FEM Pipeline\n1. **Mesh Generation and Interpolation**:\n   - The initial positions (`initialPoints`) are used to define element geometry and nodal coordinates.\n2. **Spatial Discretization**:\n   - Elements are defined using triangular topology, with each triangle contributing to the global stiffness matrix $K$ through element-wise assembly (e.g., via `addKToMatrix` method).\n3. **Weak Formulation**:\n   - The variational formulation is implicit in the force calculations and stiffness matrix construction.\n4. **Assembly Phase**:\n   - Element-wise contributions to the global stiffness matrix are aggregated through methods like `buildStiffnessMatrix`.\n5. **Time Integration**:\n   - Implicit time integration schemes (e.g., Backward Euler) are supported, with internal forces and residuals computed in methods such as `addForce` and `addDForce`.\n6. **Nonlinear Resolution**:\n   - For large displacements, nonlinearities are handled through iterative Newton-Raphson steps or similar techniques.\n7. **Linear Resolution**:\n   - Matrix-vector products (`applyStiffness`) facilitate the linear solve phase in each iteration of the nonlinear solver.\n8. **Constraint Handling**: Not explicitly mentioned but likely supported via inherited methods from `BaseLinearElasticityFEMForceField`.\n\n### Numerical Methods and Discretization Choices\n- **Small Deformation Method**:\n  - Simplified linear elasticity formulation, where displacements are assumed small enough to neglect nonlinear terms. This method is experimental and not recommended for production use without careful validation.\n- **Large Deformation Method**:\n  - Uses QR decomposition of the deformation gradient to handle large deformations effectively, ensuring consistent strain measures and stress calculations.\n\n### Variational / Lagrangian Mechanics Framework\nThe `TriangleFEMForceField` component fits into the broader variational mechanics framework by:\n- **Variational Formulation**: Deriving internal forces from a weak form of the elasticity equations.\n- **Finite Element Method (FEM)**: Spatial discretization using triangular elements, with strains and stresses computed element-wise.\n- **Time Integration**: Implicit schemes for stability in dynamic simulations.\n\n### Constitutive Model\nMaterial properties such as Young's modulus ($E$) and Poisson's ratio ($ν$) are used to compute the material stiffness matrix $K$. For plane stress or strain assumptions, these matrices are adjusted accordingly.\n\nOverall, `TriangleFEMForceField` provides a robust framework for simulating triangular finite elements under both small and large deformations within the SOFA simulation environment.",
  "abstract": "The `TriangleFEMForceField` simulates triangular finite elements with static topology in solid mechanics, supporting both small and large displacements through linear elasticity models.",
  "sheet": "# TriangleFEMForceField\n\n## Overview\n\nThe `TriangleFEMForceField` is a component for simulating triangular finite elements within the SOFA framework. It supports both small and large displacements using linear elasticity models. The component inherits from `BaseLinearElasticityFEMForceField`, making it suitable for solid mechanics simulations.\n\n## Mathematical Model\n\nThe governing equations and operators in this component are based on linear elasticity:\n- **Mass Matrix ($M$)**: Typically part of the general FEM formulation where $M\\ddot{u} + K(u)u = f_{ext}$, with $K(u)$ being the stiffness matrix.\n- **Stiffness Matrix ($K$)**: The component computes and assembles element-wise stiffness matrices representing the linearized relationship between nodal displacements and internal forces.\n- **Internal Force ($f_{int}$)**: Calculated through the `addForce` method, contributing to the global system of equations $M\\ddot{u} + f_{int}(x) = f_{ext}$.\n\n## Parameters and Data\n\nThe significant data fields exposed by this component are:\n- **Initial Points (`initialPoints`)**: Initial positions of the points in the domain, represented as `VecCoord`.\n- **Thickness (`thickness`)**: Thickness of the triangular elements used for material stiffness calculations, represented as a `Real` value.\n- **Plane Strain (`planeStrain`)**: A boolean flag to determine whether the plane strain or plane stress assumption is applied.\n\n## Practical Notes\n\nThe method for small displacements has not been fully validated and should be used carefully. For large displacements, the component uses QR decomposition of the deformation gradient to handle nonlinearities effectively."
}