Methods

{
  "name": "MechanicalPropagateDxVisitor",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalPropagateDxVisitor.h",
  "doc": "Apply a hypothetical displacement.\nThis action does not modify the state (i.e. positions and velocities) of the objects.\nIt is typically applied before a MechanicalComputeDfVisitor, in order to compute the df corresponding to a given dx (i.e. apply stiffness).\nDx is propagated to all the layers through the mappings.",
  "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": "map",
          "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 `MechanicalPropagateDxVisitor` is a visitor in the SOFA framework designed to apply a hypothetical displacement (`dx`) without modifying the state (positions and velocities) of objects. It propagates this displacement across all layers through mappings, typically used before a `MechanicalComputeDfVisitor` to compute forces corresponding to the given displacement.\n\n**Role and Purpose**: This component is essential in mechanical simulations where it's necessary to propagate hypothetical displacements for force computation or stiffness application without altering the actual object state. It operates within the scene graph architecture, interacting with various components through its API methods.\n\n**Interactions with Other Components**:\n- **fwdMechanicalState**: This method processes a `BaseMechanicalState` at a given node and returns a result indicating whether to continue processing.\n- **fwdMechanicalMapping**: Applies the Jacobian transformation (`J`) to propagate displacement through mappings. The `dx` displacement is applied using the mapping's `applyJ` function.\n- **bwdMechanicalState**: This method processes backward mechanical state operations, currently marked as unused.\n- **stopAtMechanicalMapping**: Determines whether processing should stop at a given mechanical mapping based on flags and force-mapping conditions.\n- **getInfos**: Returns information about the visitor, including the name of the displacement vector (`dx`).\n\n**Practical Usage Guidance**: This component is generally used in conjunction with other mechanical visitors to facilitate the propagation of hypothetical displacements through various layers. It should be utilized in simulations where temporary state modifications are needed for force computation or stiffness evaluation without affecting actual object positions and velocities.",
  "maths": "The `MechanicalPropagateDxVisitor` is a visitor in the SOFA framework designed to propagate a hypothetical displacement vector, denoted as \\(\\mathbf{dx}\\), without modifying the actual mechanical state (i.e., positions and velocities) of the objects. This component plays a crucial role in computing forces or stiffness associated with the given hypothetical displacements.\n\n### Governing Equations/Operators\n- **Displacement Propagation**: The core operation performed by this visitor is the propagation of \\(\\mathbf{dx}\\) through mappings and mechanical states without altering the actual object state. Mathematically, this can be described as applying a Jacobian transformation to propagate \\(\\mathbf{dx}\\):\n  \n  Given a mapping \\(J\\), the displacement is propagated via:\n  \n  \\[ J(\text{params}) \times \text{dx} = \text{dx}' \\]\n\n- **Force Computation**: The hypothetical displacements are typically used before a `MechanicalComputeDfVisitor` to compute forces corresponding to these displacements. This is done in the context of nonlinear dynamics and stiffness application.\n  \n### Constitutive or Kinematic Laws Involved\n- **Strain Measures**: Although this visitor does not directly involve constitutive laws, it propagates hypothetical strains (displacements) \\(\\mathbf{dx}\\) through mappings which could be associated with various strain measures depending on the context of the simulation.\n  \n### Role in the Global FEM Pipeline\n- **Assembly Phase**: This component is involved during the assembly phase where displacements are propagated through mappings and mechanical states. It ensures that hypothetical displacements are correctly applied to all layers without modifying the actual object state, facilitating force computation or stiffness evaluation.\n- **Time Integration**: The visitor operates in a context where it supports time integration schemes by ensuring correct displacement propagation without altering actual positions and velocities, which is crucial for implicit integration methods like backward Euler.\n\n### Numerical Methods or Discretization Choices Encoded\n- **Jacobian Transformation**: This component encodes the Jacobian transformation (`applyJ`) to propagate displacements through mappings. The Jacobian matrix \\(J\\) represents the linearized mapping between layers, ensuring consistent displacement propagation across different mechanical states and mappings.\n\n### Fit into the Broader Variational/Lagrangian Mechanics Framework\n- **Variational Consistency**: By propagating hypothetical displacements without modifying actual state variables, this visitor supports variational consistency in simulations. This ensures that forces computed via `MechanicalComputeDfVisitor` are consistent with the applied displacements within a Lagrangian mechanics framework.\n  \nIn summary, the `MechanicalPropagateDxVisitor` is an essential component for propagating hypothetical displacements through mappings and mechanical states without altering actual object state, supporting force computation and stiffness evaluation in simulations.",
  "abstract": "The `MechanicalPropagateDxVisitor` propagates hypothetical displacements (`dx`) without altering the actual object state, facilitating force computation and stiffness evaluation through mappings and mechanical states.",
  "sheet": "# MechanicalPropagateDxVisitor\n\n**Overview**: The `MechanicalPropagateDxVisitor` is a visitor in SOFA that propagates hypothetical displacements (`dx`) without modifying the actual state (positions and velocities) of objects. It operates within the scene graph architecture, interacting with mappings and mechanical states to ensure consistent displacement propagation.\n\n**Mathematical Model**: The core operation involves applying Jacobian transformations to propagate hypothetical displacements through mappings. Given a mapping \\(J\\), the displacement is propagated via:\n\n\\[ J(\\text{params}) \\times \\mathbf{dx} = \\mathbf{dx}' \\]\n\nThis visitor supports force computation and stiffness evaluation by ensuring that hypothetical displacements are correctly applied to all layers without altering actual object state.\n\n**Dependencies and Connections**: This component typically requires mappings (`BaseMapping`) and mechanical states (`BaseMechanicalState`). It is used in conjunction with other mechanical visitors, such as `MechanicalComputeDfVisitor`, for force computation or stiffness evaluation.\n\n**Practical Notes**: The `MechanicalPropagateDxVisitor` is essential in simulations where temporary state modifications are needed for force computation or stiffness evaluation without affecting actual object positions and velocities."
}