Data Fields

Methods

{
  "name": "NewmarkImplicitSolver",
  "namespace": "sofa::component::odesolver::backward",
  "module": "Sofa.Component.ODESolver.Backward",
  "include": "sofa/component/odesolver/backward/NewmarkImplicitSolver.h",
  "doc": "Implicit time integrator using Newmark scheme.\n\nImplicit time integrator using Newmark scheme.\nThis integration scheme is based on the following equations:\n  $x_{t+h} = x_t + h v_t + h^2/2 ( (1-2\\beta) a_t + 2\\beta a_{t+h} )$\n  $v_{t+h} = v_t + h ( (1-\\gamma) a_t + \\gamma a_{t+h} )$\nApplied to a mechanical system where $ M a_t + (r_M M + r_K K) v_t + K x_t = f_ext$, we need to solve the following system:\n  $ M a_{t+h} + (r_M M + r_K K) v_{t+h} + K x_{t+h} = f_ext $\n  $ M a_{t+h} + (r_M M + r_K K) ( v_t + h ( (1-\\gamma) a_t + \\gamma a_{t+h} ) ) + K ( x_t + h v_t + h^2/2 ( (1-2\\beta) a_t + 2\\beta a_{t+h} ) ) = f_ext $\n  $ ( M + h \\gamma (r_M M + r_K K) + h^2 \\beta K ) a_{t+h} = f_ext - (r_M M + r_K K) ( v_t + h (1-\\gamma) a_t ) - K ( x_t + h v_t + h^2/2 (1-2\\beta) a_t ) $\n  $ ( (1 + h \\gamma r_M) M + (h^2 \\beta + h \\gamma r_K) K ) a_{t+h} = f_ext - (r_M M + r_K K) v_t - K x_t - (r_M M + r_K K) ( h (1-\\gamma) a_t ) - K ( h v_t + h^2/2 (1-2\\beta) a_t ) $\n  $ ( (1 + h \\gamma r_M) M + (h^2 \\beta + h \\gamma r_K) K ) a_{t+h} = a_t - (r_M M + r_K K) ( h (1-\\gamma) a_t ) - K ( h v_t + h^2/2 (1-2\\beta) a_t ) $\nThe current implementation first computes $a_t$ directly (as in the explicit solvers), then solves the previous system to compute $a_{t+dt}$, and finally computes the new position and velocity.",
  "inherits": [
    "LinearSolverAccessor",
    "OdeSolver"
  ],
  "templates": [],
  "data_fields": [
    {
      "name": "d_rayleighStiffness",
      "type": "SReal",
      "xmlname": "rayleighStiffness",
      "help": "Rayleigh damping coefficient related to stiffness"
    },
    {
      "name": "d_rayleighMass",
      "type": "SReal",
      "xmlname": "rayleighMass",
      "help": "Rayleigh damping coefficient related to mass"
    },
    {
      "name": "d_velocityDamping",
      "type": "SReal",
      "xmlname": "vdamping",
      "help": "Velocity decay coefficient (no decay if null)"
    },
    {
      "name": "d_gamma",
      "type": "SReal",
      "xmlname": "gamma",
      "help": "Newmark scheme gamma coefficient"
    },
    {
      "name": "d_beta",
      "type": "SReal",
      "xmlname": "beta",
      "help": "Newmark scheme beta coefficient"
    },
    {
      "name": "d_threadSafeVisitor",
      "type": "bool",
      "xmlname": "threadSafeVisitor",
      "help": "If true, do not use realloc and free visitors in fwdInteractionForceField."
    }
  ],
  "links": [],
  "methods": [
    {
      "name": "solve",
      "return_type": "void",
      "params": [
        {
          "name": "params",
          "type": "const core::ExecParams *"
        },
        {
          "name": "dt",
          "type": "SReal"
        },
        {
          "name": "xResult",
          "type": "sofa::core::MultiVecCoordId"
        },
        {
          "name": "vResult",
          "type": "sofa::core::MultiVecDerivId"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getVelocityIntegrationFactor",
      "return_type": "SReal",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getPositionIntegrationFactor",
      "return_type": "SReal",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getIntegrationFactor",
      "return_type": "SReal",
      "params": [
        {
          "name": "inputDerivative",
          "type": "int"
        },
        {
          "name": "outputDerivative",
          "type": "int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getSolutionIntegrationFactor",
      "return_type": "SReal",
      "params": [
        {
          "name": "outputDerivative",
          "type": "int"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The Newmark Implicit Solver is an advanced time integration method used in the SOFA (Simulation Open Framework Architecture) framework for simulating deformable objects and rigid bodies with high accuracy.\n\n### Key Features:\n- **Implicit Integration**: This solver uses implicit methods to integrate the equations of motion, which allows it to handle stiff systems and large timesteps more stably than explicit solvers.\n- **Newmark Beta Method**: It implements the Newmark beta method, a popular approach in structural dynamics for time integration. The solver incorporates two parameters (beta and gamma) that can be adjusted to control stability and accuracy.\n- **Rayleigh Damping**: This feature allows for the simulation of damping effects by combining viscous and proportional damping terms.\n- **Constraint Handling**: It can handle constraints within the system, such as contacts or joints, ensuring physical consistency in simulations involving interactions between objects.\n\n### Workflow:\n1. **Initialization**:\n   - The solver initializes acceleration at time t (a_t) to zero for the first timestep and stores it for further use.\n2. **Compute Right Hand Side of Equation**:\n   - It calculates the external forces acting on the system, forming the right-hand side of the equation to be solved.\n3. **Solve System of Equations**:\n   - The solver sets up the matrix equation based on the Newmark parameters and solves for acceleration at time t+h (a_{t+h}).\n4. **Update Positions and Velocities**:\n   - Using the computed accelerations, it updates positions and velocities to their new values after a timestep.\n5. **Constraint Resolution**:\n   - The solver resolves any constraints that have been defined in the simulation to ensure physical feasibility of results.\n\n### Parameters:\n- **gamma**: A parameter in the Newmark method controlling numerical damping; default is 0.5.\n- **beta**: Another Newmark method parameter affecting accuracy and stability; default is 0.25.\n- **rayleighStiffness (rK)**: Coefficient for Rayleigh damping related to stiffness, used to simulate damping effects proportional to the system's stiffness.\n- **rayleighMass (rM)**: Coefficient for Rayleigh damping related to mass, simulating viscous damping effects.\n- **vdamping**: Velocity decay coefficient to model energy dissipation over time; default is 0, meaning no decay.\n\n### Applications:\nThis solver is particularly useful in scenarios where accurate long-term simulation stability and handling of complex constraints are required. It is suitable for a wide range of applications including virtual surgery, biomechanics research, and interactive simulations demanding high fidelity.\n\n### Limitations:\nThe implicit nature of the Newmark method can be computationally expensive compared to explicit methods, particularly in large-scale or real-time simulation contexts.",
  "parameters": {
    "gamma": "A parameter controlling numerical damping in the Newmark scheme (default: 0.5).",
    "beta": "A parameter affecting accuracy and stability in the Newmark scheme (default: 0.25).",
    "rayleighStiffness": "Coefficient for Rayleigh damping related to stiffness.",
    "rayleighMass": "Coefficient for Rayleigh damping related to mass.",
    "vdamping": "Velocity decay coefficient to model energy dissipation over time."
  },
  "examples": [
    {
      "example": "Simulating a deformable object with accurate long-term behavior while handling complex constraints, such as in virtual surgical simulations or biomechanical studies."
    }
  ],
  "maths": "The Newmark Implicit Solver is an advanced time integration method used in the SOFA framework for simulating deformable objects and rigid bodies with high accuracy. This solver implements the implicit Newmark beta method, which provides stability and accurate solutions for stiff systems.\n\n### Governing Equations:\nThe solver uses the following discrete equations based on the Newmark beta scheme:\n\begin{align*}\n  x_{t+h} &= x_t + h v_t + \\frac{h^2}{2} ((1-2\\beta) a_t + 2\\beta a_{t+h}) \\\\\nv_{t+h} &= v_t + h((1-\\gamma)a_t + \\gamma a_{t+h})\n\\end{align*}\n\nwhere:\n- $x$: position,\n- $v$: velocity,\n- $a$: acceleration,\n- $h$: time step.\n\nFor the mechanical system, the equations of motion can be written as:\n\\[ M a_t + (r_M M + r_K K) v_t + K x_t = f_{ext} \\]\nwhere:\n- $M$: mass matrix,\n- $K$: stiffness matrix,\n- $(r_M M + r_K K)$: damping term with Rayleigh coefficients $r_M$ and $r_K$.\n\n### Implicit System of Equations:\nThe Newmark scheme leads to the following implicit system to be solved for $a_{t+h}$:\n\\[ (1 + h \\gamma r_M) M a_{t+h} + (h^2 \\beta + h \\gamma r_K) K x_{t+h} = f_{ext} - (r_M M + r_K K) v_t - K x_t - (r_M M + r_K K) h(1-\\gamma)a_t - K h v_t - K \\frac{h^2}{2}(1-2\\beta)a_t. \\]\n\n### Numerical Methods and Discretization Choices:\nThe solver discretizes the equations of motion using the Newmark beta method, which is known for its stability properties. The damping terms are incorporated via Rayleigh damping, where $r_M$ and $r_K$ are coefficients related to mass and stiffness, respectively.\n\n### Role in FEM Pipeline:\nThe component fits into the broader FEM pipeline by handling time integration and solving the resulting nonlinear system of equations at each time step. Specifically, it performs the following steps:\n1. **Initialization**: Initializes acceleration $a_t$ at the first timestep.\n2. **Compute Right Hand Side**: Computes external forces to form the right-hand side of the equation for $a_{t+h}$.\n3. **Solve System**: Solves the matrix system to find $a_{t+h}$.\n4. **Update Positions and Velocities**: Updates positions and velocities based on the computed accelerations.\n5. **Constraint Resolution**: Ensures that constraints such as contacts or joints are satisfied within the simulation.\n\n### Constitutive Laws:\nThe solver does not directly implement constitutive laws but relies on the FEM framework to provide these through other components (e.g., force fields, material models). The Newmark Implicit Solver focuses on time integration and solving the equations of motion.\n\n### Constraint Handling:\nThe component supports constraint handling by ensuring that constraints are satisfied at each time step. This is achieved by projecting forces onto constrained subspaces as part of the solution process.\n\nOverall, the Newmark Implicit Solver provides a robust framework for simulating deformable objects and rigid bodies with high accuracy while maintaining stability over long simulations.",
  "abstract": "The NewmarkImplicitSolver performs implicit time integration using the Newmark scheme to solve equations of motion in mechanical systems with Rayleigh damping.",
  "sheet": "# NewmarkImplicitSolver\n\n## Overview\nThe NewmarkImplicitSolver is an implicit time integrator that uses the Newmark beta method for integrating the equations of motion in mechanical systems. It supports Rayleigh damping and adjusts parameters such as gamma and beta to control stability and accuracy.\n\n## Mathematical Model\nThe solver employs the following discrete equations based on the Newmark beta scheme:\n\\begin{align*}\n  x_{t+h} &= x_t + h v_t + \\frac{h^2}{2} ((1-2\\beta) a_t + 2\\beta a_{t+h}) \\\\\nv_{t+h} &= v_t + h((1-\\gamma)a_t + \\gamma a_{t+h})\n\\end{align*}\nwhere $x$ is position, $v$ is velocity, $a$ is acceleration, and $h$ is the time step.\n\nFor the mechanical system, the equations of motion are:\n\\[ M a_t + (r_M M + r_K K) v_t + K x_t = f_{ext} \\]\nwhere $M$ is the mass matrix, $K$ is the stiffness matrix, and $(r_M M + r_K K)$ represents Rayleigh damping.\n\nThe implicit system to be solved for $a_{t+h}$ is:\n\\[ (1 + h \\gamma r_M) M a_{t+h} + (h^2 \\beta + h \\gamma r_K) K x_{t+h} = f_{ext} - (r_M M + r_K K) v_t - K x_t - (r_M M + r_K K) h(1-\\gamma)a_t - K h v_t - K \\frac{h^2}{2}(1-2\\beta)a_t. \\]\n\n## Parameters and Data\nThe significant data fields are:\n- **rayleighStiffness ($r_K$)**: Rayleigh damping coefficient related to stiffness.\n- **rayleighMass ($r_M$)**: Rayleigh damping coefficient related to mass.\n- **vdamping**: Velocity decay coefficient (no decay if null).\n- **gamma**: Newmark scheme gamma coefficient, default is 0.5.\n- **beta**: Newmark scheme beta coefficient, default is 0.25.\n- **threadSafeVisitor**: Boolean flag indicating whether to use thread-safe visitors in fwdInteractionForceField.\n\n## Practical Notes\nThe implicit nature of the Newmark method can be computationally expensive compared to explicit methods, particularly for large-scale or real-time simulations. The solver requires careful tuning of parameters such as gamma and beta to balance stability and accuracy."
}