Methods

{
  "name": "ParallelSpringForceField",
  "namespace": "multithreading::component::solidmechanics::spring",
  "module": "MultiThreading",
  "include": "MultiThreading/component/solidmechanics/spring/ParallelSpringForceField.h",
  "doc": "Parallel stiff springs.",
  "inherits": [
    "TaskSchedulerUser"
  ],
  "templates": [
    "sofa::sofa::defaulttype::Rigid3Types",
    "sofa::sofa::defaulttype::Vec3Types"
  ],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "init",
      "return_type": "void",
      "params": [],
      "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": "data_f1",
          "type": "DataVecDeriv &"
        },
        {
          "name": "data_f2",
          "type": "DataVecDeriv &"
        },
        {
          "name": "data_x1",
          "type": "const DataVecCoord &"
        },
        {
          "name": "data_x2",
          "type": "const DataVecCoord &"
        },
        {
          "name": "data_v1",
          "type": "const DataVecDeriv &"
        },
        {
          "name": "data_v2",
          "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 sofa::core::MechanicalParams *"
        },
        {
          "name": "data_df1",
          "type": "DataVecDeriv &"
        },
        {
          "name": "data_df2",
          "type": "DataVecDeriv &"
        },
        {
          "name": "data_dx1",
          "type": "const DataVecDeriv &"
        },
        {
          "name": "data_dx2",
          "type": "const DataVecDeriv &"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `ParallelSpringForceField` is part of the MultiThreading module in the SOFA framework, specifically designed to handle stiff spring forces using parallel computation techniques. This component inherits from `TaskSchedulerUser`, enabling it to utilize multithreading capabilities for efficient force calculations.\n\n**Role and Purpose:**\nThe primary role of `ParallelSpringForceField` is to compute the forces exerted by stiff springs in a simulation, leveraging parallel processing to enhance performance. It supports various data types (`Vec3Types`, `Rigid3Types`, etc.) and integrates seamlessly into SOFA's multithreading environment.\n\n**Interactions with Other Components:**\nThe component interacts primarily through its API methods:\n- `init`: Initializes the component, setting up the task scheduler for parallel operations.\n- `addForce`: Computes and adds forces between two sets of points (`data_f1` and `data_f2`) based on positions and velocities. It utilizes a parallel loop to distribute this computation across multiple threads.\n- `addDForce`: Calculates and updates derivative forces, also using multithreading for efficiency.\n\n**Practical Usage Guidance:**\nThe component is typically used in simulations requiring stiff spring behavior where performance gains from parallel processing are beneficial. No specific data fields or configurations are exposed directly; the setup relies on inheriting properties and methods from its base classes to define springs and manage mechanical parameters.",
  "maths": "<maths>\n\n## Governing Equations and Operators\n\nThe `ParallelSpringForceField` implements the computation of forces exerted by stiff springs in a simulation. The key operators and equations involved are:\n\n1. **Internal Force** (\\( f_{int} \\\n)): The component computes the internal force due to each spring connecting two particles. This is expressed as:\n   \\[ f_{spring}(x_1, x_2) = -k (x_1 - x_2 - l_0) \\]\n   where:\n   - \\( k \\\\) is the stiffness coefficient of the spring.\n   - \\( l_0 \\\\) is the rest length of the spring.\n   - \\( x_1, x_2 \\\\) are the positions of the two particles connected by the spring.\n\n2. **Derivative Force** (\\( f_{dint} \\\n)): The derivative force calculation involves computing the Jacobian matrix (\\( J \\\n)) which represents the partial derivatives of the internal forces with respect to the nodal displacements:\n   \\[ J = \\frac{\\partial f_{spring}}{\\partial x} \\]\n\n## Constitutive or Kinematic Laws Involved\n\nThe constitutive law for each spring can be summarized as follows:\n- **Stiffness Model**: The force exerted by a stiff spring is linearly proportional to the displacement from its rest length. This implies a simple Hookean model with no additional nonlinearities.\n- **Potential Energy**: Each spring contributes to the total potential energy of the system. For an individual spring, this can be expressed as:\n   \\[ V_{spring} = \\frac{1}{2} k (x_1 - x_2 - l_0)^2 \\]\n\n## Role in the Global FEM Pipeline\n\nThe `ParallelSpringForceField` plays a crucial role in the assembly phase of the FEM pipeline:\n- **Assembly**: The component computes the contributions to the internal force vector (\\( f_{int} \\\n)) and Jacobian matrix (\\( J \\\n)). These are assembled into the global system matrices.\n- **Time Integration**: The computed forces are used in the time integration schemes, such as implicit Euler or Newmark methods, for advancing the state of the simulation over time.\n\n## Numerical Methods and Discretization Choices\n\nThe component uses parallel computation to efficiently compute forces:\n1. **Parallel Computation**: Forces are computed concurrently across multiple threads using a task scheduler (`TaskSchedulerUser`).\n2. **Thread Safety**: Mutexes ensure thread safety during the aggregation of computed forces.\n3. **Efficient Force Calculation**: The `addForce` and `addDForce` methods leverage multithreading to distribute force computations, enhancing performance.\n\n## Fit into Variational / Lagrangian Mechanics Framework\n\nWithin the broader variational mechanics framework, the component:\n- **Weak Formulation**: Although not explicitly stated in the source code, the weak form of the internal forces is implicitly considered when assembling the global matrices.\n- **Variational Principle**: The force computation aligns with the principle of virtual work, where the total potential energy (sum of spring energies) is minimized to determine equilibrium configurations.\n\n</maths>",
  "abstract": "The `ParallelSpringForceField` computes stiff spring forces in a simulation using parallel processing techniques to enhance performance.",
  "sheet": "# ParallelSpringForceField\n\n**Overview:**\nThe `ParallelSpringForceField` is part of SOFA's MultiThreading module, designed for efficient computation of stiff spring forces through multithreading. It inherits from `TaskSchedulerUser`, enabling it to distribute force calculations across multiple threads.\n\n**Mathematical Model:**\nThe component computes the internal and derivative forces exerted by stiff springs in a simulation. The governing equations are:\n- **Internal Force**: \\\\[ f_{spring}(x_1, x_2) = -k (x_1 - x_2 - l_0) \\\\]\n  where \\\\( k \\\\) is the stiffness coefficient, \\\\( l_0 \\\\) is the rest length of the spring, and \\\\( x_1, x_2 \\\\) are the positions of the two particles connected by the spring.\n- **Derivative Force**: The Jacobian matrix \\\\[ J = \\frac{\\partial f_{spring}}{\\partial x} \\\\] represents the partial derivatives of the internal forces with respect to nodal displacements.\n\n**Practical Notes:**\nThe component is typically used in simulations requiring stiff spring behavior where performance gains from parallel processing are beneficial. It leverages multithreading for efficient force calculations, ensuring thread safety during aggregation."
}