{
  "name": "BaseLinearElasticityFEMForceField",
  "main": {
    "name": "BaseLinearElasticityFEMForceField",
    "namespace": "sofa::component::solidmechanics::fem::elastic",
    "module": "Sofa.Component.SolidMechanics.FEM.Elastic",
    "include": "sofa/component/solidmechanics/fem/elastic/BaseLinearElasticityFEMForceField.h",
    "doc": "",
    "inherits": [
      "ForceField"
    ],
    "templates": [
      "sofa::defaulttype::Rigid3Types",
      "sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [
      {
        "name": "d_poissonRatio",
        "type": "VecReal",
        "xmlname": "poissonRatio",
        "help": "FEM Poisson Ratio in Hooke's law [0,0.5["
      },
      {
        "name": "d_youngModulus",
        "type": "VecReal",
        "xmlname": "youngModulus",
        "help": "FEM Young's Modulus in Hooke's law"
      }
    ],
    "links": [
      {
        "name": "l_topology",
        "target": "BaseMeshTopology",
        "kind": "single",
        "xmlname": "topology",
        "help": "link to the topology container"
      }
    ],
    "methods": [
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setPoissonRatio",
        "return_type": "void",
        "params": [
          {
            "name": "val",
            "type": "Real"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setYoungModulus",
        "return_type": "void",
        "params": [
          {
            "name": "val",
            "type": "Real"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getYoungModulusInElement",
        "return_type": "Real",
        "params": [
          {
            "name": "elementId",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getPoissonRatioInElement",
        "return_type": "Real",
        "params": [
          {
            "name": "elementId",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "toLameParameters",
        "return_type": "std::pair<Real, Real>",
        "params": [
          {
            "name": "",
            "type": "_2DMaterials"
          },
          {
            "name": "youngModulus",
            "type": "Real"
          },
          {
            "name": "poissonRatio",
            "type": "Real"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": true,
        "access": "public"
      },
      {
        "name": "toLameParameters",
        "return_type": "std::pair<Real, Real>",
        "params": [
          {
            "name": "",
            "type": "_3DMaterials"
          },
          {
            "name": "youngModulus",
            "type": "Real"
          },
          {
            "name": "poissonRatio",
            "type": "Real"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": true,
        "access": "public"
      },
      {
        "name": "checkPoissonRatio",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "checkYoungModulus",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "getVecRealInElement",
        "return_type": "Real",
        "params": [
          {
            "name": "elementId",
            "type": "int"
          },
          {
            "name": "data",
            "type": "const Data<VecReal> &"
          },
          {
            "name": "defaultValue",
            "type": "Real"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "component": {
      "name": "BaseLinearElasticityFEMForceField",
      "description": "The BaseLinearElasticityFEMForceField is an abstract class in the SOFA (Simulation Open-Framework Architecture) framework, designed to model linear elastic behavior of objects using finite element methods. This component provides the fundamental implementation for setting and validating material properties such as Young's modulus and Poisson’s ratio.",
      "parameters": [
        {
          "name": "poissonRatio",
          "type": "vector<real>",
          "description": "Poisson's ratio, a dimensionless number that measures how much a material expands laterally when stretched or contracts laterally when compressed. It must be within the range [0, 0.5). The component enforces this constraint and corrects any out-of-bound values to its default.",
          "default": "[0.3]"
        },
        {
          "name": "youngModulus",
          "type": "vector<real>",
          "description": "Young's modulus (also known as the elastic modulus), a measure of the stiffness of an elastic material, defined as the ratio of stress to strain. This value must be positive and the component ensures this constraint by correcting any negative values to its default.",
          "default": "[20]"
        },
        {
          "name": "topology",
          "type": "BaseMeshTopology",
          "description": "Link to the topology container which defines the mesh of the object. It specifies how the nodes and elements are connected. This is required for the force field calculation."
        }
      ],
      "methods": [
        {
          "name": "init",
          "description": "Initializes the component, including checking if a valid BaseMeshTopology is linked to it. If no topology link exists, it attempts to find one in the current context and sets it up.",
          "returnType": "void"
        },
        {
          "name": "checkPoissonRatio",
          "description": "Validates the Poisson's ratio values provided in 'poissonRatio'. It ensures that all values are within [0, 0.5). If a value is out of this range, it issues a warning and sets the value to its default.",
          "returnType": "void"
        },
        {
          "name": "checkYoungModulus",
          "description": "Validates the Young's modulus values provided in 'youngModulus'. It ensures that all values are positive. If a negative value is found, it issues a warning and sets the value to its default.",
          "returnType": "void"
        },
        {
          "name": "getVecRealInElement",
          "description": "Retrieves the real number (e.g., Young's modulus or Poisson’s ratio) for a specific element. If the provided Data field is smaller than the requested index, it returns either the first value in the array or a default value.",
          "returnType": "real"
        },
        {
          "name": "getYoungModulusInElement",
          "description": "Retrieves the Young's modulus for a specific element using 'getVecRealInElement'. It ensures that the value retrieved is valid for calculations involving elastic properties.",
          "returnType": "real"
        },
        {
          "name": "getPoissonRatioInElement",
          "description": "Retrieves the Poisson's ratio for a specific element using 'getVecRealInElement'. It ensures that the value retrieved is valid for calculations involving elastic properties.",
          "returnType": "real"
        },
        {
          "name": "toLameParameters",
          "description": "Converts Young’s modulus and Poisson's ratio to Lamé parameters (lambda and mu). This method supports two types of material (_2DMaterial and _3DMaterial) which use different formulas for conversion.",
          "returnType": "pair<real, real>"
        }
      ],
      "usageExample": "BaseLinearElasticityFEMForceField is used as a foundation for more specific implementations that model the elastic behavior of objects with defined topology. It ensures that material properties are correctly set up and within physically reasonable values to simulate realistic behaviors."
    }
  },
  "maths": {
    "maths": "The **BaseLinearElasticityFEMForceField** component in the SOFA (Simulation Open Framework Architecture) framework models linear elastic behavior using finite element methods. This model is fundamental in solid mechanics and simulates how materials deform under external forces while assuming they return to their original shape once these forces are removed.\n\n### Mathematical Formulation\n\n1. **Hooke's Law**:\n   The core principle of the linear elasticity model is Hooke’s Law, which states that stress (\\( \\sigma \\)) is directly proportional to strain (\\( \\epsilon \\)) within a certain range. Mathematically, this can be expressed as:\n   \n   \\[ \\sigma = E \\cdot \\epsilon \\]\n   where \\(E\\) is the Young's modulus of elasticity.\n\n2. **Stress-Strain Relations**:\n   For 3D linear isotropic materials, the stress-strain relationship can be written in terms of Lamé parameters (λ and μ), which are derived from Young's Modulus (E) and Poisson’s ratio (ν):\n   \n   \\[ \\lambda = \\frac{E\\nu}{(1 + \\nu)(1 - 2\\nu)} \\]\n   \n   \\[ \\mu = \\frac{E}{2(1+\\nu)} \\]\n\n   For 2D materials, the Lamé parameters are slightly different:\n   \n   \\[ \\lambda_{2D} = \\frac{E\\nu}{(1 - \\nu^2)} \\]\n   \n   \\[ \\mu_{2D} = \\frac{E}{2(1+\\nu)} \\]\n\n3. **Stress Tensor**:\n   The stress tensor (\\(\\sigma\\)) can be expressed in terms of Lamé parameters and the strain tensor (\\(\\epsilon\\)). In 3D, the relation is given by:\n   \n   \\[ \\sigma_{ij} = \\lambda \\cdot tr(\\epsilon) \\delta_{ij} + 2 \\mu \\cdot \\epsilon_{ij} \\]\n\n4. **Finite Element Formulation**:\n   In the context of finite element analysis, this stress-strain relationship is used to derive the stiffness matrix (\\(K\\)) for each element in the mesh. The stiffness matrix relates nodal forces (\\(F\\)) and displacements (\\(u\\)) through:\n   \n   \\[ K = \\int_{V} B^T D B \\, dV \\]\n\n   where \\(B\\) is the strain-displacement matrix, \\(D\\) is the elasticity tensor, and the integration is performed over the volume of the element.\n\n### Physical Interpretation\n\n1. **Young's Modulus (E)**:\n   Young’s modulus quantifies a material’s resistance to elastic deformation under uniaxial tensile or compressive stress. Higher values indicate stiffer materials that resist deformation more strongly.\n\n2. **Poisson's Ratio (ν)**:\n   Poisson’s ratio characterizes the transverse contraction strain relative to axial extension strain in the direction of stretching force for linear elastic materials. For example, if a material stretches along one axis, it contracts along the perpendicular axes.\n\n3. **Lamé Parameters**:\n   Lamé parameters (λ and μ) are used to express the stress-strain relationship in terms of tensors, allowing the model to handle complex deformations in 2D and 3D space efficiently.\n\n### Usage in SOFA Component\nThe BaseLinearElasticityFEMForceField component uses these principles to simulate linear elastic behavior within a finite element framework. The parameters Young's modulus (E) and Poisson’s ratio (ν) are set by the user, and the system calculates the stress-strain relations accordingly.\n\n- **Initialization**: During initialization, the component checks that both `youngModulus` and `poissonRatio` data fields are provided and valid. If not, it uses default values to ensure numerical stability.\n\n- **Force Computation**: The force field computes the internal forces due to elastic deformation based on the current displacements of nodes in the topology. This involves computing strains from nodal displacements, calculating stresses using Hooke’s Law and Lamé parameters, and integrating these over the element volumes to obtain the total forces.\n\n- **Integration with Topology**: The component requires a valid `BaseMeshTopology` object to define the geometry and connectivity of the elements. It ensures that any required topology information is available for accurate force calculations."
  },
  "summary": {
    "abstract": "The BaseLinearElasticityFEMForceField simulates linear elastic behavior using finite element methods, requiring Young's modulus and Poisson's ratio to define material properties.",
    "sheet": "# BaseLinearElasticityFEMForceField\n\n## Overview\nThe `BaseLinearElasticityFEMForceField` component in the SOFA framework models linear elastic behavior using finite element methods. It requires parameters such as Young’s modulus (E) and Poisson's ratio (ν) to define material properties.\n\n## Mathematical Model\nThe core principle of the linear elasticity model is Hooke’s Law, which states that stress (\\( \\sigma \\\")) is directly proportional to strain (\\( \\epsilon \\\")). Mathematically, this can be expressed as:\n\n\begin{equation}\n  \\sigma = E \\cdot \\epsilon\n\tag{1}\\end{equation}\n\nFor 3D linear isotropic materials, the stress-strain relationship in terms of Lamé parameters (λ and μ) is given by:\n\n\begin{align*}\n  \\lambda &= \\frac{E\\nu}{(1 + \\nu)(1 - 2\\nu)} \\\\\n  \\mu &= \\frac{E}{2(1+\\nu)}\n\tag{2}\\end{align*}\n\nFor 2D materials, the Lamé parameters are slightly different:\n\n\begin{align*}\n  \\lambda_{2D} &= \\frac{E\\nu}{(1 - \\nu^2)} \\\\\n  \\mu_{2D} &= \\frac{E}{2(1+\\nu)}\n\tag{3}\\end{align*}\n\nThe stress tensor (\\( \\sigma \\\\)) can be expressed in terms of Lamé parameters and the strain tensor (\\( \\epsilon \\\\)). In 3D, this relation is given by:\n\n\begin{equation}\n  \\sigma_{ij} = \\lambda \\cdot tr(\\epsilon) \\delta_{ij} + 2 \\mu \\cdot \\epsilon_{ij}\n\tag{4}\\end{equation}\n\nIn the context of finite element analysis, this stress-strain relationship is used to derive the stiffness matrix (\\( K \\\\)) for each element in the mesh. The stiffness matrix relates nodal forces (\\( F \\\")) and displacements (\\( u \\\")) through:\n\n\begin{equation}\n  K = \\int_{V} B^T D B \\, dV\n\tag{5}\\end{equation}\n\nwhere (\\( B \\\\)) is the strain-displacement matrix, (\\( D \\\\)) is the elasticity tensor, and the integration is performed over the volume of the element.\n\n## Parameters and Data\nThe significant data fields exposed by this component are:\n- **poissonRatio**: FEM Poisson Ratio in Hooke’s law [0, 0.5[\n- **youngModulus**: FEM Young's Modulus in Hooke’s law\n\nThese parameters control the material properties used to compute elastic forces.\n\n## Dependencies and Connections\nThe component requires a valid `BaseMeshTopology` object to define the geometry and connectivity of the elements, ensuring accurate force calculations."
  }
}