Methods

{
  "name": "PropagateEventVisitor",
  "namespace": "sofa::simulation",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/PropagateEventVisitor.h",
  "doc": "Visitor used to propagate an event in the data structure.\nPropagation is done top-down until the event is handled.\n\t@author The SOFA team </www.sofa-framework.org>",
  "inherits": [
    "Visitor"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "processNodeTopDown",
      "return_type": "Visitor::Result",
      "params": [
        {
          "name": "node",
          "type": "simulation::Node *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "processObject",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "obj",
          "type": "core::objectmodel::BaseObject *"
        }
      ],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getInfos",
      "return_type": "int",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `PropagateEventVisitor` is a visitor component in the SOFA framework used to propagate an event within the simulation data structure. It operates on a top-down traversal, starting from the root node and moving down through its child nodes until the event is handled by one of the objects. This process ensures that events are appropriately distributed throughout the hierarchy of nodes and objects, facilitating communication between different parts of the simulation.\n\n### Interactions with Other Components:\n- **Node**: The `processNodeTopDown` method iterates over all objects within a node and calls `processObject`, which checks if an object is listening for events. If so, it handles the event using the `handleEvent` function.\n- **BaseObject**: Each BaseObject can handle the event if it is marked as listening (`f_listening.getValue() == true`).\n\n### Practical Usage:\n- The visitor is initialized with a specific event and execution parameters.\n- It propagates this event through the node hierarchy until the event is handled, at which point propagation stops. If an object handles the event, the `processNodeTopDown` method returns `Visitor::RESULT_PRUNE`, indicating that further traversal can be pruned.\n\n### Data Fields:\n- **m_event**: A pointer to the event being propagated through the simulation structure.",
  "maths": "The `PropagateEventVisitor` is a visitor component in the SOFA framework designed to propagate an event through the simulation data structure. Its primary role is not directly related to governing equations, constitutive laws, or the FEM pipeline but rather to facilitate communication and coordination between different components within the simulation hierarchy.\n\n### Mathematical and Physical Description:\n\n#### Role in Simulation Pipeline:\nThe `PropagateEventVisitor` does not contribute directly to the mathematical operators such as mass matrix \\(M\\), stiffness matrix \\(K\\), internal force \\(\boldsymbol{f}_{int}\\), or residual \\(R\\). Instead, it ensures that events are properly propagated and handled within the simulation framework.\n\n#### Event Propagation Mechanism:\nThe `PropagateEventVisitor` is initialized with a specific event (an instance of `sofa::core::objectmodel::Event`) and execution parameters. It performs a top-down traversal of the node hierarchy, starting from the root node down to its child nodes.\n\n1. **Traversal**:\n   - The method `processNodeTopDown` iterates over all objects within each node.\n   - For each object, it calls the `processObject` method.\n\n2. **Event Handling**:\n   - In `processObject`, an object is checked to see if it is listening for events using `obj->f_listening.getValue()`.\n   - If the object is listening (`true`), the event is handled by calling `obj->handleEvent(m_event)`.\n\n3. **Stopping Condition**:\n   - The propagation stops once an object handles the event, as indicated by the call to `m_event->isHandled()`. At this point, the method returns `Visitor::RESULT_PRUNE`, indicating that further traversal can be pruned.\n\n#### Numerical Methods and Discretization Choices:\nThe `PropagateEventVisitor` does not encode any specific numerical methods or discretization choices directly related to FEM. Its function is purely in ensuring that events are appropriately distributed and handled within the simulation hierarchy.\n\n#### Integration into Variational/Lagrangian Mechanics Framework:\nWhile the `PropagateEventVisitor` itself does not contribute to the variational formulation or Lagrangian mechanics framework, it supports the overall structure of the SOFA pipeline by ensuring that all components can communicate effectively. This is crucial for maintaining consistency and coordination across different parts of a simulation involving deformable bodies and complex interactions.\n\n### Summary:\nThe `PropagateEventVisitor` is an essential component in the SOFA framework for propagating events through the simulation hierarchy, ensuring proper communication between nodes and objects. It does not directly contribute to mathematical operators or numerical methods associated with FEM but plays a critical role in maintaining the integrity of the simulation environment.",
  "abstract": "`PropagateEventVisitor` propagates events through the simulation data structure top-down until an object handles the event, ensuring proper communication between nodes and objects in SOFA simulations.",
  "sheet": "# PropagateEventVisitor\n\n## Overview\nThe `PropagateEventVisitor` is a visitor component used to propagate events within the SOFA framework. It operates on a top-down traversal starting from the root node until an object handles the event, ensuring effective communication between nodes and objects in the simulation hierarchy.\n\n## Dependencies and Connections\nThis component interacts with `Node` and `BaseObject`. The method `processNodeTopDown` iterates over all objects within a node, calling `processObject`, which checks if an object is listening for events. If so, it handles the event using the `handleEvent` function."
}