A Discrete-Event Network Simulator
API
li-ion-energy-source.cc
Go to the documentation of this file.
1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
2 /*
3  * Copyright (c) 2010 Andrea Sacco
4  *
5  * This program is free software; you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License version 2 as
7  * published by the Free Software Foundation;
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software
16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17  *
18  * Author: Andrea Sacco <andrea.sacco85@gmail.com>
19  */
20 
21 #include "li-ion-energy-source.h"
22 #include "ns3/log.h"
23 #include "ns3/assert.h"
24 #include "ns3/double.h"
25 #include "ns3/trace-source-accessor.h"
26 #include "ns3/simulator.h"
27 
28 #include <cmath>
29 
30 namespace ns3 {
31 
32 NS_LOG_COMPONENT_DEFINE ("LiIonEnergySource");
33 
34 NS_OBJECT_ENSURE_REGISTERED (LiIonEnergySource);
35 
36 TypeId
38 {
39  static TypeId tid = TypeId ("ns3::LiIonEnergySource")
41  .SetGroupName ("Energy")
42  .AddConstructor<LiIonEnergySource> ()
43  .AddAttribute ("LiIonEnergySourceInitialEnergyJ",
44  "Initial energy stored in basic energy source.",
45  DoubleValue (31752.0), // in Joules
48  MakeDoubleChecker<double> ())
49  .AddAttribute ("LiIonEnergyLowBatteryThreshold",
50  "Low battery threshold for LiIon energy source.",
51  DoubleValue (0.10), // as a fraction of the initial energy
53  MakeDoubleChecker<double> ())
54  .AddAttribute ("InitialCellVoltage",
55  "Initial (maximum) voltage of the cell (fully charged).",
56  DoubleValue (4.05), // in Volts
59  MakeDoubleChecker<double> ())
60  .AddAttribute ("NominalCellVoltage",
61  "Nominal voltage of the cell.",
62  DoubleValue (3.6), // in Volts
64  MakeDoubleChecker<double> ())
65  .AddAttribute ("ExpCellVoltage",
66  "Cell voltage at the end of the exponential zone.",
67  DoubleValue (3.6), // in Volts
69  MakeDoubleChecker<double> ())
70  .AddAttribute ("RatedCapacity",
71  "Rated capacity of the cell.",
72  DoubleValue (2.45), // in Ah
74  MakeDoubleChecker<double> ())
75  .AddAttribute ("NomCapacity",
76  "Cell capacity at the end of the nominal zone.",
77  DoubleValue (1.1), // in Ah
79  MakeDoubleChecker<double> ())
80  .AddAttribute ("ExpCapacity",
81  "Cell Capacity at the end of the exponential zone.",
82  DoubleValue (1.2), // in Ah
84  MakeDoubleChecker<double> ())
85  .AddAttribute ("InternalResistance",
86  "Internal resistance of the cell",
87  DoubleValue (0.083), // in Ohms
89  MakeDoubleChecker<double> ())
90  .AddAttribute ("TypCurrent",
91  "Typical discharge current used to fit the curves",
92  DoubleValue (2.33), // in A
94  MakeDoubleChecker<double> ())
95  .AddAttribute ("ThresholdVoltage",
96  "Minimum threshold voltage to consider the battery depleted.",
97  DoubleValue (3.3), // in Volts
99  MakeDoubleChecker<double> ())
100  .AddAttribute ("PeriodicEnergyUpdateInterval",
101  "Time between two consecutive periodic energy updates.",
102  TimeValue (Seconds (1.0)),
105  MakeTimeChecker ())
106  .AddTraceSource ("RemainingEnergy",
107  "Remaining energy at BasicEnergySource.",
109  "ns3::TracedValueCallback::Double")
110  ;
111  return tid;
112 }
113 
115  : m_drainedCapacity (0.0),
116  m_lastUpdateTime (Seconds (0.0))
117 {
118  NS_LOG_FUNCTION (this);
119 }
120 
122 {
123  NS_LOG_FUNCTION (this);
124 }
125 
126 void
127 LiIonEnergySource::SetInitialEnergy (double initialEnergyJ)
128 {
129  NS_LOG_FUNCTION (this << initialEnergyJ);
130  NS_ASSERT (initialEnergyJ >= 0);
131  m_initialEnergyJ = initialEnergyJ;
132  // set remaining energy to be initial energy
134 }
135 
136 double
138 {
139  NS_LOG_FUNCTION (this);
140  return m_initialEnergyJ;
141 }
142 
143 void
145 {
146  NS_LOG_FUNCTION (this << supplyVoltageV);
147  m_eFull = supplyVoltageV;
148  m_supplyVoltageV = supplyVoltageV;
149 }
150 
151 double
153 {
154  NS_LOG_FUNCTION (this);
155  return m_supplyVoltageV;
156 }
157 
158 void
160 {
161  NS_LOG_FUNCTION (this << interval);
162  m_energyUpdateInterval = interval;
163 }
164 
165 Time
167 {
168  NS_LOG_FUNCTION (this);
169  return m_energyUpdateInterval;
170 }
171 
172 double
174 {
175  NS_LOG_FUNCTION (this);
176  // update energy source to get the latest remaining energy.
178  return m_remainingEnergyJ;
179 }
180 
181 double
183 {
184  NS_LOG_FUNCTION (this);
185  // update energy source to get the latest remaining energy.
188 }
189 
190 void
192 {
193  NS_LOG_FUNCTION (this << energyJ);
194  NS_ASSERT (energyJ >= 0);
195  m_remainingEnergyJ -= energyJ;
196 
197  // check if remaining energy is 0
199  {
201  }
202 }
203 
204 void
206 {
207  NS_LOG_FUNCTION (this << energyJ);
208  NS_ASSERT (energyJ >= 0);
209  m_remainingEnergyJ += energyJ;
210 }
211 
212 void
214 {
215  NS_LOG_FUNCTION (this);
216  NS_LOG_DEBUG ("LiIonEnergySource:Updating remaining energy at node #" <<
217  GetNode ()->GetId ());
218 
219  // do not update if simulation has finished
220  if (Simulator::IsFinished ())
221  {
222  return;
223  }
224 
226 
228 
230 
232  {
234  return; // stop periodic update
235  }
236 
239  this);
240 }
241 
242 /*
243  * Private functions start here.
244  */
245 void
247 {
248  NS_LOG_FUNCTION (this);
249  UpdateEnergySource (); // start periodic update
250 }
251 
252 void
254 {
255  NS_LOG_FUNCTION (this);
256  BreakDeviceEnergyModelRefCycle (); // break reference cycle
257 }
258 
259 
260 void
262 {
263  NS_LOG_FUNCTION (this);
264  NS_LOG_DEBUG ("LiIonEnergySource:Energy depleted at node #" <<
265  GetNode ()->GetId ());
266  NotifyEnergyDrained (); // notify DeviceEnergyModel objects
267 }
268 
269 
270 void
272 {
273  NS_LOG_FUNCTION (this);
274  double totalCurrentA = CalculateTotalCurrent ();
275  Time duration = Simulator::Now () - m_lastUpdateTime;
276  NS_ASSERT (duration.GetSeconds () >= 0);
277  // energy = current * voltage * time
278  double energyToDecreaseJ = totalCurrentA * m_supplyVoltageV * duration.GetSeconds ();
279 
280  if (m_remainingEnergyJ < energyToDecreaseJ)
281  {
282  m_remainingEnergyJ = 0; // energy never goes below 0
283  }
284  else
285  {
286  m_remainingEnergyJ -= energyToDecreaseJ;
287  }
288 
289  m_drainedCapacity += (totalCurrentA * duration).GetHours ();
290  // update the supply voltage
291  m_supplyVoltageV = GetVoltage (totalCurrentA);
292  NS_LOG_DEBUG ("LiIonEnergySource:Remaining energy = " << m_remainingEnergyJ);
293 }
294 
295 double
297 {
298  NS_LOG_FUNCTION (this << i);
299 
300  // integral of i in dt, drained capacity in Ah
301  double it = m_drainedCapacity;
302 
303  // empirical factors
304  double A = m_eFull - m_eExp;
305  double B = 3 / m_qExp;
306 
307  // slope of the polarization curve
308  double K = std::abs ( (m_eFull - m_eNom + A * (std::exp (-B * m_qNom) - 1)) * (m_qRated - m_qNom) / m_qNom);
309 
310  // constant voltage
311  double E0 = m_eFull + K + m_internalResistance * m_typCurrent - A;
312 
313  double E = E0 - K * m_qRated / (m_qRated - it) + A * std::exp (-B * it);
314 
315  // cell voltage
316  double V = E - m_internalResistance * i;
317 
318  NS_LOG_DEBUG ("Voltage: " << V << " with E: " << E);
319 
320  return V;
321 }
322 
323 } // namespace ns3
This class can be used to hold variables of floating point type such as 'double' or 'float'.
Definition: double.h:41
Introspection did not find any typical Config paths.
Definition: energy-source.h:87
Ptr< Node > GetNode(void) const
void BreakDeviceEnergyModelRefCycle(void)
This function is called to break reference cycle between EnergySource and DeviceEnergyModel.
double CalculateTotalCurrent(void)
void NotifyEnergyDrained(void)
This function notifies all DeviceEnergyModel of energy depletion event.
void Cancel(void)
This method is syntactic sugar for the ns3::Simulator::Cancel method.
Definition: event-id.cc:53
Model a generic Lithium Ion Battery basing on [1][2].
double m_drainedCapacity
capacity drained from the cell, in Ah
virtual void UpdateEnergySource(void)
Implements UpdateEnergySource.
void SetInitialEnergy(double initialEnergyJ)
virtual double GetInitialEnergy(void) const
void DoDispose(void)
All child's implementation must call BreakDeviceEnergyModelRefCycle to ensure reference cycles to Dev...
double m_minVoltTh
minimum threshold voltage to consider the battery depleted
virtual void IncreaseRemainingEnergy(double energyJ)
Time GetEnergyUpdateInterval(void) const
virtual double GetRemainingEnergy(void)
double m_supplyVoltageV
actual voltage of the cell
TracedValue< double > m_remainingEnergyJ
remaining energy, in Joules
double m_initialEnergyJ
initial energy, in Joules
double m_eFull
initial voltage of the cell, in Volts
void SetEnergyUpdateInterval(Time interval)
double m_internalResistance
internal resistance of the cell, in Ohms
void CalculateRemainingEnergy(void)
Calculates remaining energy.
Time m_energyUpdateInterval
energy update interval
virtual double GetSupplyVoltage(void) const
void SetInitialSupplyVoltage(double supplyVoltageV)
double m_eNom
nominal voltage of the cell, in Volts
double m_lowBatteryTh
low battery threshold, as a fraction of the initial energy
void HandleEnergyDrainedEvent(void)
Handles the remaining energy going to zero event.
double m_eExp
cell voltage at the end of the exponential zone, in Volts
virtual double GetEnergyFraction(void)
EventId m_energyUpdateEvent
energy update event
void DoInitialize(void)
Initialize() implementation.
double m_qNom
cell capacity at the end of the nominal zone, in Ah
double m_qExp
capacity value at the end of the exponential zone, in Ah
double GetVoltage(double current) const
double m_qRated
rated capacity of the cell, in Ah
static TypeId GetTypeId(void)
Get the type ID.
virtual void DecreaseRemainingEnergy(double energyJ)
double m_typCurrent
typical discharge current used to fit the curves
Time m_lastUpdateTime
last update time
static EventId Schedule(Time const &delay, FUNC f, Ts &&... args)
Schedule an event to expire after delay.
Definition: simulator.h:556
static bool IsFinished(void)
Check if the simulation should finish.
Definition: simulator.cc:165
static Time Now(void)
Return the current simulation virtual time.
Definition: simulator.cc:195
Simulation virtual time values and global simulation resolution.
Definition: nstime.h:103
double GetSeconds(void) const
Get an approximation of the time stored in this instance in the indicated unit.
Definition: nstime.h:379
AttributeValue implementation for Time.
Definition: nstime.h:1308
a unique identifier for an interface.
Definition: type-id.h:59
TypeId SetParent(TypeId tid)
Set the parent TypeId.
Definition: type-id.cc:922
#define NS_ASSERT(condition)
At runtime, in debugging builds, if this condition is not true, the program prints the source file,...
Definition: assert.h:67
Ptr< const AttributeAccessor > MakeDoubleAccessor(T1 a1)
Create an AttributeAccessor for a class data member, or a lone class get functor or set method.
Definition: double.h:42
Ptr< const AttributeAccessor > MakeTimeAccessor(T1 a1)
Create an AttributeAccessor for a class data member, or a lone class get functor or set method.
Definition: nstime.h:1309
#define NS_LOG_COMPONENT_DEFINE(name)
Define a Log component with a specific name.
Definition: log.h:205
#define NS_LOG_DEBUG(msg)
Use NS_LOG to output a message of level LOG_DEBUG.
Definition: log.h:273
#define NS_LOG_FUNCTION(parameters)
If log level LOG_FUNCTION is enabled, this macro will output all input parameters separated by ",...
#define NS_OBJECT_ENSURE_REGISTERED(type)
Register an Object subclass with the TypeId system.
Definition: object-base.h:45
Time Seconds(double value)
Construct a Time in the indicated unit.
Definition: nstime.h:1244
Ptr< const TraceSourceAccessor > MakeTraceSourceAccessor(T a)
Create a TraceSourceAccessor which will control access to the underlying trace source.
Every class exported by the ns3 library is enclosed in the ns3 namespace.
Ptr< const AttributeChecker > MakeTimeChecker(const Time min, const Time max)
Helper to make a Time checker with bounded range.
Definition: time.cc:522
#define E(name, start, end)