F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

energy: Documentation fixes

Browse Source
This commit is contained in:
Alberto Gallegos Ramonet
2023-07-26 15:05:40 +09:00
parent 1da18cbf93
commit 574f5839ff
1 changed files with 55 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

162
src/energy/doc/energy.rst
View File

@@ -23,11 +23,11 @@ The framework is implemented into the ``src/energy/`` folder.
The |ns3| energy framework is composed of 3 essential parts:
* Energy source models. Represent storing energy sources such as batteries or capacitors.
* **Energy source models.** Represent storing energy sources such as batteries or capacitors.
* Energy consumption models. Represent a portion of a device that draws energy from energy sources. Examples of this include sensors, radio transceivers, vehicles, UAV, etc.
* **Energy consumption models.** Represent a portion of a device that draws energy from energy sources. Examples of this include sensors, radio transceivers, vehicles, UAV, etc.
* Energy harvesting models. Represent devices that provide energy to energy sources. For example, solar panels and chargers.
* **Energy harvesting models.** Represent devices that provide energy to energy sources. For example, solar panels and chargers.
.. _fig-energyFramework:
@@ -49,18 +49,10 @@ the node such that each device energy model can react to this event. Further, ea
can access the energy source objects for information such as remaining capacity , voltage or
state of charge (SoC). This enables the implementation of energy aware protocols in ns-3.
In order to model a wide range of power supplies such as batteries,
the energy source must be able to capture characteristics of these
supplies. There are 2 important characteristics or effects related to
practical batteries:
In order to model a wide range of power supplies such as batteries, the energy source must be able to capture characteristics of these supplies. There are 2 important characteristics or effects related to practical batteries:
Rate Capacity Effect
Decrease of battery lifetime when the current draw is higher
than the rated value of the battery.
Recovery Effect
Increase of battery lifetime when the battery is alternating
between discharge and idle states.
* **Rate Capacity Effect.** Decrease of battery lifetime when the current draw is higher than the rated value of the battery.
* **Recovery Effect.** Increase of battery lifetime when the battery is alternating between discharge and idle states.
In order to incorporate the Rate Capacity Effect, the Energy Source
uses current draw from all the devices on the same node to calculate
@@ -73,12 +65,7 @@ Device Energy Model will notify the Energy Source of this change and
new total current draw will be calculated. Similarly, every Energy
Harvester update triggers an update to the connected Energy Source.
The ``EnergySource`` base class keeps a list of devices (``DeviceEnergyModel``
objects) and energy harvesters (``EnergyHarvester`` objects) that
are using the particular Energy Source as power supply. When energy is
completely drained, the Energy Source will notify all devices on this
list. Each device can then handle this event independently, based on
the desired behavior that should be followed in case of power outage.
The ``EnergySource`` base class keeps a list of devices (``DeviceEnergyModel`` objects) and energy harvesters (``EnergyHarvester`` objects) that are using the particular Energy Source as power supply. When energy is completely drained, the Energy Source will notify all devices on this list. Each device can then handle this event independently, based on the desired behavior that should be followed in case of power outage.
Generic Batttery Model
######################
@@ -104,6 +91,7 @@ discharge curves datasheets.
|ns3| Generic Battery Model Points in battery discharge curve.
The 3 basic set of points that require identification in a datasheet are:
* :math:`V_{full}:` The full battery voltage
* :math:`Q:` The maximum battery capacity
@@ -115,17 +103,13 @@ The 3 basic set of points that require identification in a datasheet are:
Additionally, it is also necessary to set the values of:
:math:`R:` The battery impedance (The battery internal resistance)
:math:`i_{typical}:` The typical current value used to discharge the battery, this value is
used to calculate some of the constants used in the model.
:math:`cutoffVoltage:` Required if we desired to inform connected energy consumption models
that the battery has reached its discharged point.
:math:`i:` The discharge current used to discharge the battery. This value is provided by the
energy consumption model attached to the battery.
* :math:`R:` The battery impedance (The battery internal resistance)
* :math:`i_{typical}:` The typical current value used to discharge the battery, this value is used to calculate some of the constants used in the model.
* :math:`cutoffVoltage:` Required if we desired to inform connected energy consumption models that the battery has reached its discharged point.
* :math:`i:` The discharge current used to discharge the battery. This value is provided by the energy consumption model attached to the battery.
The value of :math:`R:` is typically included in the datatsheets, however, because
:math:`R` variability is not modeled in |ns3| (The resistance is fixed), it is necessary
to discretely adjust its value to obtain the desired discharge curves. :math:`i_{typical}:` can
The value of :math:`R` is typically included in the datatsheets, however, because :math:`R` variability is not modeled in |ns3| (The resistance is fixed), it is necessary
to discretely adjust its value to obtain the desired discharge curves. The value :math:`i_{typical}` can
be obtained by inferring its value from the discharged curves shown in datasheets. When modeling
the behavior of a new battery, it is important to chose values that satisfies more than one curve,
trial an error adjustments might be necessary to obtain the desired results.
@@ -161,7 +145,7 @@ Attributes:
* ``RvBatteryModelAlphaValue``: RV battery model alpha value.
* ``RvBatteryModelBetaValue``: RV battery model beta value.
* ``RvBatteryModelNumOfTerms``: The number of terms of the infinite sum for estimating battery level.
*
Basic Energy Source
###################
@@ -176,22 +160,13 @@ Attributes:
Energy Consumption Models
=========================
A device energy model is the energy consumption model of a device
installed on the node. It is designed to be a state based model where
each device is assumed to have a number of states, and each state is
associated with a power consumption value. Whenever the state of the
device changes, the corresponding device energy model will notify the
energy source of the new current draw of the device. The energy source
will then calculate the new total current draw and update the
remaining energy.
A device energy model can also be used for devices that do not have
finite number of states. For example, in an electric vehicle, the
current draw of the motor is determined by its speed. Since the
vehicle's speed can take continuous values within a certain range, it
is infeasible to define a set of discrete states of
operation. However, by converting the speed value into current draw
directly, the same set of device energy model APIs can still be used.
A ``DeviceEnergyModel`` is the energy consumption model of a device installed on the node.
It is designed to be a state based model where each device is assumed to have a number of states, and each state is associated with a power consumption value.
Whenever the state of the device changes, the corresponding ``DeviceEnergyModel`` will notify the associated ``EnergySourceModel`` of the new current draw of the device.
The ``EnergySourceModel`` will then calculate the new total current draw and update the remaining energy. A ``DeviceEnergyModel`` can also be used for devices that do not have finite number of states.
For example, in an electric vehicle, the current draw of the motor is determined by its speed.
Since the vehicle's speed can take continuous values within a certain range, it is infeasible to define a set of discrete states of operation.
However, by converting the speed value into current draw directly, the same set of ``DeviceEnergyModel`` APIs can still be used.
WiFi Radio Energy Model
#######################
@@ -284,8 +259,6 @@ access to the Energy Harvester objects in order to gather information
regarding the current harvestable power and the total energy harvested
by the harvester.
Helpers
=======
@@ -315,7 +288,7 @@ The ``GenericBatteryModelHelper`` can be used to easily install an energy source
node or node container of one of four types of chemestries (Li-Ion,Lead Acid, NiCd,NiMH).
Users must use one of the available presets that represent an specific battery.
::
:::
GenericBatteryModelHelper batteryHelper;
EnergySourceContainer
energySourceContainer = batteryHelper.Install(nodeContainer, PANASONIC_CGR18650DA_LION);
@@ -327,7 +300,7 @@ connected in series and 2 connected in parallel (2S,2P).
Another option is to manually configure the values that makes the preset:
::
:::
node = CreateObject<Node>();
devicesEnergyModel = CreateObject<SimpleDeviceEnergyModel>();
batteryModel = CreateObject<GenericBatteryModel>();
@@ -341,24 +314,31 @@ batteryModel->SetAttribute("InternalResistance", DoubleValue(0.0046)); // R
batteryModel->SetAttribute("TypicalDischargeCurrent", DoubleValue(1.3)); // i typical
batteryModel->SetAttribute("CutoffVoltage", DoubleValue(1.0)); // End of charge.
batteryModel->SetAttribute("BatteryType", EnumValue(NIMH_NICD));
batteryModel = DynamicCast<GenericBatteryModel>
(batteryHelper.Install(node,PANASONIC_HHR650D_NIMH));
batteryModel = DynamicCast<GenericBatteryModel>(batteryHelper.Install(node,PANASONIC_HHR650D_NIMH));
devicesEnergyModel->SetEnergySource(batteryModel);
batteryModel->AppendDeviceEnergyModel(devicesEnergyModel);
devicesEnergyModel->SetNode(node);
Usage of both of these type of configurations are shown in ``generic-battery-discharge-example.cc``.
The following table is a list of the available presents in |ns3|:
+---------------------------+-------------------------------------------------+
| Preset Name | Description |
+===========================+=================================================+
| PANASONIC_CGR18650DA_LION | Panasonic Li-Ion (3.6V, 2450Ah, Size A) |
+---------------------------+-------------------------------------------------+
| PANASONIC_HHR650D_NIMH | Panasonic NiMh HHR550D (1.2V 6.5Ah, Size D) |
+---------------------------+-------------------------------------------------+
| CSB_GP1272_LEADACID | CSB Lead Acid GP1272 (12V,7.2Ah) |
+---------------------------+-------------------------------------------------+
| PANASONIC_N700AAC_NICD | Panasonic NiCd N-700AAC (1.2V 700mAh, Size: AA) |
+---------------------------+-------------------------------------------------+
| RSPRO_LGP12100_LEADACID | Rs Pro Lead Acid LGP12100 (12V, 100Ah) |
+---------------------------+-------------------------------------------------+
Tracing
=======
@@ -400,7 +380,7 @@ Examples in ``src/energy/examples``:
Examples in ``examples/energy``:
* ``energy-model-example.cc``
* ``energy-model-with-harvesting-example.cc``
* ``energy-model-with-harvesting-example.cc``: Shows the harvesting model usage. Only usable with basicEnergySources.
Tests
@@ -411,10 +391,7 @@ The following tests have been written, which can be found in ``src/energy/tests/
Validation
**********
- The RV battery model is validated by comparing results with what was presented in the original RV battery model paper.
- The generic battery model is validated by superimposing the obtained discharge curves with manufacters's datasheets plots.
The following shows the results of the ``generic-battery-discharge-example.cc`` superimposed to manufacter's datasheets charts:
The RV battery model is validated by comparing results with what was presented in the original RV battery model paper. The generic battery model is validated by superimposing the obtained discharge curves with manufacters's datasheets plots. The following shows the results of the ``generic-battery-discharge-example.cc`` superimposed to manufacter's datasheets charts:
.. _fig-leadacid:
@@ -446,75 +423,46 @@ Validation
Scope and Limitations
=====================
- In the ``GenericBatteryModel`` charging behavior (voltage as a function of SoC) is included but is not been thoroughly tested. Testing requires the implementation of a
harvesting device (A charger) capable of providing a CCCV charging method typically used in batteries.
- In the ``GenericBatteryModel`` impedance (battery resistance) is constant, battery aging or temperature effects are not considered.
- The Rv battery model has some reported issues (See: issue #164)
- The harvesting mode can only be used with basic energy sources because it does not consider the current capacity or voltage of the battery.
* In the ``GenericBatteryModel`` charging behavior (voltage as a function of SoC) is included but is not been thoroughly tested. Testing requires the implementation of a harvesting device (A charger) capable of providing a CCCV charging method typically used in batteries.
* In the ``GenericBatteryModel`` impedance (battery resistance) is constant, battery aging or temperature effects are not considered.
* The Rv battery model has some reported issues (See: issue #164)
* The harvesting mode can only be used with basic energy sources because it does not consider the current capacity or voltage of the battery.
Future Work
===========
- Support of device energy models for PHY layers (lr-wpan, WiMax, etc) and other pieces of hardware (UAV, sensors, CPU).
- Support for realistical charging batteries in the ``GenericBatteryModule``.
- Support for device capable of charging batteries (e.g. chargers with CCCV capabilities).
- Implement an energy harvester that recharges the energy sources according to the power levels defined in a user customizable dataset
of real measurements.
* Support of device energy models for PHY layers (lr-wpan, WiMax, etc) and other pieces of hardware (UAV, sensors, CPU).
* Support for realistical charging batteries in the ``GenericBatteryModule``.
* Support for device capable of charging batteries (e.g. chargers with CCCV capabilities).
* Implement an energy harvester that recharges the energy sources according to the power levels defined in a user customizable dataset of real measurements.
References
==========
Energy source models and energy consumption models:
[1] H. Wu, S. Nabar and R. Poovendran. An Energy Framework for the
Network Simulator 3 (ns-3).
[`1 <https://labs.ece.uw.edu/nsl/papers/SIMUTools-11.pdf>`_] H. Wu, S. Nabar and R. Poovendran. An Energy Framework for the Network Simulator 3 (ns-3).
[2] M. Handy and D. Timmermann. Simulation of mobile wireless
networks with accurate modelling of non-linear battery effects. In
Proc. of Applied simulation and Modeling (ASM), 2003.
[2] M. Handy and D. Timmermann. Simulation of mobile wireless networks with accurate modelling of non-linear battery effects. In Proc. of Applied simulation and Modeling (ASM), 2003.
[3] D. N. Rakhmatov and S. B. Vrudhula. An analytical high-level
battery model for use in energy management of portable electronic
systems. In Proc. of IEEE/ACM International Conference on Computer
Aided Design (ICCAD'01), pages 488-493, November 2001.
[3] D. N. Rakhmatov and S. B. Vrudhula. An analytical high-level battery model for use in energy management of portable electronic systems. In Proc. of IEEE/ACM International Conference on Computer Aided Design (ICCAD'01), pages 488-493, November 2001.
[4] D. N. Rakhmatov, S. B. Vrudhula, and D. A. Wallach. Battery
lifetime prediction for energy-aware computing. In Proc. of the 2002
International Symposium on Low Power Electronics and Design
(ISLPED'02), pages 154-159, 2002.
[4] D. N. Rakhmatov, S. B. Vrudhula, and D. A. Wallach. Battery lifetime prediction for energy-aware computing. In Proc. of the 2002 International Symposium on Low Power Electronics and Design (ISLPED'02), pages 154-159, 2002.
[5] Olivier Tremblay and Louis-A. Dessaint. 2009. Experimental
Validation of a Battery Dynamic Model for EV Applications.
World Electric Vehicle Journal 3, 2 (2009), 289–298.
https://doi.org/10.3390/wevj3020289
[`5 <https://www.mdpi.com/2032-6653/3/2/289>`_] Olivier Tremblay and Louis-A. Dessaint. 2009. Experimental Validation of a Battery Dynamic Model for EV Applications. World Electric Vehicle Journal 3, 2 (2009), 289–298. https://doi.org/10.3390/wevj3020289
[6] Olivier Tremblay, Louis-A. Dessaint, and Abdel-Illah Dekkiche.
2007. A Generic Battery Model for the Dynamic Simulation
of Hybrid Electric Vehicles. In 2007 IEEE Vehicle Power and
Propulsion Conference. 284–289.
https://doi.org/10.1109/VPPC.2007.4544139
[`6 <https://ieeexplore.ieee.org/document/4544139>`_] Olivier Tremblay, Louis-A. Dessaint, and Abdel-Illah Dekkiche. 2007. A Generic Battery Model for the Dynamic Simulation of Hybrid Electric Vehicles. In 2007 IEEE Vehicle Power and Propulsion Conference. 284–289. https://doi.org/10.1109/VPPC.2007.4544139
[7] https://www.mathworks.com/help/sps/powersys/ref/battery.html
[`7 <https://www.mathworks.com/help/sps/powersys/ref/battery.html>`_] MatWorks SimuLink Generic Battery Model
[8] C. M. Shepherd. 1965. Design of Primary and Secondary Cells:
II . An Equation Describing Battery Discharge. Journal of The
Electrochemical Society 112, 7 (jul 1965), 657.
https://doi.org/10.1149/1.2423659
[8] C. M. Shepherd. 1965. Design of Primary and Secondary Cells: II . An Equation Describing Battery Discharge. Journal of The Electrochemical Society 112, 7 (jul 1965), 657. https://doi.org/10.1149/1.2423659
[`9 <https://dl.acm.org/doi/abs/10.1145/3592149.3592156>`_] Alberto Gallegos Ramonet, Alexander Guzman Urbina, and Kazuhiko Kinoshita. 2023. Evaluation and Extension of ns-3 Battery Framework. In Proceedings of the 2023 Workshop on ns-3 (WNS3 '23). Association for Computing Machinery, New York, NY, USA, 102–108. https://doi.org/10.1145/3592149.3592156
[9] Alberto Gallegos Ramonet, Alexander Guzman Urbina, and
Kazuhiko Kinoshita. 2023. Evaluation and Extension of ns-3 Battery Framework.
In Proceedings of the 2023 Workshop on ns-3 (WNS3 '23).
Association for Computing Machinery, New York, NY, USA, 102–108.
https://doi.org/10.1145/3592149.3592156
Energy Harvesting Models:
[10] C. Tapparello, H. Ayatollahi and W. Heinzelman. Extending the Energy Framework for Network Simulator 3 (ns-3). Workshop on ns-3 (WNS3), Poster Session, Atlanta, GA, USA. May, 2014.
[10] C. Tapparello, H. Ayatollahi and W. Heinzelman. Extending the
Energy Framework for Network Simulator 3 (ns-3). Workshop on ns-3
(WNS3), Poster Session, Atlanta, GA, USA. May, 2014.
[11] C. Tapparello, H. Ayatollahi and W. Heinzelman. Energy Harvesting Framework for Network Simulator 3 (ns-3). 2nd International Workshop on Energy Neutral Sensing Systems (ENSsys), Memphis, TN, USA. November 6, 2014.
[11] C. Tapparello, H. Ayatollahi and W. Heinzelman. Energy Harvesting
Framework for Network Simulator 3 (ns-3). 2nd International Workshop on
Energy Neutral Sensing Systems (ENSsys), Memphis, TN, USA. November 6,
2014.