.. _energy_calculations_ref:

=======================
Energy calculations
=======================
The energy of rigid bodies,  constraints and motors can be reached using the energy manager of a simulation. Tutorials
of using energy calculations with rigid bodies, constraints or drive train motors are located in
**tutorials/agxOSG/tutorial_energyManager.cpp**.

.. code-block:: c++

    agxSDK::EnergyManager* energyManager = simulation->getEnergyManager();

------------
Rigid bodies
------------
To be able to read the energy change of a rigid body it first has to be added to the **agxSDK::EnergyManager**.

.. code-block:: c++

  energyManager->add( rigidBody );

Once added the energy manager will perform calculations to get

 * The gravity potential change
 * The dissipated energy from linear and angular velocity damping and external forces

.. note::
  All external forces will be considered dissipative.

The energy changes during the last time step can be reached with the following code:

.. code-block:: c++

  agx::Real potentialChange = energyManager->getPotentialChange( rigidBody );
  agx::Real dissipation = energyManager->Dissipation( rigidBody );

It is possible to get both the change in kinetic energy and the total kinetic energy of a rigid body. The total kinetic
energy can be reached with a static method and thus the rigid body does not have to be added to the energy manager for
this.

.. code-block:: c++

  // Get the kinetic energy change during the last time step.
  agx::Real energy = energyManager->getKineticEnergyChange( rigidBody );
  agx::Real energy = energyManager->getTranslationalEnergyChange( rigidBody );
  agx::Real energy = energyManager->getRotationalEnergyChange( rigidBody );

  // Get The total kinetic energy of a rigid body. The rigid body does not have to be added to the energy manager.
  agx::Real energy = agxSDK::EnergyManager::getKineticEnergy( rigidBody );
  agx::Real energy = agxSDK::EnergyManager::getTranslationalEnergy( rigidBody );
  agx::Real energy = agxSDK::EnergyManager::getRotationalEnergy( rigidBody );

.. attention::
  :code:`getKineticEnergyChange`, :code:`getPotentialChange` and :code:`getDissipation` will return a change of energy
  during the last time step while :code:`getKineticEnergy` will return the current energy.

-----------
Constraints
-----------
For constraints we get the change in potential energy and dissipation. The constraint first has to be added to the
energy manager.

.. code-block:: c++

  energyManager->add( constraint );

The energy change from the previous time step can be reached by the following calls.

.. code-block:: c++

  agx::Real potentialChange = energyManager->getPotentialChange( constraint );
  agx::Real dissipation = energyManager->getDissipation( constraint );

It is also possible to get dissipation, potential change and power from the secondary constraints. The :code:`getPower`
method is mainly used to get energy consumption from constraint motors such as **Motor1D** or
**ElectricMotorController**.

.. code-block:: c++

  energyManager->getPotentialChange( secondaryConstraint );
  energyManager->getDissipation( secondaryConstraint );
  energyManager->getPower( secondaryConstraint );

-----------------
DriveTrain motors
-----------------
For a motor it is possible to look att the power and the work done. A motor does not store any potential energy so all
the work done by the motor is dissipative.

Energy calculations for drive train motors are supported for

 - agxDriveTrain::ElectricMotor
 - agxDriveTrain::Engine
 - agxDriveTrain::FixedVelocityEngine
 - agxDriveTrain::CombustionEngine

Add them to the **agx::DriveTrain::EnergyManager**.

.. code-block:: c++

  agxDriveTrain::EnergyManager::add( motor );

The motor will be added to the energy manager of the simulation that the power line is added to. If the power line is
not added to a simulation or if the motor has not been added to a power line it is also necessary to specify which
simulation you want to use.

.. code-block:: c++

  agxDriveTrain::EnergyManager::add( motor, simulation );

The power and work done can be accessed with the following methods.

.. code-block:: cpp

  agx::Real work = agxDriveTrain::EnergyManager::getWorkDone( motor );
  agx::Real power = agxDriveTrain::EnergyManager::getPower( motor );

-----------------
Known limitations
-----------------
 - All external forces on a rigid body are considered to be dissipative.
 - The separation of conservative och dissipative work done by constraints works for

   * Soft elastic constraints
   * Stiff constraints with consistent initial conditions (non-violated and with a velocities tangent to the constraint)

 - An added force on a drive train motor's rigid body will also add to the work done and the power of that motor.