CREATE OR REPLACE PACKAGE BODY EFT_NOM.cout_energy_calculations IS

  /**
  -- Purpose : Utilities for energy and volume calculations
  -- #version $Revision: 1 $
  -- #author $Author: Gilberta $
  -- Created : 13/09/2004 09:39:11
  */

  /*
  $Header: /Isle Of Grain/database/PLSQL/cout_energy_calculations.pck 1     7/01/05 12:54 Gilberta $  Logfile, Revision, Date, Author

  $Date: 7/01/05 12:54 $  Date and time of last checkin
  $Modtime: 4/01/05 16:41 $  Date and time of last modification

  $History: cout_energy_calculations.pck $
 *
 * *****************  Version 1  *****************
 * User: Gilberta     Date: 7/01/05    Time: 12:54
 * Created in $/Isle Of Grain/database/PLSQL
 * Initial Version
  */

  FUNCTION energy_to_volume(p_energy                IN NUMBER
                           ,p_cv                    IN NUMBER
                           ,p_energy_unit_of_size   IN cout_units_of_measure.g_t_si_prefix DEFAULT cout_units_of_measure.g_c_kilo
                           ,p_energy_derived_unit   IN cout_units_of_measure.g_t_joule_or_watthour DEFAULT cout_units_of_measure.g_c_watthour
                           ,p_cv_unit_of_size       IN cout_units_of_measure.g_t_si_prefix DEFAULT cout_units_of_measure.g_c_mega
                           ,p_cv_unit_quantity      IN cout_units_of_measure.g_t_volume_or_mass DEFAULT cout_units_of_measure.g_c_volume
                           ,p_cv_density_of_lng     IN NUMBER DEFAULT 424.5 -- kg per cubic metre
                           ,p_unit_of_size_required IN cout_units_of_measure.g_t_si_prefix DEFAULT cout_units_of_measure.g_c_mega)
    RETURN NUMBER IS
    /*
    * Notes:
    * One watt is equal to one joule per second.
    * Therefore, 1 watt hour (Wh) is equivalent to exactly 3.6 kilojoule (kJ) of energy.
    * Calorific Value (CV) is the ratio of:
    *                         energy (Joules) to volume (cubic metres), OR
    *                         energy (Joules) to mass (kilograms)
    *
    */
    l_c_seconds_in_hour CONSTANT NUMBER := 60 * 60;

    l_energy_j            NUMBER;
    l_cv                  NUMBER := p_cv * p_cv_unit_of_size;
    l_volume_cubic_metres NUMBER;
    l_substitution_list   cout_err.g_t_substitution_list;

  BEGIN
    --
    l_substitution_list(1) := 'CV';
    cout_assert.istrue(p_cv > 0
                      ,p_exception => -20051
                      ,p_message => 'CV must be a positive non-zero value'
                      ,p_substitution_list => l_substitution_list);

    l_substitution_list(1) := 'Energy Unit of Size';
    cout_assert.isnotnull(p_energy_unit_of_size
                         ,p_exception => -20100
                         ,p_message => 'Energy unit of size must not be null');

    l_substitution_list(1) := 'Energy Unit of Size Required';
    cout_assert.isnotnull(p_unit_of_size_required
                         ,p_exception => -20100
                         ,p_message => 'Unit of size required must not be null'
                         ,p_substitution_list => l_substitution_list);

    l_substitution_list(1) := p_cv_unit_quantity;
    l_substitution_list(2) := 'CV Unit Quantity';
    cout_assert.istrue(p_cv_unit_quantity IN
                       (cout_units_of_measure.g_c_volume,
                        cout_units_of_measure.g_c_mass)
                      ,'CV unit quantity invalid, expect ' ||
                       cout_units_of_measure.g_c_volume || ' or ' ||
                       cout_units_of_measure.g_c_mass || ', got ' ||
                       p_cv_unit_quantity
                      ,p_exception => -20101
                      ,p_substitution_list => l_substitution_list);

    l_substitution_list(1) := 'CV Unit of Size';
    cout_assert.isnotnull(p_cv_unit_of_size
                         ,p_exception => -20100
                         ,p_message => 'CV unit of size must not be null');

    l_substitution_list(1) := 'CV Density';
    cout_assert.istrue(p_cv_density_of_lng > 0
                      ,p_exception => -20051
                      ,p_message => 'CV density must be a positive non-zero value'
                      ,p_substitution_list => l_substitution_list);

    l_substitution_list(1) := p_energy_derived_unit;
    l_substitution_list(2) := 'Energy Derived Unit';
    cout_assert.istrue(p_energy_derived_unit IN
                       (cout_units_of_measure.g_c_watthour,
                        cout_units_of_measure.g_c_joule)
                      ,'Energy derived unit invalid, expect ' ||
                       cout_units_of_measure.g_c_joule || ' or ' ||
                       cout_units_of_measure.g_c_watthour || ', got ' ||
                       p_energy_derived_unit
                      ,p_substitution_list => l_substitution_list);

    IF p_energy_derived_unit = cout_units_of_measure.g_c_watthour THEN
      l_energy_j := p_energy * l_c_seconds_in_hour;
    ELSE
      l_energy_j := p_energy;
    END IF;

    l_energy_j := l_energy_j * p_energy_unit_of_size;

    IF p_cv_unit_quantity = cout_units_of_measure.g_c_volume THEN
      --
      -- CV = energy(J)/volume(m3)
      -- therefore, volume(m3) = energy(J)/CV
      --
      l_volume_cubic_metres := l_energy_j / l_cv;

    ELSIF p_cv_unit_quantity = cout_units_of_measure.g_c_mass THEN
      --
      -- CV = energy(J)/mass(kg)
      -- mass = density * volume
      -- therefore, volume(m3) = energy(J) / (density * CV)
      --
      l_volume_cubic_metres := l_energy_j / (p_cv_density_of_lng * l_cv);
    END IF;

    RETURN l_volume_cubic_metres / p_unit_of_size_required;

  END energy_to_volume;

  FUNCTION kwh_to_mcm(p_energy IN NUMBER
                     ,p_cv     IN NUMBER) RETURN NUMBER IS
  BEGIN
    RETURN energy_to_volume(p_energy                => p_energy
                           ,p_cv                    => p_cv
                           ,p_energy_unit_of_size   => cout_units_of_measure.g_c_kilo
                           ,p_energy_derived_unit   => cout_units_of_measure.g_c_watthour
                           ,p_cv_unit_of_size       => cout_units_of_measure.g_c_mega
                           ,p_cv_unit_quantity      => cout_units_of_measure.g_c_volume
                           ,p_unit_of_size_required => cout_units_of_measure.g_c_mega);
  END kwh_to_mcm;

  FUNCTION kwh_to_cm(p_energy IN NUMBER
                    ,p_cv     IN NUMBER) RETURN NUMBER IS
  BEGIN
    RETURN energy_to_volume(p_energy                => p_energy
                           ,p_cv                    => p_cv
                           ,p_energy_unit_of_size   => cout_units_of_measure.g_c_kilo
                           ,p_energy_derived_unit   => cout_units_of_measure.g_c_watthour
                           ,p_cv_unit_of_size       => cout_units_of_measure.g_c_mega
                           ,p_cv_unit_quantity      => cout_units_of_measure.g_c_volume
                           ,p_unit_of_size_required => cout_units_of_measure.g_c_unit);
  END kwh_to_cm;

BEGIN
  -- Initialization
  NULL;
END cout_energy_calculations;
/