{
  "name": "FixPickedParticleButtonSetting",
  "main": {
    "name": "FixPickedParticleButtonSetting",
    "namespace": "sofa::gui::component",
    "module": "Sofa.GUI.Component",
    "include": "sofa/gui/component/FixPickedParticleButtonSetting.h",
    "doc": "Fix a picked particle in space.",
    "inherits": [
      "MouseButtonSetting"
    ],
    "templates": [],
    "data_fields": [
      {
        "name": "stiffness",
        "type": "SReal",
        "xmlname": "stiffness",
        "help": "Stiffness of the spring to fix a particule"
      }
    ],
    "links": [],
    "methods": [
      {
        "name": "getOperationType",
        "return_type": "int",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The `FixPickedParticleButtonSetting` is a component in SOFA's GUI module that allows for fixing a picked particle in space, effectively pinning it to its current position. It inherits from the `MouseButtonSetting` class, indicating that it reacts to mouse button events within the graphical user interface.\n\n### Role and Purpose\nThis component serves to temporarily or permanently constrain particles at specific locations by creating springs with specified stiffness values. This functionality is useful for simulations where interactive manipulation of objects or parts of a model is required.\n\n### Interactions with Other Components\n- **MouseButtonSetting**: Inherits from this base class, which means it integrates with the GUI event handling system, responding to mouse events.\n- **ConfigurationSetting**: Likely interacts indirectly through its parent `MouseButtonSetting`, contributing to the configuration and setting management within SOFA's graphical interface.\n\n### Practical Usage Guidance\nTo use `FixPickedParticleButtonSetting`, a user typically selects a particle in the GUI by clicking on it. The component then fixes this particle with a specified stiffness, allowing it to be held steady during simulation or manipulation tasks.\n\n- **Data Fields**:\n  - `stiffness`: Defines the stiffness of the spring used to fix the particle. This field is configurable and defaults to a value of 10000 (units: SReal).\n\nOverall, this component facilitates interactive simulations where specific particles need to be anchored or held fixed."
  },
  "maths": {
    "maths": "The `FixPickedParticleButtonSetting` component in the SOFA framework is designed to fix selected particles at specific positions within a simulation. This functionality effectively pins or anchors these particles, which can be useful for interactive manipulation tasks during simulations.\n\n### Governing Equations and Operators\n- **Spring Stiffness**: The component introduces an additional spring constraint with stiffness defined by the parameter `stiffness`. Mathematically, this is represented as a linear spring force term:\n  \n  \\[ f_{\\text{spring}} = k (x - x_0) \\]\n\n  where:\n  - \\( k \\) is the stiffness of the spring (`stiffness` parameter).\n  - \\( x \\) is the current position of the particle.\n  - \\( x_0 \\) is the fixed reference position (the position at which the particle is pinned).\n\n### Constitutive or Kinematic Laws Involved\n- **Linear Spring Law**: The component employs a linear spring law to fix particles. The stiffness `k` is configurable and defaults to 10000 units (`SReal`).\n\n### Role in the Global FEM Pipeline\n- **Assembly**: This component contributes an additional constraint term to the system of equations, effectively modifying the global force vector and potentially the mass matrix if implicit time integration methods are used.\n- **Time Integration**: During time integration (e.g., using implicit Euler or Newmark schemes), the spring force `f_{\\text{spring}}` is incorporated into the overall force balance equation:\n  \n  \\[ M \frac{\text{d}^2 x}{\text{d} t^2} + K(x - x_0) = F(t) \\]\n\n  where `M` is the mass matrix, `K` is the stiffness matrix (including contributions from the linear spring), and `F(t)` represents external forces.\n- **Nonlinear Solve**: The inclusion of this spring constraint does not typically affect the nonlinear solve step significantly unless the particle's position changes dramatically, which can be handled by standard Newton-Raphson or similar iterative methods.\n- **Linear Solve**: The stiffness term is linear and straightforward to incorporate into the linear solve process during each time step.\n\n### Numerical Methods and Discretization Choices\n- **Implicit Integration**: If implicit integration schemes are used (such as implicit Euler), the spring force will be directly incorporated into the linear system of equations solved at each time step.\n- **Direct Constraint Handling**: The component directly adds a constraint to the simulation by fixing particle positions, which is straightforward in terms of numerical implementation but can impact overall system stiffness and convergence behavior if not managed carefully.\n\n### Variational / Lagrangian Mechanics Framework\n- This component fits into the broader variational mechanics framework as an additional constraint that modifies the potential energy function. By adding a linear spring term to pin particles, it effectively changes the system's potential energy landscape:\n  \n  \\[ V(x) = \\frac{1}{2} k (x - x_0)^2 + V_{\\text{other}}(x) \\]\n\n  where `V_{\\text{other}}` represents other potential energy terms in the system. The total force is then derived from this modified potential energy function, incorporating both the spring constraint and any external forces.\n"
  },
  "summary": {
    "abstract": "Fixes picked particles in space by introducing a linear spring with specified stiffness, reacting to mouse events within the SOFA GUI.",
    "sheet": "<h1>FixPickedParticleButtonSetting</h1>\n\n<h2>Overview</h2>\n<p>The `FixPickedParticleButtonSetting` component is part of the SOFA GUI module and allows for fixing picked particles in space by creating springs with specified stiffness. It inherits from the `MouseButtonSetting` class, indicating that it reacts to mouse button events within the graphical user interface.</p>\n\n<h2>Mathematical Model</h2>\n<p>The component introduces a linear spring constraint to fix selected particles at specific positions. The governing equation for this spring is:</p>\n\\[ f_{\\text{spring}} = k (x - x_0) \\]\n<p>where:</p>\n<ul>\n<li><span class=\"math inline\">\\(k\\)</span> is the stiffness of the spring, defined by the <code>stiffness</code> parameter.</li>\n<li><span class=\"math inline\">\\(x\\)</span> is the current position of the particle.</li>\n<li><span class=\"math inline\">\\(x_0\\)</span> is the fixed reference position (the position at which the particle is pinned).</li>\n</ul>\n<p>The spring force <span class=\"math inline\">\\(f_{\\text{spring}}\\)</span> modifies the global force vector and potentially the mass matrix during implicit time integration.</p>\n\n<h2>Parameters and Data</h2>\n<table>\n<thead>\n<tr>\n<th>Name</th>\n<th>Type</th>\n<th>Description</th>\n<th>Default Value</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>stiffness</code></td>\n<td>SReal</td>\n<td>Stiffness of the spring to fix a particle.</td>\n<td>10000 (SReal)</td>\n</tr>\n</tbody>\n</table>"
  }
}