{
  "name": "EllipsoidForceField",
  "main": {
    "name": "EllipsoidForceField",
    "namespace": "sofa::component::mechanicalload",
    "module": "Sofa.Component.MechanicalLoad",
    "include": "sofa/component/mechanicalload/EllipsoidForceField.h",
    "doc": "Outward / inward repulsion applied by an ellipsoid geometry.",
    "inherits": [
      "ForceField"
    ],
    "templates": [
      "sofa::defaulttype::Vec3Types"
    ],
    "data_fields": [
      {
        "name": "data",
        "type": "DataTypes"
      },
      {
        "name": "d_center",
        "type": "Coord",
        "xmlname": "center",
        "help": "ellipsoid center"
      },
      {
        "name": "d_vradius",
        "type": "Coord",
        "xmlname": "vradius",
        "help": "ellipsoid radius"
      },
      {
        "name": "d_stiffness",
        "type": "Real",
        "xmlname": "stiffness",
        "help": "force stiffness (positive to repulse outward, negative inward)"
      },
      {
        "name": "d_damping",
        "type": "Real",
        "xmlname": "damping",
        "help": "force damping"
      },
      {
        "name": "d_color",
        "type": "sofa::type::RGBAColor",
        "xmlname": "color",
        "help": "ellipsoid color. (default=0,0.5,1.0,1.0)"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "setStiffness",
        "return_type": "void",
        "params": [
          {
            "name": "stiff",
            "type": "Real"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "setDamping",
        "return_type": "void",
        "params": [
          {
            "name": "damp",
            "type": "Real"
          }
        ],
        "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": "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": "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": {
    "description": "The Ellipsoid Force Field is a force field component in the Sofa framework that applies outward or inward repulsion forces based on an ellipsoid geometry.",
    "parameters": [
      {
        "name": "center",
        "type": "Coord",
        "description": "Specifies the center of the ellipsoid."
      },
      {
        "name": "vradius",
        "type": "Coord",
        "description": "Defines the radii along each axis of the ellipsoid."
      },
      {
        "name": "stiffness",
        "type": "Real",
        "description": "Controls the force stiffness, determining how strongly objects are repelled from or attracted to the ellipsoid surface. Positive values cause outward repulsion while negative values induce inward attraction."
      },
      {
        "name": "damping",
        "type": "Real",
        "description": "Applies damping to velocity along the ellipsoid normal direction, reducing movement perpendicular to the ellipsoid surface."
      },
      {
        "name": "color",
        "type": "RGBAColor",
        "description": "Sets the color used for visualizing the ellipsoid geometry in the scene."
      }
    ],
    "methods": [
      {
        "name": "setStiffness",
        "parameters": [
          {
            "name": "stiff",
            "type": "Real"
          }
        ],
        "returns": null,
        "description": "Sets the stiffness value for the force field."
      },
      {
        "name": "setDamping",
        "parameters": [
          {
            "name": "damp",
            "type": "Real"
          }
        ],
        "returns": null,
        "description": "Configures the damping amount applied to velocities."
      }
    ],
    "functionality": "This component implements an ellipsoidal force field that repels or attracts objects based on their proximity to the ellipsoid surface. It calculates forces for each object point relative to the ellipsoid geometry defined by its center position and axis radii. The stiffness parameter controls the strength of this interaction, applying outward forces when positive or inward forces when negative. Damping can be applied to reduce motion perpendicular to the ellipsoid surface. This allows creating containment volumes or attracting objects to a specific shape.",
    "usage": "The Ellipsoid Force Field is useful for creating physical boundaries, containment regions, or attractors in simulations with an ellipsoidal geometry. It can be used to keep objects within a certain volume or direct their motion toward a particular form."
  },
  "maths": {
    "maths": "# Mathematical Description of the Ellipsoid Force Field\n\nThe **Ellipsoid Force Field** in the Sofa framework applies forces to particles based on their distance from an ellipsoidal surface. The force can be directed either outward or inward depending on the sign of the stiffness parameter. Here are the mathematical and physical details of this component:\n\n## Definitions\n\n- **Center of Ellipsoid**: \\(\\mathbf{c} = (c_x, c_y, c_z)\\)\n- **Radii of Ellipsoid**: \\(\\mathbf{r} = (r_x, r_y, r_z)\\)\n- **Position of Particle**: \\(\\mathbf{p}_i = (x_i, y_i, z_i)\\)\n- **Displacement from Center**: \\(\\mathbf{d}_i = \\mathbf{p}_i - \\mathbf{c}\\)\n- **Stiffness Parameter**: \\(k\\)\n- **Damping Coefficient**: \\(d\\)\n\n## Distance and Normalization\n\n1. **Distance from Center**: \n   The displacement vector \\(\\mathbf{d}_i\\) is given by:\n   \\[\\mathbf{d}_i = (x_i - c_x, y_i - c_y, z_i - c_z)\\]\n2. **Normalized Distance**:\n   To normalize the distance to an ellipsoidal surface, we use:\n   \\[\\text{norm}^2 = \\sum_{j=0}^{N-1}\\left(\\frac{(d_i)_j}{r_j}\\right)^2\\]\n   where \\((d_i)_j\\) is the j-th component of \\(\\mathbf{d}_i\\), and \\(N\\) is the dimensionality (e.g., 3 for a 3D ellipsoid).\n\n## Force Calculation\n\nThe force \\(\\mathbf{F}(p_i)\\) applied to particle \\(i\\) at position \\(\\mathbf{p}_i\\) depends on whether it lies inside or outside the ellipsoid:\n1. **Inside Ellipsoid**: \n   If \\((\\text{norm}^2 - 1)k < 0\\), the point is considered inside and a repulsive force will be applied.\n   The distance to the surface, normalized by stiffness \\(k\\) and its absolute value, is:\n   \\[v = \\sqrt{\\text{norm}^2} - 1\\]\n\n   **Gradient Calculation**: \n   \\[\\mathbf{grad}_i = \\frac{d_i}{r_j}\\]\n   where each component of the gradient vector \\(\\mathbf{grad}_i\\) is normalized by its respective radius.\n\n   The norm of this gradient is:\n   \\[g_{norm}^2 = ||\\mathbf{grad}_i||^2\\]\n   \\[g_{norm} = \\sqrt{g_{norm}^2}\\]\n\n   **Force Intensity**:\n   The force intensity due to stiffness and damping is given by:\n   \\[F_{intensity} = -|k|v / g_{norm}\\]\n   \\[\\text{Damping Intensity} = d |v|\\]\n\n2. **Total Force**:\n   Combining these components, the total force applied to particle \\(i\\) is:\n   \\[\\mathbf{F}_i = \\frac{-k}{g_{norm}} (\\sqrt{\\text{norm}^2}-1)\\frac{d_i}{r_j} - d v \\mathbf{v}_i\\]\n\n## Matrix Representation\n\nThe force gradient matrix \\(\\mathbf{M}\\) for each particle contact is used to calculate the derivative of forces with respect to displacements. This matrix is given by:\n\n1. **Diagonal Elements** (assuming isotropic behavior for simplicity):\n   \\[m_{ii} = -|k| \\left(\\frac{(d_i)_i}{r_i g_{norm}} + v \\frac{1}{g_{norm}^2}\\right)\\]\n\n2. **Off-Diagonal Elements** (cross-terms due to gradient interactions):\n   \\[m_{ij} = -|k| \\left(\\frac{(d_i)_i (d_i)_j}{r_j g_{norm}} + v \\frac{1}{g_{norm}^2}\\right) \\quad \\text{for } i \neq j\\]\n\n## Potential Energy\n\nThe potential energy associated with the Ellipsoid Force Field is not explicitly defined in this component but can be derived from the force function if needed. The general form would involve integrating the force over displacements.\n"
  },
  "summary": {
    "abstract": "The EllipsoidForceField applies outward or inward repulsion forces based on an ellipsoidal geometry defined by its center, radii, stiffness, and damping parameters.",
    "sheet": "# EllipsoidForceField\n\n## Overview\n\nThe EllipsoidForceField is a force field component in the Sofa framework that applies outward or inward repulsion forces to particles based on their distance from an ellipsoidal surface. It inherits from the `ForceField` class.\n\n## Mathematical Model\n\n### Definitions\n- **Center of Ellipsoid**: \\(\\mathbf{c} = (c_x, c_y, c_z)\\)\n- **Radii of Ellipsoid**: \\(\\mathbf{r} = (r_x, r_y, r_z)\\)\n- **Position of Particle**: \\(\\mathbf{p}_i = (x_i, y_i, z_i)\\)\n- **Displacement from Center**: \\(\\mathbf{d}_i = \\mathbf{p}_i - \\mathbf{c}\\)\n- **Stiffness Parameter**: \\(k\\)\n- **Damping Coefficient**: \\(d\\)\n\n### Distance and Normalization\n1. **Distance from Center**:\n   The displacement vector \\(\\mathbf{d}_i\\) is given by:\n   \\[\\mathbf{d}_i = (x_i - c_x, y_i - c_y, z_i - c_z)\\]\n2. **Normalized Distance**:\n   To normalize the distance to an ellipsoidal surface, we use:\n   \\[\\text{norm}^2 = \\sum_{j=0}^{N-1}\\left(\\frac{(d_i)_j}{r_j}\\right)^2\\]\n\n### Force Calculation\nThe force \\(\\mathbf{F}(p_i)\\) applied to particle \\(i\\) at position \\(\\mathbf{p}_i\\) depends on whether it lies inside or outside the ellipsoid:\n1. **Inside Ellipsoid**:\n   If \\((\\text{norm}^2 - 1)k < 0\\), the point is considered inside and a repulsive force will be applied.\n   The distance to the surface, normalized by stiffness \\(k\\) and its absolute value, is:\n   \\[v = \\sqrt{\\text{norm}^2} - 1\\]\n\n   **Gradient Calculation**:\n   \\[\\mathbf{grad}_i = \\frac{d_i}{r_j}\\]\n   where each component of the gradient vector \\(\\mathbf{grad}_i\\) is normalized by its respective radius.\n\n   The norm of this gradient is:\n   \\[g_{norm}^2 = ||\\mathbf{grad}_i||^2\\]\n   \\[g_{norm} = \\sqrt{g_{norm}^2}\\]\n\n   **Force Intensity**:\n   The force intensity due to stiffness and damping is given by:\n   \\[F_{intensity} = -|k|v / g_{norm}\\]\n   \\[\\text{Damping Intensity} = d |v|\\]\n2. **Total Force**:\n   Combining these components, the total force applied to particle \\(i\\) is:\n   \\[\\mathbf{F}_i = \\frac{-k}{g_{norm}} (\\sqrt{\\text{norm}^2}-1)\\frac{d_i}{r_j} - d v \\mathbf{v}_i\\]\n\n## Parameters and Data\n- **center**: Ellipsoid center (`Coord`, default: none)\n- **vradius**: Ellipsoid radius (`Coord`, default: none)\n- **stiffness**: Force stiffness (positive to repulse outward, negative inward) (`Real`, default: none)\n- **damping**: Force damping (`Real`, default: none)\n- **color**: Ellipsoid color (`sofa::type::RGBAColor`, default: `0.0, 0.5, 1.0, 1.0`)"
  }
}