Data Fields

Methods

{
  "name": "PlaneForceField",
  "namespace": "sofa.component.mechanicalload",
  "module": "Sofa.Component.MechanicalLoad",
  "include": "sofa/component/mechanicalload/PlaneForceField.h",
  "doc": "Repulsion along the normal to a plane.\n\n@class PlaneForceField\nA plane is cutting the space in two half spaces. This component generate a force preventing the\nobject to cross the plane. The plane is defined by its normal and by the amount of displacement\nalong this normal.",
  "inherits": [
    "ForceField"
  ],
  "templates": [
    "sofa::defaulttype::Rigid3Types",
    "sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [
    {
      "name": "m_data",
      "type": "DataTypes"
    },
    {
      "name": "d_planeNormal",
      "type": "DPos",
      "xmlname": "normal",
      "help": "plane normal. (default=[0,1,0])"
    },
    {
      "name": "d_planeD",
      "type": "Real",
      "xmlname": "d",
      "help": "plane d coef. (default=0)"
    },
    {
      "name": "d_stiffness",
      "type": "Real",
      "xmlname": "stiffness",
      "help": "force stiffness. (default=500)"
    },
    {
      "name": "d_damping",
      "type": "Real",
      "xmlname": "damping",
      "help": "force damping. (default=5)"
    },
    {
      "name": "d_maxForce",
      "type": "Real",
      "xmlname": "maxForce",
      "help": "if non-null , the max force that can be applied to the object. (default=0)"
    },
    {
      "name": "d_bilateral",
      "type": "bool",
      "xmlname": "bilateral",
      "help": "if true the plane force field is applied on both sides. (default=false)"
    },
    {
      "name": "d_localRange",
      "type": "type::Vec<2, int>",
      "xmlname": "localRange",
      "help": "optional range of local DOF indices. Any computation involving indices outside of this range are discarded (useful for parallelization using mesh partitioning)"
    },
    {
      "name": "d_drawIsEnabled",
      "type": "bool",
      "xmlname": "showPlane",
      "help": "enable/disable drawing of plane. (default=false)"
    },
    {
      "name": "d_drawColor",
      "type": "sofa::type::RGBAColor",
      "xmlname": "planeColor",
      "help": "plane color. (default=[0.0,0.5,0.2,1.0])"
    },
    {
      "name": "d_drawSize",
      "type": "Real",
      "xmlname": "showPlaneSize",
      "help": "plane display size if draw is enabled. (default=10)"
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "setPlane(normal, d)",
      "parameters": [
        {
          "name": "normal",
          "dataType": "Vec3",
          "description": "The new normal vector for the plane.",
          "example": [
            {
              "value": "[0.0, 1.0, 0.0]",
              "explanation": "Sets a horizontal plane."
            }
          ]
        },
        {
          "name": "d",
          "dataType": "float",
          "description": "The new offset value for the plane equation.",
          "example": [
            {
              "value": "5.0",
              "explanation": "Moves the plane 5 units away from the origin along its normal vector."
            }
          ]
        }
      ],
      "returns": null,
      "description": "Sets a new plane defined by its normal and offset values."
    },
    {
      "name": "rotate(axe, angle)",
      "parameters": [
        {
          "name": "axe",
          "dataType": "Vec3",
          "description": "The axis of rotation.",
          "example": [
            {
              "value": "[0.0, 1.0, 0.0]",
              "explanation": "Rotates around the Y-axis."
            }
          ]
        },
        {
          "name": "angle",
          "dataType": "float",
          "description": "The angle of rotation in radians.",
          "example": [
            {
              "value": "M_PI / 2",
              "explanation": "Rotates by 90 degrees (π/2 radians)."
            }
          ]
        }
      ],
      "returns": null,
      "description": "Rotates the plane around a specified axis."
    },
    {
      "name": "updateStiffness(x)",
      "parameters": [
        {
          "name": "x",
          "dataType": "VecCoord",
          "description": "The coordinates of the points to update.",
          "example": [
            {
              "value": "[[0.0, 0.0, 0.0], [1.0, 2.0, 3.0]]",
              "explanation": "Updates stiffness for these two coordinate points."
            }
          ]
        }
      ],
      "returns": null,
      "description": "Updates the internal representation of the plane based on new coordinates."
    },
    {
      "name": "addForce(mparams, f, x, v)",
      "parameters": [
        {
          "name": "mparams",
          "dataType": "core::MechanicalParams*",
          "description": "The mechanical parameters.",
          "example": []
        },
        {
          "name": "f",
          "dataType": "DataVecDeriv&",
          "description": "The forces to be added.",
          "example": []
        },
        {
          "name": "x",
          "dataType": "const DataVecCoord&",
          "description": "The coordinates of the points.",
          "example": []
        },
        {
          "name": "v",
          "dataType": "const DataVecDeriv&",
          "description": "The velocities of the points.",
          "example": []
        }
      ],
      "returns": null,
      "description": "Adds repulsive forces to prevent objects from crossing the plane."
    },
    {
      "name": "addDForce(mparams, df, dx)",
      "parameters": [
        {
          "name": "mparams",
          "dataType": "core::MechanicalParams*",
          "description": "The mechanical parameters.",
          "example": []
        },
        {
          "name": "df",
          "dataType": "DataVecDeriv&",
          "description": "The forces to be added.",
          "example": []
        },
        {
          "name": "dx",
          "dataType": "const DataVecDeriv&",
          "description": "The displacements of the points.",
          "example": []
        }
      ],
      "returns": null,
      "description": "Adds derivative forces based on displacements to prevent objects from crossing the plane."
    },
    {
      "name": "addKToMatrix(mparams, matrix)",
      "parameters": [
        {
          "name": "mparams",
          "dataType": "core::MechanicalParams*",
          "description": "The mechanical parameters.",
          "example": []
        },
        {
          "name": "matrix",
          "dataType": "const sofa::core::behavior::MultiMatrixAccessor*",
          "description": "The stiffness matrix to update.",
          "example": []
        }
      ],
      "returns": null,
      "description": "Updates the stiffness matrix with contributions from the plane force field."
    },
    {
      "name": "buildStiffnessMatrix(matrix)",
      "parameters": [
        {
          "name": "matrix",
          "dataType": "sofa::core::behavior::StiffnessMatrix*",
          "description": "The stiffness matrix to build.",
          "example": []
        }
      ],
      "returns": null,
      "description": "Builds the stiffness matrix for the plane force field."
    },
    {
      "name": "draw(vparams)",
      "parameters": [
        {
          "name": "vparams",
          "dataType": "const core::visual::VisualParams*",
          "description": "The visual parameters.",
          "example": []
        }
      ],
      "returns": null,
      "description": "Draws the plane in the simulation environment if drawing is enabled."
    },
    {
      "name": "computeBBox(params, onlyVisible)",
      "parameters": [
        {
          "name": "params",
          "dataType": "const core::ExecParams*",
          "description": "The execution parameters.",
          "example": []
        },
        {
          "name": "onlyVisible",
          "dataType": "bool",
          "description": "If true, only computes the bounding box for visible objects.",
          "example": []
        }
      ],
      "returns": null,
      "description": "Computes the bounding box for the plane force field."
    }
  ],
  "title": "Plane Force Field",
  "summary": "The PlaneForceField component generates a repulsive force to prevent objects from crossing a defined plane.",
  "description": [
    {
      "paragraph": "This class represents a physical constraint that prevents objects from penetrating a specified plane. The plane is defined by its normal vector and an offset value (d). The repulsion force generated by the component increases linearly with the distance of the object from the plane, up to a maximum limit."
    }
  ],
  "parameters": [
    {
      "name": "planeNormal",
      "dataType": "Vec3",
      "default": "[0, 1, 0]",
      "description": "The normal vector defining the orientation of the plane.",
      "example": [
        {
          "value": "[0, 1, 0]",
          "explanation": "A horizontal plane (normal pointing upwards)."
        }
      ]
    },
    {
      "name": "planeD",
      "dataType": "float",
      "default": "0.0",
      "description": "The offset value for the plane equation.",
      "example": [
        {
          "value": "5.0",
          "explanation": "The plane is 5 units away from the origin along its normal vector."
        }
      ]
    },
    {
      "name": "stiffness",
      "dataType": "float",
      "default": "500.0",
      "description": "Stiffness coefficient for the repulsion force.",
      "example": [
        {
          "value": "1000.0",
          "explanation": "A higher stiffness value results in a stronger repulsive force."
        }
      ]
    },
    {
      "name": "damping",
      "dataType": "float",
      "default": "5.0",
      "description": "Damping coefficient for the repulsion force.",
      "example": [
        {
          "value": "10.0",
          "explanation": "A higher damping value increases the dissipation of energy."
        }
      ]
    },
    {
      "name": "maxForce",
      "dataType": "float",
      "default": "0.0",
      "description": "The maximum magnitude of the repulsive force (if non-null).",
      "example": [
        {
          "value": "1000.0",
          "explanation": "Limits the maximum force to 1000 units."
        }
      ]
    },
    {
      "name": "bilateral",
      "dataType": "bool",
      "default": "false",
      "description": "If true, the force field is applied on both sides of the plane.",
      "example": [
        {
          "value": "true",
          "explanation": "Enables repulsion from both sides of the plane."
        }
      ]
    },
    {
      "name": "localRange",
      "dataType": "[int, int]",
      "default": "[-1, -1]",
      "description": "Optional range of local DOF indices to consider.",
      "example": [
        {
          "value": "[0, 99]",
          "explanation": "Only affects the first 100 DOFs."
        }
      ]
    },
    {
      "name": "drawIsEnabled",
      "dataType": "bool",
      "default": "false",
      "description": "Enables or disables drawing of the plane.",
      "example": [
        {
          "value": "true",
          "explanation": "Visualizes the plane in the simulation environment."
        }
      ]
    },
    {
      "name": "drawColor",
      "dataType": "RGBAColor",
      "default": "[0.0, 0.5, 0.2, 1.0]",
      "description": "The color used for drawing the plane.",
      "example": [
        {
          "value": "[1.0, 0.0, 0.0, 1.0]",
          "explanation": "Draws the plane in red."
        }
      ]
    },
    {
      "name": "drawSize",
      "dataType": "float",
      "default": "10.0",
      "description": "The size used for drawing the plane.",
      "example": [
        {
          "value": "20.0",
          "explanation": "Increases the visible size of the drawn plane."
        }
      ]
    }
  ],
  "maths": "The `PlaneForceField` component in the SOFA framework enforces a physical constraint that prevents objects from penetrating a specified plane. This plane is defined by its normal vector, \\(\\boldsymbol{n}\\), and an offset value, \\(d\\). The equation of the plane can be written as:\n\n\begin{equation}\n    \\boldsymbol{x} \\cdot \\boldsymbol{n} - d = 0,\n\tag{1}\n\nd\neq \text{constant},\n\boldsymbol{n} = (n_1, n_2, n_3)\n\tag{2}\n\\end{equation}\n\nwhere \\(\\boldsymbol{x}\\) is the position vector of a point in space. If the object's position violates this equation, i.e., if \\(\\boldsymbol{x} \\cdot \\boldsymbol{n} - d < 0\\), a repulsive force is generated to push the object away from the plane.\n\nThe repulsion force applied at each node can be expressed as:\n\n\begin{equation}\n    \\boldsymbol{f}(\\boldsymbol{x}) = \n        -k (\\boldsymbol{x} \\cdot \\boldsymbol{n} - d)\\, \\boldsymbol{n}\n         + c (\\boldsymbol{x} \\cdot \\boldsymbol{n} - d)\\, \\dot{\\boldsymbol{x}}\n\tag{3}\n\\end{equation}\n\nwhere:\n- \\(k\\) is the stiffness coefficient, which controls the strength of the repulsive force.\n- \\(c\\) is the damping coefficient, which accounts for the velocity-dependent component of the force to dampen oscillations and stabilize the system.\n\nThe first term in equation (3) represents a linear spring-like force, while the second term acts as a damper. The maximum magnitude of this repulsive force can be limited by setting the `maxForce` parameter, ensuring that the force does not exceed a predefined threshold.\n\n### Governing Equations and Operators Contribution\n- **Internal Force:** This component contributes to the internal forces in the system via the nonlinear term \\(f_{\\text{int}} = \boldsymbol{f}(\\boldsymbol{x})\\).\n- **Stiffness Matrix:** The stiffness matrix \\(K_e\\) associated with this constraint is derived from the first term of equation (3), which represents a linear spring force. Specifically, the local contribution to the stiffness matrix for each node can be represented by:\n\n\begin{equation}\n    K_{e,i} = k \boldsymbol{n} \\otimes \\boldsymbol{n},\n\tag{4}\n\\end{equation}\n\nwhere \\(\\otimes\\) denotes the dyadic (outer) product, and this matrix is added to the global stiffness matrix for each node that violates the plane constraint.\n- **Damping Matrix:** The damping matrix \\(C_e\\), derived from the second term in equation (3), can be expressed as:\n\n\begin{equation}\n    C_{e,i} = c \boldsymbol{n} \\otimes \\boldsymbol{n},\n\tag{5}\n\\end{equation}\n\nwhich is added to the global damping matrix for nodes violating the plane constraint.\n\n### Role in the Global FEM Pipeline:\n- **Assembly Phase:** The component computes and adds contributions from repulsion forces, stiffness terms, and damping terms during the assembly phase of the nonlinear system. These contributions are computed based on node positions that violate the plane equation (1).\n- **Nonlinear Solve:** The internal force term \\(\\boldsymbol{f}(\\boldsymbol{x})\\) is a part of the residual function in the nonlinear solve, contributing to the overall balance of forces.\n- **Linear Solve:** During each iteration of the Newton–Raphson method, this component's contribution is included in the tangent stiffness matrix \\(J(x) = M / Δt -Δt K(x)\\).\n\n### Numerical Methods and Discretization Choices:\n- The force computation uses a linear spring-damper model, discretized at each node within the domain. This ensures that the repulsive forces are computed accurately based on the current position of nodes relative to the plane.\n- The component allows for selective application of constraints through an optional range (`d_localRange`) which can be useful in parallelization or localized computations.\n\n### Variational / Lagrangian Mechanics Framework:\nThe `PlaneForceField` enforces mechanical constraints by directly modifying the internal forces and stiffness/damping matrices. This ensures that the total energy functional (Lagrangian) of the system remains consistent with the imposed physical constraint, thereby preserving the variational principles underlying FEM simulations.",
  "abstract": "The `PlaneForceField` component enforces repulsion along the normal to a specified plane, preventing objects from crossing it. It computes internal forces based on stiffness and damping coefficients.",
  "sheet": "\n# PlaneForceField\n\n## Overview\n\nThe `PlaneForceField` is a mechanical load that generates a repulsive force along the normal of a specified plane, preventing objects from penetrating this plane. This component inherits from the `ForceField` class and operates within the SOFA framework to enforce physical constraints.\n\n## Mathematical Model\n\nThe plane is defined by its normal vector \\\\( \\boldsymbol{n} \\\\) and an offset value \\\\( d \\\\). The equation of the plane can be written as:\n\n\begin{equation}\n    \\boldsymbol{x} \\cdot \\boldsymbol{n} - d = 0,\n    \\label{eq:plane_eq}\n\\end{equation}\n\nwhere \\\\( \\boldsymbol{x} \\\\) is the position vector of a point in space. If an object's position violates this equation (i.e., if \\\\( \\boldsymbol{x} \\cdot \\boldsymbol{n} - d < 0 \\\\)), a repulsive force is generated to push the object away from the plane.\n\nThe repulsion force applied at each node can be expressed as:\n\n\begin{equation}\n    \\boldsymbol{f}(\\boldsymbol{x}) = \n        -k (\\boldsymbol{x} \\cdot \\boldsymbol{n} - d)\\, \\boldsymbol{n}\n         + c (\\boldsymbol{x} \\cdot \\boldsymbol{n} - d)\\, \\dot{\\boldsymbol{x}},\n    \\label{eq:repulsion_force}\n\\end{equation}\n\nwhere:\n- \\\\( k \\\\) is the stiffness coefficient.\n- \\\\( c \\\\) is the damping coefficient.\n\nThe first term in equation (\\ref{eq:repulsion_force}) represents a linear spring-like force, while the second term acts as a damper. The maximum magnitude of this repulsive force can be limited by setting the `maxForce` parameter.\n\n### Stiffness and Damping Matrices\n\nThe stiffness matrix \\\\( K_e \\\\) associated with this constraint is derived from the first term of equation (\\ref{eq:repulsion_force}), which represents a linear spring force. Specifically, the local contribution to the stiffness matrix for each node can be represented by:\n\n\begin{equation}\n    K_{e,i} = k \\boldsymbol{n} \\otimes \\boldsymbol{n},\n    \\label{eq:stiffness_matrix}\n\\end{equation}\n\nwhere \\\\( \\otimes \\\\) denotes the dyadic (outer) product.\n\nThe damping matrix \\\\( C_e \\\\) derived from the second term in equation (\\ref{eq:repulsion_force}) can be expressed as:\n\n\begin{equation}\n    C_{e,i} = c \\boldsymbol{n} \\otimes \\boldsymbol{n},\n    \\label{eq:damping_matrix}\n\\end{equation}\n\n## Parameters and Data\n\n- **normal**: Plane normal vector. (default=[0,1,0])\n- **d**: Plane offset value. (default=0)\n- **stiffness**: Force stiffness coefficient. (default=500)\n- **damping**: Force damping coefficient. (default=5)\n- **maxForce**: Maximum force that can be applied to the object. (default=0)\n- **bilateral**: If true, the plane force field is applied on both sides of the plane. (default=false)\n- **localRange**: Optional range of local DOF indices for parallelization or localized computations.\n- **showPlane**: Enable/disable drawing of the plane. (default=false)\n- **planeColor**: Plane color for visualization. (default=[0.0,0.5,0.2,1.0])\n- **showPlaneSize**: Size of the plane display if drawing is enabled. (default=10)\n\n## Practical Notes\n\n- Ensure that the stiffness and damping coefficients are chosen appropriately to avoid numerical instability.\n- The `maxForce` parameter can be used to limit the magnitude of the repulsive force, which may be necessary for certain simulation scenarios.\n"
}