{
  "name": "AnimateVisitor",
  "main": {
    "name": "AnimateVisitor",
    "namespace": "sofa::simulation",
    "module": "Sofa.framework.Simulation.Core",
    "include": "sofa/simulation/AnimateVisitor.h",
    "doc": "",
    "inherits": [
      "Visitor"
    ],
    "templates": [],
    "data_fields": [],
    "links": [],
    "methods": [
      {
        "name": "setDt",
        "return_type": "void",
        "params": [
          {
            "name": "v",
            "type": "SReal"
          }
        ],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getDt",
        "return_type": "SReal",
        "params": [],
        "is_virtual": false,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "processCollisionPipeline",
        "return_type": "void",
        "params": [
          {
            "name": "node",
            "type": "simulation::Node *"
          },
          {
            "name": "obj",
            "type": "core::collision::Pipeline *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "fwdInteractionForceField",
        "return_type": "void",
        "params": [
          {
            "name": "node",
            "type": "simulation::Node *"
          },
          {
            "name": "obj",
            "type": "core::behavior::BaseInteractionForceField *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "processNodeTopDown",
        "return_type": "Result",
        "params": [
          {
            "name": "node",
            "type": "simulation::Node *"
          }
        ],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "isThreadSafe",
        "return_type": "bool",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      },
      {
        "name": "getCategoryName",
        "return_type": "const char *",
        "params": [],
        "is_virtual": true,
        "is_pure_virtual": false,
        "is_static": false,
        "access": "public"
      }
    ]
  },
  "desc": {
    "description": "The `AnimateVisitor` is a SOFA component within the `sofa::simulation` namespace and part of the `Sofa.framework.Simulation.Core` module. It inherits from the `Visitor` class and plays a crucial role in advancing the simulation by processing nodes, collision pipelines, interaction force fields, and mechanical integration steps.\n\n### Role and Purpose:\nThe primary purpose of `AnimateVisitor` is to manage the temporal progression (or animation) of the physical system within SOFA. It handles various aspects including collision detection, solving constraints, applying forces, and updating positions/velocities across different nodes in the scene graph hierarchy.\n\n### Interactions with Other Components:\n- **Nodes**: `AnimateVisitor` processes individual simulation nodes, calling methods on them to propagate events (`IntegrateBeginEvent`, `IntegrateEndEvent`) and execute mechanical integration steps.\n- **Collision Pipeline**: It interacts with collision pipelines by executing the necessary collision detection procedures using `processCollisionPipeline` method.\n- **Interaction Force Fields**: It iterates over interaction force fields, applying forces through methods like `fwdInteractionForceField`.\n- **Mechanical Solvers**: The component executes mechanical solvers to update positions and velocities based on applied forces and constraints.\n\n### Practical Usage Guidance:\nThe `AnimateVisitor` is typically not directly instantiated by the user but rather used internally within SOFA's simulation framework. Users interact indirectly through setting up nodes, behaviors, collision pipelines, and force fields in their scene graph configurations.\n- **Data Fields**:\n  - `dt`: Represents the time step (Delta Time) for numerical integration.\n\n### Methods Overview:\n- **setDt(SReal v)**: Sets the time step for the simulation.\n- **getDt()**: Retrieves the current time step value.\n- **processCollisionPipeline(Node*, Pipeline*)**: Executes collision detection procedures on a given node's pipeline.\n- **fwdInteractionForceField(Node*, BaseInteractionForceField*)**: Applies forces to interaction force fields within nodes.\n- **processNodeTopDown(Node*)**: Main processing method that advances simulation steps, including constraint resets, mechanical integration, and event propagation.\n\nThe `AnimateVisitor` supports thread-safe operations and categorizes itself under the 'animate' category for debugging/profiling purposes."
  },
  "maths": {
    "maths": "<h3>AnimateVisitor Component</h3>\n\n<p>The <code>AnimateVisitor</code> is a critical component in the SOFA simulation framework, responsible for advancing the physical system over time. It orchestrates various operations including collision detection, constraint resolution, and mechanical integration to update the positions and velocities of objects within the simulation.</p>\n\n<h4>Mathematical and Physical Operations</h4>\n\n<ul>\n<li><strong>Collision Detection:</strong></li>\n</ul>\n<p>The <code>processCollisionPipeline(Node*, Pipeline*)</code> method executes collision detection procedures. This involves determining whether pairs of objects (e.g., rigid bodies) intersect or come into contact with each other within the specified time step (<span class=\"math-inline\">\\(dt\\)</span>). The collision pipeline typically employs algorithms such as bounding volume hierarchies (BVHs) and spatial partitioning techniques to efficiently detect collisions.</p>\n\n<ul>\n<li><strong>Force Application:</strong></li>\n</ul>\n<p>The <code>fwdInteractionForceField(Node*, BaseInteractionForceField*)</code> method applies forces from interaction force fields. Interaction force fields model the influence of various physical phenomena (e.g., gravity, springs, contacts) on objects in the simulation. The external forces are added to the system's internal state through methods like <code>addForce(&mparams, ffId)</code>, where <span class=\"math-inline\">\\(ffId\\)</span> is an identifier for the force field and <span class=\"math-inline\">\\(mparams\\)</span> holds mechanical parameters.</p>\n\n<ul>\n<li><strong>Mechanical Integration:</strong></li>\n</ul>\n<p>The core of the temporal progression lies in the <code>processNodeTopDown(Node*)</code> method, which performs several key operations:</p>\n\n<ol type=\"1\">\n<li><strong>Constraint Resetting:</strong> Before integrating mechanical equations, constraints (e.g., joints, contacts) are reset using <code>MechanicalResetConstraintVisitor</code>. This ensures that the system starts from a consistent state.</li>\n<li><strong>Solver Execution:</strong> The component iterates over each solver associated with the node and invokes their <code>solve(params, dt)</code> method to solve for new positions and velocities. Solvers typically employ numerical methods such as implicit or explicit time integration schemes to update the system's state.</li>\n<li><strong>Position and Velocity Propagation:</strong> After solving, the new positions and velocities are propagated through the scene graph using <code>MechanicalProjectPositionAndVelocityVisitor</code> and <code>MechanicalPropagateOnlyPositionAndVelocityVisitor</code>. These visitors ensure that updated positions and velocities are correctly applied to all relevant objects.</li>\n<li><strong>Constraint Matrix Construction:</strong> Before solving, the constraint matrix is built using <code>MechanicalBuildConstraintMatrix</code>, which gathers information about constraints affecting the system. This step is crucial for enforcing physical constraints accurately during integration.</li>\n<li><strong>Event Propagation:</strong> Events such as collision begin/end and integrate begin/end are propagated through the scene graph to notify relevant components of simulation state changes.</li>\n</ol>\n\n<h4>Data Fields</h4>\n\n<ul>\n<li><code>dt</code>: The time step (Delta Time) for numerical integration, representing the duration over which forces and constraints are applied. This value is critical for ensuring stability and accuracy in the simulation.</li>\n</ul>\n\n<p>In summary, <code>AnimateVisitor</code> plays a central role in advancing the physical system within SOFA by orchestrating collision detection, force application, constraint resolution, and mechanical integration steps to update object positions and velocities accurately over time.</p>"
  },
  "summary": {
    "abstract": "`AnimateVisitor` manages the temporal progression of the physical system within SOFA by processing nodes, collision pipelines, interaction force fields, and mechanical integration steps.",
    "sheet": "# AnimateVisitor\n\n**Overview**: `AnimateVisitor` is a critical component in the SOFA simulation framework that advances the physical system over time. It orchestrates various operations including collision detection, constraint resolution, and mechanical integration to update positions and velocities of objects within the simulation.\n\n**Parameters and Data**:\n- **dt**: The time step (Delta Time) for numerical integration, representing the duration over which forces and constraints are applied.\n\n**Dependencies and Connections**: `AnimateVisitor` interacts with nodes, collision pipelines, interaction force fields, and mechanical solvers to advance the simulation. It processes individual simulation nodes by calling methods on them to propagate events (`IntegrateBeginEvent`, `IntegrateEndEvent`) and execute mechanical integration steps.\n\n**Practical Notes**: The `AnimateVisitor` is typically not directly instantiated by users but used internally within SOFA's simulation framework. Users interact indirectly through setting up nodes, behaviors, collision pipelines, and force fields in their scene graph configurations."
  }
}