{
  "name": "FreeMotionAnimationLoop",
  "main": {
    "name": "FreeMotionAnimationLoop",
    "namespace": "sofa::component::animationloop",
    "module": "Sofa.Component.AnimationLoop",
    "include": "sofa/component/animationloop/FreeMotionAnimationLoop.h",
    "doc": "( The animation loop to use with constraints. You must add this loop at the beginning of the scene if you are using constraints.",
    "inherits": [
      "CollisionAnimationLoop"
    ],
    "templates": [],
    "data_fields": [
      {
        "name": "d_solveVelocityConstraintFirst",
        "type": "bool",
        "xmlname": "solveVelocityConstraintFirst",
        "help": "solve separately velocity constraint violations before position constraint violations"
      },
      {
        "name": "d_threadSafeVisitor",
        "type": "bool",
        "xmlname": "threadSafeVisitor",
        "help": "If true, do not use realloc and free visitors in fwdInteractionForceField."
      },
      {
        "name": "d_parallelCollisionDetectionAndFreeMotion",
        "type": "bool",
        "xmlname": "parallelCollisionDetectionAndFreeMotion",
        "help": "If true, executes free motion step and collision detection step in parallel."
      },
      {
        "name": "d_parallelODESolving",
        "type": "bool",
        "xmlname": "parallelODESolving",
        "help": "If true, solves all the ODEs in parallel during the free motion step."
      }
    ],
    "links": [
      {
        "name": "l_constraintSolver",
        "target": "ConstraintSolver",
        "kind": "single",
        "xmlname": "constraintSolver",
        "help": "The ConstraintSolver used in this animation loop (required)"
      }
    ],
    "methods": [
      {
        "name": "step",
        "return_type": "void",
        "params": [
          {
            "name": "params",
            "type": "const sofa::core::ExecParams *"
          },
          {
            "name": "dt",
            "type": "SReal"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "init",
        "return_type": "void",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "computeFreeMotionAndCollisionDetection",
        "return_type": "void",
        "params": [
          {
            "name": "params",
            "type": "const sofa::core::ExecParams *"
          },
          {
            "name": "cparams",
            "type": "const core::ConstraintParams &"
          },
          {
            "name": "dt",
            "type": "SReal"
          },
          {
            "name": "pos",
            "type": "sofa::core::MultiVecId"
          },
          {
            "name": "freePos",
            "type": "sofa::core::MultiVecId"
          },
          {
            "name": "freeVel",
            "type": "sofa::core::MultiVecDerivId"
          },
          {
            "name": "mop",
            "type": "simulation::common::MechanicalOperations *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      },
      {
        "name": "computeFreeMotion",
        "return_type": "void",
        "params": [
          {
            "name": "params",
            "type": "const sofa::core::ExecParams *"
          },
          {
            "name": "cparams",
            "type": "const core::ConstraintParams &"
          },
          {
            "name": "dt",
            "type": "SReal"
          },
          {
            "name": "pos",
            "type": "sofa::core::MultiVecId"
          },
          {
            "name": "freePos",
            "type": "sofa::core::MultiVecId"
          },
          {
            "name": "freeVel",
            "type": "sofa::core::MultiVecDerivId"
          },
          {
            "name": "mop",
            "type": "simulation::common::MechanicalOperations *"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "protected"
      }
    ]
  },
  "desc": {
    "description": "The `FreeMotionAnimationLoop` is an animation loop designed to handle simulations involving constraints in the SOFA framework. It inherits from the `CollisionAnimationLoop`, indicating it integrates collision handling functionalities alongside constraint solving.\n\n**Role and Purpose:**\nThe primary role of `FreeMotionAnimationLoop` is to manage the simulation's temporal evolution, particularly when there are constraints involved. This loop ensures that both free motion (i.e., unconstrained movement) and constrained dynamics are computed accurately over each time step.\n\n**Interactions with Other Components:*\nThe component interacts directly with a required `ConstraintSolver`, specified via its API. The solver is used to resolve constraint violations during the simulation steps. This loop also relies on other SOFA components such as mechanical visitors, state update mechanisms, and task schedulers for efficient parallel processing.\n\n**Usage Guidance and Data Fields:**\nThe component offers several configuration options:\n- `solveVelocityConstraintFirst`: Determines whether velocity constraints are solved separately before position constraints.\n- `threadSafeVisitor`: If true, reallocations and deallocations within visitors are avoided to ensure thread safety.\n- `parallelCollisionDetectionAndFreeMotion`: Enables parallel execution of free motion steps and collision detection.\n- `parallelODESolving`: Solves ordinary differential equations (ODEs) in parallel during the free motion step. These options can be configured via XML attributes or dynamically in code."
  },
  "maths": {
    "maths": "# Mathematical and Physical Description of FreeMotionAnimationLoop\n\n## Overview\nThe `FreeMotionAnimationLoop` is a simulation loop designed for handling simulations with constraints in the SOFA (Simulation Open Framework Architecture) framework. This component integrates collision handling along with constraint solving, ensuring that both free motion (unconstrained movement) and constrained dynamics are computed accurately over each time step.\n\n## Mathematical Formulation\n### Free Motion Dynamics\nThe primary goal of the `FreeMotionAnimationLoop` is to solve for the motion under constraints in a dynamic simulation. The physical system can be described by the following equations:\n\n1. **Position Update** (without constraints):\n   \\[\\mathbf{x}_{t+1} = \\mathbf{x}_t + dt \\cdot \\mathbf{v}_t\\]\n   where \\\\[\\mathbf{x}_t\\\\] is the position at time \\\\[t\\\\], and \\\\[\\mathbf{v}_t\\\\] is the velocity at time \\\\[t\\\\].\n\n2. **Velocity Update** (with forces):\n   \\[\\mathbf{v}_{t+1} = \\mathbf{v}_t + dt \\cdot \\frac{\bm{F}}{m}\\]\n   where \\\\[\\bm{F}\\\\] is the net force acting on the system, and \\\\[m\\\\] is the mass.\n\n### Constraint Solving\nConstraints are represented as equations that must be satisfied. For example:\n- **Position Constraints**: \\[g(\\mathbf{x}_{t+1}) = 0\\]\n- **Velocity Constraints**: \\[h(\\mathbf{v}_{t+1}) = 0\\]\n\nThe `ConstraintSolver` is used to solve for these constraints. The solver iteratively adjusts the positions and velocities until the constraints are satisfied within a specified tolerance.\n\n### Parallel Processing\nTo handle large-scale simulations efficiently, parallel processing options are available:\n- **Parallel Collision Detection**: Simultaneous detection of collisions while solving free motion dynamics.\n- **Parallel ODE Solving**: Parallel solution of ordinary differential equations during the free motion step.\n\n## Physical Interpretation\n1. **Free Motion**: In unconstrained scenarios, the system evolves according to standard Newtonian mechanics. The position and velocity updates are straightforward based on forces and initial conditions.\n2. **Constrained Dynamics**: When constraints are present, the dynamics must be adjusted to ensure that these constraints are met at all times. This typically involves projecting velocities or positions onto a feasible manifold defined by the constraints.\n3. **Collision Handling**: Collisions introduce additional constraints into the system. The collision detection and response mechanisms determine how objects interact upon contact, ensuring momentum conservation and reaction forces are applied correctly.\n\n## Usage Guidance\n- `solveVelocityConstraintFirst`: If enabled (true), velocity constraints are solved first before position constraints. This can be beneficial in scenarios where maintaining consistent velocities is crucial before adjusting positions.\n- `threadSafeVisitor`: Ensures thread safety by avoiding reallocations and deallocations within visitors, which is critical for multi-threaded simulations.\n- `parallelCollisionDetectionAndFreeMotion`, `parallelODESolving`: These options enable parallel processing to enhance performance in large-scale simulations.\n\n## Configuration Options\nThe following configuration options are available via XML attributes or dynamically in code:\n- `solveVelocityConstraintFirst`: Boolean flag (default: false).\n- `threadSafeVisitor`: Boolean flag (default: true).\n- `parallelCollisionDetectionAndFreeMotion`: Boolean flag (default: false).\n- `parallelODESolving`: Boolean flag (default: false).\n\n## Conclusion\nThe `FreeMotionAnimationLoop` is a powerful component for handling dynamic simulations with constraints, providing efficient parallel processing and flexible constraint solving mechanisms. This ensures accurate physical behavior while maintaining high performance in complex scenarios."
  },
  "summary": {
    "abstract": "The `FreeMotionAnimationLoop` manages the simulation's temporal evolution in scenarios involving constraints by integrating collision handling and constraint solving functionalities. It ensures accurate computation of both free motion and constrained dynamics over each time step.",
    "sheet": "# FreeMotionAnimationLoop\n\n## Overview\nThe `FreeMotionAnimationLoop` is an animation loop component designed to handle simulations involving constraints within the SOFA framework. This component integrates collision handling along with constraint solving, ensuring that both free motion (unconstrained movement) and constrained dynamics are computed accurately over each time step.\n\n## Parameters and Data\n- **solveVelocityConstraintFirst**: Boolean flag determining whether velocity constraints are solved separately before position constraints. Default: `false`.\n- **threadSafeVisitor**: Boolean flag indicating if reallocations and deallocations within visitors are avoided to ensure thread safety. Default: `true`.\n- **parallelCollisionDetectionAndFreeMotion**: Boolean flag enabling parallel execution of free motion steps and collision detection. Default: `false`.\n- **parallelODESolving**: Boolean flag for solving ordinary differential equations (ODEs) in parallel during the free motion step. Default: `false`.\n\n## Dependencies and Connections\nThe component requires a `ConstraintSolver`, specified via its API, to resolve constraint violations during simulation steps. It also interacts with other SOFA components such as mechanical visitors, state update mechanisms, and task schedulers for efficient parallel processing.\n\n## Practical Notes\n- Enabling `solveVelocityConstraintFirst` can be beneficial in scenarios where maintaining consistent velocities is crucial before adjusting positions.\n- The `threadSafeVisitor` option ensures thread safety by avoiding reallocations and deallocations within visitors, which is critical for multi-threaded simulations.\n- Parallel processing options (`parallelCollisionDetectionAndFreeMotion`, `parallelODESolving`) enhance performance in large-scale simulations but may require careful tuning to avoid numerical instability."
  }
}