{
  "name": "InteractionEllipsoidForceField",
  "main": {
    "name": "InteractionEllipsoidForceField",
    "namespace": "sofa::component::mechanicalload",
    "module": "Sofa.Component.MechanicalLoad",
    "include": "sofa/component/mechanicalload/InteractionEllipsoidForceField.h",
    "doc": "Outward / inward repulsion applied by an ellipsoid geometry, which can possibly act on several objects.",
    "inherits": [
      "MixedInteractionForceField"
    ],
    "templates": [
      "sofa::defaulttype::Vec3Types, sofa::defaulttype::Rigid3Types"
    ],
    "data_fields": [
      {
        "name": "data",
        "type": "DataTypes1, DataTypes2"
      },
      {
        "name": "center",
        "type": "VecCoord1"
      },
      {
        "name": "vradius",
        "type": "VecCoord1"
      },
      {
        "name": "stiffness",
        "type": "Real1"
      },
      {
        "name": "damping",
        "type": "Real1"
      },
      {
        "name": "color",
        "type": "sofa::type::RGBAColor"
      },
      {
        "name": "bDraw",
        "type": "bool"
      },
      {
        "name": "object2_dof_index",
        "type": "int"
      },
      {
        "name": "object2_forces",
        "type": "bool"
      },
      {
        "name": "object2_invert",
        "type": "bool"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "calcF",
        "return_type": "bool",
        "params": [
          {
            "name": "p1",
            "type": "const Coord1 &"
          },
          {
            "name": "v1",
            "type": "const Deriv1 &"
          },
          {
            "name": "f1",
            "type": "Deriv1 &"
          },
          {
            "name": "dfdx",
            "type": "Mat &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "initCalcF",
        "return_type": "void",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "setStiffness",
        "return_type": "void",
        "params": [
          {
            "name": "stiff",
            "type": "Real1"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setDamping",
        "return_type": "void",
        "params": [
          {
            "name": "damp",
            "type": "Real1"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addForce",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const sofa::core::MechanicalParams *"
          },
          {
            "name": "f1",
            "type": "DataVecDeriv1 &"
          },
          {
            "name": "f2",
            "type": "DataVecDeriv2 &"
          },
          {
            "name": "x1",
            "type": "const DataVecCoord1 &"
          },
          {
            "name": "x2",
            "type": "const DataVecCoord2 &"
          },
          {
            "name": "v1",
            "type": "const DataVecDeriv1 &"
          },
          {
            "name": "v2",
            "type": "const DataVecDeriv2 &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addForce2",
        "return_type": "void",
        "params": [
          {
            "name": "f1",
            "type": "DataVecDeriv1 &"
          },
          {
            "name": "f2",
            "type": "DataVecDeriv2 &"
          },
          {
            "name": "p1",
            "type": "const DataVecCoord1 &"
          },
          {
            "name": "p2",
            "type": "const DataVecCoord2 &"
          },
          {
            "name": "v1",
            "type": "const DataVecDeriv1 &"
          },
          {
            "name": "v2",
            "type": "const DataVecDeriv2 &"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "addDForce",
        "return_type": "void",
        "params": [
          {
            "name": "mparams",
            "type": "const sofa::core::MechanicalParams *"
          },
          {
            "name": "df1",
            "type": "DataVecDeriv1 &"
          },
          {
            "name": "df2",
            "type": "DataVecDeriv2 &"
          },
          {
            "name": "dx1",
            "type": "const DataVecDeriv1 &"
          },
          {
            "name": "dx2",
            "type": "const DataVecDeriv2 &"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getPotentialEnergy",
        "return_type": "SReal",
        "params": [
          {
            "name": "mparams",
            "type": "const sofa::core::MechanicalParams *"
          },
          {
            "name": "x1",
            "type": "const DataVecCoord1 &"
          },
          {
            "name": "x2",
            "type": "const DataVecCoord2 &"
          }
        ],
        "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": "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": "draw",
        "return_type": "void",
        "params": [
          {
            "name": "vparams",
            "type": "const core::visual::VisualParams *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "name": "InteractionEllipsoidForceField",
    "description": "This component applies an outward or inward repulsion force based on an ellipsoidal geometry to interact with other objects in the simulation.",
    "parameters": [
      {
        "name": "color",
        "type": "Color",
        "description": "The color of the visual representation of the ellipsoid."
      },
      {
        "name": "draw",
        "type": "bool",
        "default_value": "false",
        "description": "Whether to draw the ellipsoid geometry in the visualization."
      },
      {
        "name": "object2-forces",
        "type": "bool",
        "default_value": "true",
        "description": "Whether to apply forces on the second object (object2) that interacts with the ellipsoid."
      },
      {
        "name": "rayleigh-stiffness",
        "type": "float",
        "default_value": "0.01",
        "description": "The Rayleigh damping coefficient used in the calculation of damping forces."
      },
      {
        "name": "stiffness",
        "type": "float",
        "default_value": "5000",
        "description": "Controls the strength of the repulsive force applied by the ellipsoid on interacting objects."
      }
    ],
    "input": [
      {
        "name": "geometry",
        "type": "Ellipsoid",
        "description": "The geometry of the interaction zone defined as an ellipsoid, which can be placed and oriented arbitrarily in space."
      },
      {
        "name": "object2-forces",
        "type": "MechanicalObject",
        "description": "The second object to apply forces on when it interacts with the ellipsoidal force field. The force is applied at the center of mass of this object."
      }
    ],
    "output": [
      {
        "name": "force-field",
        "type": "ForceField",
        "description": "Applies repulsive forces to interacting objects based on their position relative to the ellipsoid's surface."
      },
      {
        "name": "visualization",
        "type": "GeometryModel",
        "optional": true,
        "description": "Optional visual representation of the ellipsoidal force field in the scene."
      }
    ],
    "notes": [
      "This component is useful for simulating interactions where objects should be kept at a certain distance from each other or repelled by an obstacle with an ellipsoid shape.",
      "It can simulate effects such as collision avoidance, boundary conditions, or repulsive forces in simulations involving multiple interacting bodies."
    ]
  },
  "maths": {
    "maths": "\n### Governing Equations and Operators\n\nThe `InteractionEllipsoidForceField` component in the SOFA framework implements a force field that applies an outward or inward repulsion based on an ellipsoidal geometry to deformable objects. It contributes to the internal force vector $\\mathbf{f}_{int}$, which is part of the semi-discrete dynamical system equation:\n\n\begin{equation}\nM \\ddot{x}(t) + f_{int}(x(t)) = f_{ext}(t)\n\\end{equation}\n\nwhere $M$ is the mass matrix and $f_{ext}$ represents external forces.\n\nThe interaction force field computes the repulsive force at each point within or outside an ellipsoidal geometry. The repulsion force $\\mathbf{f}_i$ at a point $\\mathbf{p}_1$ relative to the ellipsoid center $\\mathbf{c}$ and semi-axes radii $\\mathbf{r} = (r_x, r_y, r_z)$ is given by:\n\n\begin{equation}\n\\mathbf{f}_i(\\mathbf{p}_1) = -k \\left(\\sqrt{\\frac{(\\mathbf{p}_1 - \\mathbf{c})_x^2}{r_x^2} + \\frac{(\\mathbf{p}_1 - \\mathbf{c})_y^2}{r_y^2} + \\frac{(\\mathbf{p}_1 - \\mathbf{c})_z^2}{r_z^2}} - 1\\right) \\left(\\frac{(\\mathbf{p}_1 - \\mathbf{c})_x}{r_x^2}, \\frac{(\\mathbf{p}_1 - \\mathbf{c})_y}{r_y^2}, \\frac{(\\mathbf{p}_1 - \\mathbf{c})_z}{r_z^2}\\right) / gnorm\n\\end{equation}\n\nwhere $k$ is the stiffness coefficient, and $gnorm$ normalizes the direction.\n\n### Constitutive or Kinematic Laws Involved\n\nThe force model does not rely on a traditional constitutive law but rather an explicit geometric constraint. The repulsive force depends on the distance from each point to the ellipsoid surface, which is defined by:\n\n\begin{equation}\ng(\\mathbf{p}_1) = \\sqrt{\\frac{(\\mathbf{p}_1 - \\mathbf{c})_x^2}{r_x^2} + \\frac{(\\mathbf{p}_1 - \\mathbf{c})_y^2}{r_y^2} + \\frac{(\\mathbf{p}_1 - \\mathbf{c})_z^2}{r_z^2}} - 1\n\\end{equation}\n\nThe force $\\mathbf{f}_i$ is then a function of this distance and the stiffness coefficient, with damping optionally applied to velocity:\n\n\begin{equation}\nf_{damping} = \\beta v_i\n\\end{equation}\n\nwhere $v_i$ is the velocity at point $i$, and $\\beta$ is the damping coefficient.\n\n### Role in the Global FEM Pipeline\n\n1. **Initialization**: The component initializes its internal variables, including ellipsoid center, radii, stiffness, and damping coefficients (`initCalcF` function).\n2. **Force Calculation**: It computes the repulsive forces for each point within or outside the ellipsoidal geometry relative to a reference frame defined by another object (`addForce`, `calcF` functions).\n3. **Constraint Handling**: The force is applied based on whether points lie inside or outside the ellipsoid, and the force direction depends on the sign of the stiffness coefficient.\n4. **Time Integration**: The calculated forces are part of the internal forces $f_{int}$ that enter the time integration scheme (`addForce`, `addDForce` functions).\n5. **Nonlinear Solve**: This component contributes to the nonlinear solve by providing a residual term through its force calculation (`R(x)` in the Newton-Raphson method).\n\n### Numerical Methods and Discretization Choices\n\nThe force field is computed at each node (point) of the deformed object, and the repulsion is based on an ellipsoid geometry. This geometric constraint ensures a nonlinear relationship between position and force.\n\n1. **Geometric Transformation**: Points are transformed into the local frame defined by another object (`vars.pos6D`) to ensure consistent relative positioning and orientation (`addForce` function).\n2. **Residual Calculation**: The residual $R(x)$ is computed based on the difference between actual positions and those predicted under the influence of the repulsive force, which feeds into the nonlinear solve process.\n3. **Matrix-Free Evaluation**: While not explicitly forming a stiffness matrix, the component computes necessary derivatives for Newton-Raphson iterations (`dfdx` matrix in `calcF`).\n\n### Fit within Variational / Lagrangian Mechanics Framework\n\nThe `InteractionEllipsoidForceField` can be seen as implementing a form of geometric constraint that influences the potential energy $U$ of the system. The repulsion force acts to minimize this potential, which is consistent with variational principles:\n\n\begin{equation}\n\\delta U = \\int_\\Omega \\mathbf{f}_{int} \\cdot \\delta \\mathbf{x}\\, d\\Omega = 0\n\\end{equation}\n\nThe repulsion forces are derived from the distance to the ellipsoid surface and ensure that points inside (or outside) an object adhere to or diverge from the geometric constraint, thus contributing to the overall energy minimization.\n"
  },
  "summary": {
    "abstract": "The `InteractionEllipsoidForceField` applies outward or inward repulsion forces based on an ellipsoidal geometry to interact with other objects in the simulation.",
    "sheet": "# InteractionEllipsoidForceField\n\n## Overview\nThe `InteractionEllipsoidForceField` is a mechanical load component that applies outward or inward repulsion forces based on an ellipsoidal geometry. It inherits from `MixedInteractionForceField`, enabling it to interact with multiple objects within the SOFA simulation.\n\n## Mathematical Model\nThe interaction force field computes the repulsive force at each point relative to the ellipsoid center and semi-axes radii. The repulsion force $\\mathbf{f}_i$ at a point $\\mathbf{p}_1$ is given by:\n\n\begin{equation}\n\\mathbf{f}_i(\\mathbf{p}_1) = -k \\left(\\sqrt{\\frac{(\\mathbf{p}_1 - \\mathbf{c})_x^2}{r_x^2} + \\frac{(\\mathbf{p}_1 - \\mathbf{c})_y^2}{r_y^2} + \\frac{(\\mathbf{p}_1 - \\mathbf{c})_z^2}{r_z^2}} - 1\\right) \\left(\\frac{(\\mathbf{p}_1 - \\mathbf{c})_x}{r_x^2}, \\frac{(\\mathbf{p}_1 - \\mathbf{c})_y}{r_y^2}, \\frac{(\\mathbf{p}_1 - \\mathbf{c})_z}{r_z^2}\\right) / gnorm\n\\end{equation}\n\nwhere $k$ is the stiffness coefficient, and $gnorm$ normalizes the direction. The force model also includes damping:\n\n\begin{equation}\nf_{damping} = \\beta v_i\n\\end{equation}\n\nwhere $v_i$ is the velocity at point $i$, and $\\beta$ is the damping coefficient.\n\n## Parameters and Data\nThe significant data fields exposed by this component include:\n- `center`: The center of the ellipsoid geometry (type: VecCoord1).\n- `vradius`: The semi-axes radii of the ellipsoid (type: VecCoord1).\n- `stiffness`: The stiffness coefficient for repulsion forces (type: Real1).\n- `damping`: The damping coefficient for velocity-based forces (type: Real1).\n- `color`: The color used for visualization (type: sofa::type::RGBAColor).\n- `bDraw`: A boolean flag to enable or disable drawing the ellipsoid geometry (type: bool).\n\n## Dependencies and Connections\nThis component typically requires other mechanical objects to interact with, such as deformable bodies. It fits into the scene graph by connecting to these objects through its geometric constraints.\n\n## Practical Notes\nThe stiffness and damping parameters should be carefully tuned for numerical stability. The visualization settings (`color` and `bDraw`) can help in debugging and visualizing the ellipsoid geometry."
  }
}