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
ns3::TypeId
a unique identifier for an interface.
Definition: type-id.h:59
NS_LOG_COMPONENT_DEFINE
#define NS_LOG_COMPONENT_DEFINE(name)
Define a Log component with a specific name.
Definition: log.h:205
ns3::LiIonEnergySource::SetEnergyUpdateInterval
void SetEnergyUpdateInterval(Time interval)
Definition: li-ion-energy-source.cc:159
NS_OBJECT_ENSURE_REGISTERED
#define NS_OBJECT_ENSURE_REGISTERED(type)
Register an Object subclass with the TypeId system.
Definition: object-base.h:45
NS_ASSERT
#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
ns3::MakeTimeChecker
Ptr< const AttributeChecker > MakeTimeChecker(const Time min, const Time max)
Helper to make a Time checker with bounded range.
Definition: time.cc:533
ns3::LiIonEnergySource::m_qRated
double m_qRated
Definition: li-ion-energy-source.h:196
ns3::LiIonEnergySource::m_drainedCapacity
double m_drainedCapacity
Definition: li-ion-energy-source.h:186
ns3::Simulator::Now
static Time Now(void)
Return the current simulation virtual time.
Definition: simulator.cc:195
ns3
Every class exported by the ns3 library is enclosed in the ns3 namespace.
ns3::LiIonEnergySource::m_qNom
double m_qNom
Definition: li-ion-energy-source.h:197
ns3::LiIonEnergySource::m_remainingEnergyJ
TracedValue< double > m_remainingEnergyJ
Definition: li-ion-energy-source.h:185
ns3::LiIonEnergySource::GetVoltage
double GetVoltage(double current) const
Definition: li-ion-energy-source.cc:296
ns3::LiIonEnergySource::DoDispose
void DoDispose(void)
All child's implementation must call BreakDeviceEnergyModelRefCycle to ensure reference cycles to Dev...
Definition: li-ion-energy-source.cc:253
ns3::LiIonEnergySource::m_lastUpdateTime
Time m_lastUpdateTime
Definition: li-ion-energy-source.h:190
ns3::LiIonEnergySource::m_energyUpdateInterval
Time m_energyUpdateInterval
Definition: li-ion-energy-source.h:191
ns3::Simulator::Schedule
static EventId Schedule(Time const &delay, FUNC f, Ts &&... args)
Schedule an event to expire after delay.
Definition: simulator.h:556
ns3::LiIonEnergySource::m_qExp
double m_qExp
Definition: li-ion-energy-source.h:198
ns3::TypeId::SetParent
TypeId SetParent(TypeId tid)
Set the parent TypeId.
Definition: type-id.cc:923
ns3::DoubleValue
This class can be used to hold variables of floating point type such as 'double' or 'float'.
Definition: double.h:41
ns3::MakeTraceSourceAccessor
Ptr< const TraceSourceAccessor > MakeTraceSourceAccessor(T a)
Create a TraceSourceAccessor which will control access to the underlying trace source.
Definition: trace-source-accessor.h:202
ns3::EnergySource::GetNode
Ptr< Node > GetNode(void) const
Definition: energy-source.cc:64
ns3::EnergySource::NotifyEnergyDrained
void NotifyEnergyDrained(void)
This function notifies all DeviceEnergyModel of energy depletion event.
Definition: energy-source.cc:192
ns3::LiIonEnergySource::m_initialEnergyJ
double m_initialEnergyJ
Definition: li-ion-energy-source.h:184
li-ion-energy-source.h
ns3::LiIonEnergySource::LiIonEnergySource
LiIonEnergySource()
Definition: li-ion-energy-source.cc:114
ns3::LiIonEnergySource::GetTypeId
static TypeId GetTypeId(void)
Definition: li-ion-energy-source.cc:37
ns3::EnergySource::CalculateTotalCurrent
double CalculateTotalCurrent(void)
Definition: energy-source.cc:163
ns3::LiIonEnergySource::DecreaseRemainingEnergy
virtual void DecreaseRemainingEnergy(double energyJ)
Definition: li-ion-energy-source.cc:191
ns3::LiIonEnergySource::m_typCurrent
double m_typCurrent
Definition: li-ion-energy-source.h:199
ns3::LiIonEnergySource::m_internalResistance
double m_internalResistance
Definition: li-ion-energy-source.h:195
ns3::LiIonEnergySource::m_supplyVoltageV
double m_supplyVoltageV
Definition: li-ion-energy-source.h:187
ns3::LiIonEnergySource::SetInitialSupplyVoltage
void SetInitialSupplyVoltage(double supplyVoltageV)
Definition: li-ion-energy-source.cc:144
ns3::EventId::Cancel
void Cancel(void)
This method is syntactic sugar for the ns3::Simulator::Cancel method.
Definition: event-id.cc:53
ns3::EnergySource
Introspection did not find any typical Config paths.
Definition: energy-source.h:82
ns3::LiIonEnergySource::CalculateRemainingEnergy
void CalculateRemainingEnergy(void)
Calculates remaining energy.
Definition: li-ion-energy-source.cc:271
ns3::Time
Simulation virtual time values and global simulation resolution.
Definition: nstime.h:104
ns3::LiIonEnergySource::HandleEnergyDrainedEvent
void HandleEnergyDrainedEvent(void)
Handles the remaining energy going to zero event.
Definition: li-ion-energy-source.cc:261
ns3::LiIonEnergySource::IncreaseRemainingEnergy
virtual void IncreaseRemainingEnergy(double energyJ)
Definition: li-ion-energy-source.cc:205
ns3::LiIonEnergySource::m_eFull
double m_eFull
Definition: li-ion-energy-source.h:192
ns3::LiIonEnergySource::m_minVoltTh
double m_minVoltTh
Definition: li-ion-energy-source.h:200
ns3::MakeDoubleAccessor
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
ns3::LiIonEnergySource::m_energyUpdateEvent
EventId m_energyUpdateEvent
Definition: li-ion-energy-source.h:189
ns3::LiIonEnergySource
Model a generic Lithium Ion Battery basing on [1][2].
Definition: li-ion-energy-source.h:73
ns3::EnergySource::BreakDeviceEnergyModelRefCycle
void BreakDeviceEnergyModelRefCycle(void)
This function is called to break reference cycle between EnergySource and DeviceEnergyModel.
Definition: energy-source.cc:228
NS_LOG_DEBUG
#define NS_LOG_DEBUG(msg)
Use NS_LOG to output a message of level LOG_DEBUG.
Definition: log.h:273
ns3::LiIonEnergySource::m_eNom
double m_eNom
Definition: li-ion-energy-source.h:193
ns3::LiIonEnergySource::GetEnergyFraction
virtual double GetEnergyFraction(void)
Definition: li-ion-energy-source.cc:182
ns3::Seconds
Time Seconds(double value)
Construct a Time in the indicated unit.
Definition: nstime.h:1289
ns3::LiIonEnergySource::GetInitialEnergy
virtual double GetInitialEnergy(void) const
Definition: li-ion-energy-source.cc:137
E
#define E(name, start, end)
Definition: packet-test-suite.cc:418
ns3::LiIonEnergySource::~LiIonEnergySource
virtual ~LiIonEnergySource()
Definition: li-ion-energy-source.cc:121
ns3::LiIonEnergySource::GetSupplyVoltage
virtual double GetSupplyVoltage(void) const
Definition: li-ion-energy-source.cc:152
ns3::TimeValue
AttributeValue implementation for Time.
Definition: nstime.h:1353
NS_LOG_FUNCTION
#define NS_LOG_FUNCTION(parameters)
If log level LOG_FUNCTION is enabled, this macro will output all input parameters separated by ",...
Definition: log-macros-enabled.h:244
ns3::Simulator::IsFinished
static bool IsFinished(void)
Check if the simulation should finish.
Definition: simulator.cc:165
ns3::LiIonEnergySource::GetEnergyUpdateInterval
Time GetEnergyUpdateInterval(void) const
Definition: li-ion-energy-source.cc:166
ns3::LiIonEnergySource::DoInitialize
void DoInitialize(void)
Initialize() implementation.
Definition: li-ion-energy-source.cc:246
ns3::LiIonEnergySource::m_lowBatteryTh
double m_lowBatteryTh
Definition: li-ion-energy-source.h:188
ns3::LiIonEnergySource::UpdateEnergySource
virtual void UpdateEnergySource(void)
Implements UpdateEnergySource.
Definition: li-ion-energy-source.cc:213
ns3::LiIonEnergySource::GetRemainingEnergy
virtual double GetRemainingEnergy(void)
Definition: li-ion-energy-source.cc:173
ns3::Time::GetSeconds
double GetSeconds(void) const
Get an approximation of the time stored in this instance in the indicated unit.
Definition: nstime.h:380
ns3::MakeTimeAccessor
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:1354
ns3::LiIonEnergySource::m_eExp
double m_eExp
Definition: li-ion-energy-source.h:194
ns3::LiIonEnergySource::SetInitialEnergy
void SetInitialEnergy(double initialEnergyJ)
Definition: li-ion-energy-source.cc:127