Methods

{
  "name": "MechanicalComputeEnergyVisitor",
  "namespace": "sofa::simulation::mechanicalvisitor",
  "module": "Sofa.framework.Simulation.Core",
  "include": "sofa/simulation/mechanicalvisitor/MechanicalComputeEnergyVisitor.h",
  "doc": "Compute the amount of mechanical energy\n\t@author Francois Faure",
  "inherits": [
    "MechanicalVisitor"
  ],
  "templates": [],
  "data_fields": [],
  "links": [],
  "methods": [
    {
      "name": "getKineticEnergy",
      "return_type": "SReal",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "getPotentialEnergy",
      "return_type": "SReal",
      "params": [],
      "is_virtual": false,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "fwdMass",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "mass",
          "type": "sofa::core::behavior::BaseMass *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "fwdForceField",
      "return_type": "Result",
      "params": [
        {
          "name": "",
          "type": "simulation::Node *"
        },
        {
          "name": "f",
          "type": "sofa::core::behavior::BaseForceField *"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    },
    {
      "name": "execute",
      "return_type": "void",
      "params": [
        {
          "name": "c",
          "type": "sofa::core::objectmodel::BaseContext *"
        },
        {
          "name": "precomputedTraversalOrder",
          "type": "bool"
        }
      ],
      "is_virtual": true,
      "is_pure_virtual": false,
      "is_static": false,
      "access": "public"
    }
  ],
  "description": "The `MechanicalComputeEnergyVisitor` is a component in the SOFA framework designed to compute the mechanical energy (kinetic and potential) within a simulation. It inherits from `sofa::simulation::MechanicalVisitor`. This visitor aggregates kinetic energy from mass models (`BaseMass`) and potential energy from force fields (`BaseForceField`). It interacts with other components by traversing the scene graph, accumulating energy values during its execution. The `getKineticEnergy` and `getPotentialEnergy` methods provide access to the computed energies. The component is typically used in debugging or profiling scenarios where mechanical energy monitoring is required.",
  "maths": "The `MechanicalComputeEnergyVisitor` is a visitor component in the SOFA framework designed to compute the mechanical energy (kinetic and potential) within a simulation. Its role is to aggregate kinetic energy from mass models (`BaseMass`) and potential energy from force fields (`BaseForceField`). The computed energies are stored as internal state variables `m_kineticEnergy` and `m_potentialEnergy`, respectively, which can be accessed via the public methods `getKineticEnergy()` and `getPotentialEnergy()`.\n\n### Governing Equations\n\n1. **Kinetic Energy**:\nThe kinetic energy is computed by summing contributions from all mass models in the simulation. Mathematically, for a system with multiple masses, the total kinetic energy can be expressed as:\n\begin{equation}\nT = \\sum_{i} T_i = \\frac{1}{2} \\sum_{i} m_i v_i^2\n\\end{equation}\nwhere $m_i$ and $v_i$ are the mass and velocity of each point, respectively.\n\nThe `fwdMass` method updates the kinetic energy by adding contributions from a given `BaseMass` object:\n\begin{equation}\nm_{\\text{kineticEnergy}} += m_{i}\\cdot \\frac{1}{2} v_i^2\n\\end{equation}\n\n2. **Potential Energy**:\nThe potential energy is computed by summing contributions from all force fields in the simulation. Mathematically, for a system with multiple force fields, the total potential energy can be expressed as:\n\begin{equation}\nV = \\sum_{j} V_j\n\\end{equation}\nwhere $V_j$ is the potential energy contribution of each force field.\n\nThe `fwdForceField` method updates the potential energy by adding contributions from a given `BaseForceField` object:\n\begin{equation}\nm_{\\text{potentialEnergy}} += V_j\n\\end{equation}\n\n### Constitutive or Kinematic Laws Involved\n\n- **Kinetic Energy**: The kinetic energy depends on the mass and velocity of the system. This is a direct consequence of Newtonian mechanics.\n\n- **Potential Energy**: The potential energy depends on the specific force field model, which can include elastic, gravitational, electrostatic, or other types of forces depending on the application.\n\n### Role in the Global FEM Pipeline\n\nThis component plays a role in post-processing and analysis rather than directly contributing to the core simulation steps such as assembly, time integration, nonlinear solve, linear solve, constraint handling, mapping, etc. Specifically, it accumulates energy values during its traversal of the scene graph.\n\n- **Assembly Phase**: The visitor does not actively participate in assembling global matrices or vectors; instead, it aggregates already computed contributions from individual mass models and force fields.\n\n- **Time Integration**: It is used post-integration to compute total energy for analysis purposes.\n\n### Numerical Methods or Discretization Choices\n\nThe `MechanicalComputeEnergyVisitor` does not implement any specific numerical methods or discretization choices. Instead, it relies on the internal implementations of `BaseMass` and `BaseForceField` components to provide the necessary energy contributions.\n\n### Fit into the Broader Variational / Lagrangian Mechanics Framework\n\nIn variational mechanics, the total mechanical energy (kinetic plus potential) is a conserved quantity in the absence of non-conservative forces. The visitor provides a means to monitor and verify this conservation property by summing up contributions from mass models and force fields.\n\nThe kinetic energy term arises from the Lagrangian formulation via the kinetic energy functional:\n\begin{equation}\nT(q, \\dot{q}) = \\sum_{i} \\frac{1}{2} m_i v_i^2\n\\end{equation}\nwhere $v_i$ is related to the generalized coordinates and velocities through the mass matrix.\n\nThe potential energy term arises from the potential energy functional:\n\begin{equation}\nV(q) = \\sum_{j} V_j(q)\n\\end{equation}\nwhere each $V_j(q)$ represents a contribution from an individual force field.",
  "abstract": "The `MechanicalComputeEnergyVisitor` computes mechanical energy (kinetic and potential) within a SOFA simulation by aggregating contributions from mass models and force fields.",
  "sheet": "\n# MechanicalComputeEnergyVisitor\n\n## Overview\n\nThe `MechanicalComputeEnergyVisitor` is a visitor component in the SOFA framework designed to compute the total mechanical energy (kinetic and potential) within a simulation. It aggregates kinetic energy from mass models (`BaseMass`) and potential energy from force fields (`BaseForceField`). This component interacts with other components by traversing the scene graph, accumulating energy values during its execution.\n\n## Mathematical Model\n\nThe `MechanicalComputeEnergyVisitor` computes mechanical energy using the following governing equations:\n\n### Kinetic Energy\n\nThe kinetic energy is computed by summing contributions from all mass models in the simulation. Mathematically, for a system with multiple masses, the total kinetic energy can be expressed as:\n\\[ T = \\sum_{i} T_i = \\frac{1}{2} \\sum_{i} m_i v_i^2 \\]\nwhere $m_i$ and $v_i$ are the mass and velocity of each point, respectively.\n\nThe `fwdMass` method updates the kinetic energy by adding contributions from a given `BaseMass` object:\n\\[ m_{\\text{kineticEnergy}} += m_{i} \\cdot \\frac{1}{2} v_i^2 \\]\n\n### Potential Energy\n\nThe potential energy is computed by summing contributions from all force fields in the simulation. Mathematically, for a system with multiple force fields, the total potential energy can be expressed as:\n\\[ V = \\sum_{j} V_j \\]\nwhere $V_j$ is the potential energy contribution of each force field.\n\nThe `fwdForceField` method updates the potential energy by adding contributions from a given `BaseForceField` object:\n\\[ m_{\\text{potentialEnergy}} += V_j \\]\n"
}