Methods

{
  "name": "MechanicalPropagateOnlyPositionAndVelocityVisitor",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalPropagateOnlyPositionAndVelocityVisitor.h",
  "doc": "Propagate positions and velocities to all the levels of the hierarchy.\nAt each level, the mappings form the parent to the child is applied.\nAfter the execution of this action, all the (mapped) degrees of freedom are consistent with the independent degrees of freedom.\nThis action is typically applied after time integration of the independent degrees of freedom.\nNote that this visitor only propagate through the mappings, and does\nnot apply projective constraints as was previously done by\nMechanicalPropagatePositionAndVelocityVisitor.\nUse MechanicalProjectPositionAndVelocityVisitor before this visitor if\nprojection is needed.",
  "inherits": [
    "MechanicalVisitor"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "fwdMechanicalState",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "mm",
          "type": "sofa::core::behavior::BaseMechanicalState *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "fwdMechanicalMapping",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "map",
          "type": "sofa::core::BaseMapping *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "bwdMechanicalState",
      "return_type": "void",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "mm",
          "type": "sofa::core::behavior::BaseMechanicalState *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "stopAtMechanicalMapping",
      "return_type": "bool",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "",
          "type": "sofa::core::BaseMapping *"
        }
      ],
      "is_virtual": true,
      "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"
    },
    {
      "name": "isThreadSafe",
      "return_type": "bool",
      "params": [],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `MechanicalPropagateOnlyPositionAndVelocityVisitor` is a mechanical visitor in SOFA that propagates positions and velocities to all levels of the hierarchy within a simulation scene graph. This visitor applies mappings from parent nodes to child nodes, ensuring that all mapped degrees of freedom are consistent with the independent degrees of freedom after time integration.\n\nIt interacts primarily with `simulation::Node` and `core::BaseMapping`, using methods like `fwdMechanicalState` and `fwdMechanicalMapping`. The visitor only propagates through mappings and does not apply projective constraints, which were previously handled by the `MechanicalPropagatePositionAndVelocityVisitor`. If projection is needed, the `MechanicalProjectPositionAndVelocityVisitor` should be used before this visitor.\n\nThe component has no data fields or links but implements several methods including `fwdMechanicalState`, `bwdMechanicalState`, and `stopAtMechanicalMapping`. The class also specifies that it can be parallelized, as indicated by the `isThreadSafe` method returning true.",
  "maths": "The `MechanicalPropagateOnlyPositionAndVelocityVisitor` is a mechanical visitor in the SOFA framework that propagates positions and velocities to all levels of the simulation hierarchy. This ensures consistency between mapped degrees of freedom (DOFs) and independent DOFs after time integration.\n\n### Governing Equations and Operators\n- **Positions**: The component updates nodal position vectors \\(\bm{x}\\).\n- **Velocities**: The component also updates nodal velocity vectors \\(\bm{v}\\).\n\nThe propagation of positions and velocities is performed through mappings from parent to child nodes in the scene graph. This process can be mathematically represented as follows:\n\n1. Position Propagation:\n   \n   Let \\(x^p\\) represent the position vector at the parent node, and \\(x^c\\) represent the position vector at the child node. The mapping from parent to child is given by a transformation matrix or function \\(M_p \\to c\\):\n   \n   \n   \n   \\[ x^c = M_{p \\to c} (x^p) \\]\n\n2. Velocity Propagation:\n\n   Similarly, the velocity vector at the parent node is denoted by \\(\bm{v}^p\\), and at the child node by \\(\bm{v}^c\\). The propagation of velocities through mappings can be expressed as:\n   \n   \\[ \bm{v}^c = M_{p \\to c} (\bm{v}^p) \\]\n\n### Constitutive or Kinematic Laws Involved\n- **Mappings**: The visitor applies mappings between parent and child nodes. These mappings could include affine transformations, nonlinear mappings, or other interpolations depending on the specific implementation of `core::BaseMapping` in SOFA.\n- **Position Consistency**: Ensures that all mapped DOFs are consistent with independent DOFs after time integration.\n\n### Role in the Global FEM Pipeline\nThe visitor operates in the assembly phase and during state updates. Specifically:\n1. **Assembly Phase**: The mappings between nodes ensure consistency of positions and velocities throughout the hierarchy, which is crucial for maintaining physical coherence in a multi-level simulation setup.\n2. **Time Integration**: After time integration of independent DOFs (e.g., using implicit Euler or other schemes), this visitor ensures that dependent DOFs are updated accordingly.\n\n### Numerical Methods or Discretization Choices\n- The component does not directly contribute to the discretization methods such as FEM spatial discretization, weak form derivation, or element operator construction. Instead, it focuses on ensuring consistency across the hierarchy after the solution has been obtained at each level.\n\n### Integration into Variational / Lagrangian Mechanics Framework\nThe visitor plays a role in maintaining consistency and correctness of the state variables (positions and velocities) within the hierarchical structure of the simulation scene graph. This is essential for the overall stability and accuracy of the numerical solution, particularly when dealing with multi-resolution or embedded mesh configurations.\n\n### Summary\nThe `MechanicalPropagateOnlyPositionAndVelocityVisitor` ensures that positions and velocities are consistently propagated through mappings in a SOFA simulation hierarchy, maintaining consistency between mapped and independent DOFs. This component does not directly contribute to the governing equations of motion but is crucial for ensuring numerical stability and coherence across different levels of the scene graph.",
  "abstract": "The `MechanicalPropagateOnlyPositionAndVelocityVisitor` propagates positions and velocities through the hierarchy of nodes in a SOFA simulation, ensuring consistency between mapped degrees of freedom (DOFs) and independent DOFs after time integration.",
  "sheet": "# MechanicalPropagateOnlyPositionAndVelocityVisitor\n\n## Overview\nThe `MechanicalPropagateOnlyPositionAndVelocityVisitor` is a mechanical visitor that propagates positions and velocities through the hierarchy of nodes in a SOFA simulation. It ensures consistency between mapped degrees of freedom (DOFs) and independent DOFs after time integration by applying mappings from parent to child nodes.\n\n## Dependencies and Connections\nThis component interacts with `simulation::Node` and `core::BaseMapping`. Specifically, it uses methods like `fwdMechanicalState`, `bwdMechanicalState`, and `stopAtMechanicalMapping` to propagate positions and velocities through the hierarchy. The visitor does not apply projective constraints; if projection is needed, the `MechanicalProjectPositionAndVelocityVisitor` should be used before this visitor."
}