{
  "name": "BeamFEMForceField",
  "main": {
    "name": "BeamFEMForceField",
    "namespace": "sofa::component::solidmechanics::fem::elastic::_beamfemforcefield_",
    "module": "Sofa.Component.SolidMechanics.FEM.Elastic",
    "include": "sofa/component/solidmechanics/fem/elastic/BeamFEMForceField.h",
    "doc": "Beam finite elements.\n\nCompute Finite Element forces based on 6D beam elements.",
    "inherits": [
      "BaseLinearElasticityFEMForceField"
    ],
    "templates": [
      "sofa::defaulttype::Rigid3Types"
    ],
    "data_fields": [
      {
        "name": "d_radius",
        "type": "Real",
        "xmlname": "radius",
        "help": "radius of the section"
      },
      {
        "name": "d_radiusInner",
        "type": "Real",
        "xmlname": "radiusInner",
        "help": "inner radius of the section for hollow beams"
      },
      {
        "name": "d_listSegment",
        "type": "BaseMeshTopology::SetIndex",
        "xmlname": "listSegment",
        "help": "apply the forcefield to a subset list of beam segments. If no segment defined, forcefield applies to the whole topology"
      },
      {
        "name": "d_useSymmetricAssembly",
        "type": "bool",
        "xmlname": "useSymmetricAssembly",
        "help": "use symmetric assembly of the matrix K"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "createBeamInfo",
        "return_type": "void",
        "params": [
          {
            "name": "edgeIndex",
            "type": "int"
          },
          {
            "name": "",
            "type": "BeamInfo &"
          },
          {
            "name": "e",
            "type": "const BaseMeshTopology::Edge &"
          },
          {
            "name": "",
            "type": "const int &"
          },
          {
            "name": "",
            "type": "const int &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "beamQuat",
        "return_type": "Quat<SReal> &",
        "params": [
          {
            "name": "i",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "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": "reinitBeam",
        "return_type": "void",
        "params": [
          {
            "name": "i",
            "type": "int"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addForce",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const 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": "mparams",
            "type": "const MechanicalParams *"
          },
          {
            "name": "datadF",
            "type": "DataVecDeriv &"
          },
          {
            "name": "datadX",
            "type": "const DataVecDeriv &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addKToMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "matrix",
            "type": "sofa::linearalgebra::BaseMatrix *"
          },
          {
            "name": "kFact",
            "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": "mparams",
            "type": "const MechanicalParams *"
          },
          {
            "name": "x",
            "type": "const DataVecCoord &"
          }
        ],
        "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": "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": "setUpdateStiffnessMatrix",
        "return_type": "void",
        "params": [
          {
            "name": "val",
            "type": "bool"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setBeam",
        "return_type": "void",
        "params": [
          {
            "name": "i",
            "type": "int"
          },
          {
            "name": "E",
            "type": "SReal"
          },
          {
            "name": "L",
            "type": "SReal"
          },
          {
            "name": "nu",
            "type": "SReal"
          },
          {
            "name": "r",
            "type": "SReal"
          },
          {
            "name": "rInner",
            "type": "SReal"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "initBeams",
        "return_type": "void",
        "params": [
          {
            "name": "size",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "drawElement",
        "return_type": "void",
        "params": [
          {
            "name": "i",
            "type": "int"
          },
          {
            "name": "points",
            "type": "int *"
          },
          {
            "name": "x",
            "type": "const VecCoord &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "pseudoDeterminantForCoef",
        "return_type": "Real",
        "params": [
          {
            "name": "M",
            "type": "const Mat<2, 3, Real> &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "computeStiffness",
        "return_type": "void",
        "params": [
          {
            "name": "i",
            "type": "int"
          },
          {
            "name": "a",
            "type": "int"
          },
          {
            "name": "b",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "initLarge",
        "return_type": "void",
        "params": [
          {
            "name": "i",
            "type": "int"
          },
          {
            "name": "a",
            "type": "int"
          },
          {
            "name": "b",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "accumulateForceLarge",
        "return_type": "void",
        "params": [
          {
            "name": "f",
            "type": "VecDeriv &"
          },
          {
            "name": "x",
            "type": "const VecCoord &"
          },
          {
            "name": "i",
            "type": "int"
          },
          {
            "name": "a",
            "type": "int"
          },
          {
            "name": "b",
            "type": "int"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "applyStiffnessLarge",
        "return_type": "void",
        "params": [
          {
            "name": "f",
            "type": "VecDeriv &"
          },
          {
            "name": "x",
            "type": "const VecDeriv &"
          },
          {
            "name": "i",
            "type": "int"
          },
          {
            "name": "a",
            "type": "int"
          },
          {
            "name": "b",
            "type": "int"
          },
          {
            "name": "fact",
            "type": "SReal"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "_return": "This is the documentation for the `BeamFEMForceField` component in SOFA (Simulation Open Framework Architecture), which is used to simulate elastic beams using Finite Element Method (FEM). Below, I'll provide a detailed description of its features and functionalities based on the given code snippet and typical behavior of such components in SOFA physics engine.\n\n### Overview:\nThe `BeamFEMForceField` component simulates elastic beams by solving the beam bending problem using FEM. It applies forces to nodes to simulate the physical behavior of a beam, including stiffness and possibly damping. The force field can be used in simulations involving solid mechanics where beams are expected to deform realistically under applied loads or external forces.\n\n### Key Features:\n- **Beam Properties**: Each beam element defined by this component has properties such as Young's modulus (E), length (L), Poisson's ratio (nu), outer radius (r), and inner radius (if the beam is hollow). These properties determine how the beam will deform under forces.\n- **FEM Simulation**: The force field computes the internal forces within each element using FEM principles, which account for both bending and torsional stiffness.\n- **Update Mechanism**: During simulation, it updates the positions of nodes based on the computed forces to simulate deformation realistically. It also supports updating the stiffness matrix if required for more accurate simulations.\n- **Visualization**: The component can draw beams in a visual scene using different colors for x-axis and y-axis cross-sections of the beam elements, which helps in understanding the simulated behavior visually.\n\n### Implementation Details:\n- **Initialization**: When initializing or resizing the set of beams, the `initBeams` function is called. This prepares the internal data structures to hold information about each beam element.\n- **Force Computation**: The main computation happens within the `addForce` method where the force contributions from each beam element are calculated and added to the global forces acting on nodes.\n- **Potential Energy Calculation**: Although not fully implemented in the provided code, there is a placeholder for calculating potential energy based on the deformed state of beams. This feature can be useful for certain physics engines or simulations.\n- **Drawing Functionality**: The component supports drawing beam elements for visualization purposes using different colors for different cross-section axes (x and y). It uses SOFA's visual tools to draw lines representing beam elements in 3D space.\n\n### Customization:\nThe user can customize various properties of the beams, such as material parameters (`E`, `nu`), geometric dimensions (`L`, `r`), and whether or not to update the stiffness matrix during simulation. These settings allow for a wide range of applications, from simulating simple springs to more complex beam structures.\n\n### Use Cases:\nThe `BeamFEMForceField` is suitable for simulations involving mechanical structures where beams play a significant role, such as in civil engineering (bridges, buildings), biomechanics (bones and ligaments), or robotics (manipulator arms). It allows researchers and engineers to test the behavior of beam-based structures under various loading conditions without physical prototypes."
  },
  "maths": {
    "maths": "## Beam Finite Element Method (FEM) Force Field\n\n### Overview\nThe `BeamFEMForceField` is a computational mechanics model used to simulate the behavior of beams under various loading conditions. The beam is discretized into finite elements, and each element's deformation is calculated based on the principles of linear elasticity.\n\n### Beam Properties\n- **Young’s Modulus (E):** Measures the stiffness of the material.\n- **Length (L):** Length of the beam segment.\n- **Poisson’s Ratio (ν):** Ratio of transverse contraction strain to lateral or axial strain. It describes how much a material expands along its length when squeezed, and conversely contracts when stretched.\n- **Radius (r) & Inner Radius (rInner):** Geometrical parameters defining the cross-sectional area of the beam. The radius `r` represents the outer radius of the cross-section, while `rInner` is the inner radius for hollow beams.\n\n### Elastic Constants Calculation\nGiven Young’s modulus (`E`) and Poisson's ratio (`ν`), other elastic constants can be derived:\n- **Shear Modulus (G):** \\\\[ G = \\frac{E}{2(1 + ν)} \\\\]\n- **Second Moment of Area (I_z, I_y):** These are geometric properties that describe the cross-section's resistance to bending. For a solid circular cross-section: \\\\[ I_z = I_y = \\frac{\\pi r^4}{4} - \\frac{π r_{inner}^4}{4} \\\\]\n- **Polar Moment of Inertia (J):** Represents the beam’s resistance to torsion. For a solid circular cross-section: \\\\[ J = I_z + I_y \\\\]\n- **Cross-sectional Area (A):** \\\\[ A = \\pi r^2 - π r_{inner}^2 \\\\]\n\n### Stiffness Matrix Calculation\nThe stiffness matrix for each beam element is derived from the material properties and geometric parameters. For a 1D beam element, the global stiffness matrix `K` can be expressed as:\n- The local stiffness matrix for axial deformation (in x-direction) is based on the Young’s modulus (`E`) and cross-sectional area (`A`).\n- Bending moments in the y and z directions are modeled using flexural rigidity (`EI_z` and `EI_y`).\n- Torsional rigidity depends on the polar moment of inertia (`J`) and shear modulus (`G`).\n\n### Non-linear Material Behavior (Optional)\nThe model can be extended to accommodate non-linear material behavior, such as plastic deformation. In this case, a hardening function is used to update the Young’s modulus `E` based on the previous stress state.\n- The function takes into account the previous stress magnitude (`σ`) and updates the stiffness accordingly: \\\\[ E = \\frac{1}{\\left| σ_{prev} \\right| + 0.25E_0^{-1}} \\\\]\n\n### Displacement Calculation\nThe beam deformation is calculated using finite element methods, where nodal displacements are computed based on applied forces and boundary conditions. The displacements for each node of the beam element are then used to calculate internal stresses.\n\n### Visualization & Debugging\n- **Draw Method:** This function visualizes the beam elements along with their local coordinate system axes (X, Y, Z) which helps in debugging and visualization purposes.\n- **Bounding Box Computation:** The bounding box is computed by including all the node positions to define the spatial extent of the beam structure.\n\n### Stiffness Matrix Update Mechanism\nThe stiffness matrix is updated based on changes in the beam’s configuration, material properties, or applied forces. This mechanism ensures that the system accurately reflects any deformation or loading scenarios.\n"
  },
  "summary": {
    "abstract": "The `BeamFEMForceField` computes finite element forces for beam elements based on linear elasticity principles, handling both solid and hollow beams with customizable radii and segment-specific application.",
    "sheet": "# BeamFEMForceField\n\n## Overview\nThe `BeamFEMForceField` is a computational mechanics model used to simulate the behavior of beams under various loading conditions. It computes finite element forces for beam elements based on linear elasticity principles, handling both solid and hollow beams with customizable radii and segment-specific application.\n\n## Mathematical Model\nGiven Young’s modulus (\\(E\\)), Poisson's ratio (\\(\nu\\)), radius (\\(r\\)), and inner radius (\\(r_{inner}\\)) for hollow beams, the elastic constants are calculated as follows:\n- **Shear Modulus (G):** \\[ G = \\frac{E}{2(1 + \nu)} \\]\n- **Second Moment of Area (I_z, I_y):** For a solid circular cross-section: \\[ I_z = I_y = \\frac{π r^4}{4} - \\frac{π r_{inner}^4}{4} \\]\n- **Polar Moment of Inertia (J):** \\[ J = I_z + I_y \\]\n- **Cross-sectional Area (A):** \\[ A = π r^2 - π r_{inner}^2 \\]\n\nThe stiffness matrix for each beam element is derived from the material properties and geometric parameters. For a 1D beam element, the global stiffness matrix \\(K\\) can be expressed as:\n- The local stiffness matrix for axial deformation (in x-direction) is based on Young’s modulus (\\(E\\)) and cross-sectional area (\\(A\\)).\n- Bending moments in the y and z directions are modeled using flexural rigidity (\\(EI_z\\) and \\(EI_y\\)).\n- Torsional rigidity depends on the polar moment of inertia (\\(J\\)) and shear modulus (\\(G\\)).\n\n## Parameters and Data\nThe significant data fields exposed by `BeamFEMForceField` are:\n- **radius:** Radius of the section (`Real`, default: not specified).\n- **radiusInner:** Inner radius of the section for hollow beams (`Real`, default: not specified).\n- **listSegment:** Apply the force field to a subset list of beam segments. If no segment is defined, the force field applies to the whole topology (`BaseMeshTopology::SetIndex`, default: not specified).\n- **useSymmetricAssembly:** Use symmetric assembly of the matrix \\(K\\) (`bool`, default: not specified)."
  }
}