A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
spectrum-value.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2009 CTTC
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Nicola Baldo <nbaldo@cttc.es>
7 */
8
9#ifndef SPECTRUM_VALUE_H
10#define SPECTRUM_VALUE_H
11
12#include "spectrum-model.h"
13
14#include <ns3/ptr.h>
15#include <ns3/simple-ref-count.h>
16
17#include <ostream>
18#include <vector>
19
20namespace ns3
21{
22
23/// Container for element values
24typedef std::vector<double> Values;
25
26/**
27 * @ingroup spectrum
28 *
29 * @brief Set of values corresponding to a given SpectrumModel
30 *
31 * This class implements a Function Space which can represent any
32 * function \f$ g: F \in {\sf
33 * R\hspace*{-0.9ex}\rule{0.15ex}{1.5ex}\hspace*{0.9ex}}^N \rightarrow {\sf
34 * R\hspace*{-0.9ex}\rule{0.15ex}{1.5ex}\hspace*{0.9ex}} \f$
35 *
36 * Every instance of this class represent a particular function \f$ g(F) \f$.
37 * The domain of the function space, i.e., \f$ F \f$, is implemented by Bands.
38 * The codomain of the function space is implemented by Values.
39 *
40 * To every possible value of \f$ F\f$ corresponds a different Function
41 * Space.
42 * Mathematical operations are defined in this Function Space; these
43 * operations are implemented by means of operator overloading.
44 *
45 * The intended use of this class is to represent frequency-dependent
46 * things, such as power spectral densities, frequency-dependent
47 * propagation losses, spectral masks, etc.
48 */
49class SpectrumValue : public SimpleRefCount<SpectrumValue>
50{
51 public:
52 /**
53 * @brief SpectrumValue constructor
54 *
55 * @param sm pointer to the SpectrumModel which implements the set of frequencies to which the
56 * values will be referring.
57 *
58 * @warning the intended use if that sm points to a static object
59 * which will be there for the whole simulation. This is reasonable
60 * since the set of frequencies which are to be used in the
61 * simulation is normally known before the simulation starts. Make
62 * sure that the SpectrumModel instance which sm points to has already been
63 * initialized by the time this method is invoked. The main reason is
64 * that if you initialize the SpectrumModel instance afterwards, and
65 * the memory for the underlying std::vector gets reallocated, then
66 * sm will not be a valid reference anymore. Another reason is that
67 * m_values could end up having the wrong size.
68 */
70
72
73 /**
74 * Access value at given frequency index
75 *
76 * @param index the given frequency index
77 *
78 * @return reference to the value
79 */
80 double& operator[](size_t index);
81
82 /**
83 * Access value at given frequency index
84 *
85 * @param index the given frequency index
86 *
87 * @return const reference to the value
88 */
89 const double& operator[](size_t index) const;
90
91 /**
92 *
93 * @return the uid of the embedded SpectrumModel
94 */
96
97 /**
98 *
99 * @return the embedded SpectrumModel
100 */
102
103 /**
104 *
105 *
106 * @return a const iterator pointing to the beginning of the embedded Bands
107 */
108 Bands::const_iterator ConstBandsBegin() const;
109
110 /**
111 *
112 *
113 * @return a const iterator pointing to the end of the embedded Bands
114 */
115 Bands::const_iterator ConstBandsEnd() const;
116
117 /**
118 *
119 *
120 * @return a const iterator pointing to the beginning of the embedded Values
121 */
122 Values::const_iterator ConstValuesBegin() const;
123
124 /**
125 *
126 *
127 * @return a const iterator pointing to the end of the embedded Values
128 */
129 Values::const_iterator ConstValuesEnd() const;
130
131 /**
132 *
133 *
134 * @return an iterator pointing to the beginning of the embedded Values
135 */
136 Values::iterator ValuesBegin();
137
138 /**
139 *
140 *
141 * @return an iterator pointing to the end of the embedded Values
142 */
143 Values::iterator ValuesEnd();
144
145 /**
146 * @brief Get the number of values stored in the array
147 * @return the values array size
148 */
149 uint32_t GetValuesN() const;
150
151 /**
152 * Directly set the values using the std::vector<double>
153 * @param values a reference to the std::vector<double>
154 */
155 inline void SetValues(Values& values)
156 {
158 values.size() == m_spectrumModel->GetNumBands(),
159 "Values size does not correspond to the SpectrumModel in use by this SpectrumValue.");
160 m_values = values;
161 }
162
163 /**
164 * Directly set the values by moving the values from the input std::vector<double>
165 * @param values a reference to the std::vector<double> to be moved
166 */
167 inline void SetValues(Values&& values)
168 {
170 values.size() == m_spectrumModel->GetNumBands(),
171 "Values size does not correspond to the SpectrumModel in use by this SpectrumValue.");
172 m_values = std::move(values);
173 }
174
175 /**
176 * @brief Provides the direct access to the underlying std::vector<double>
177 * that stores the spectrum values.
178 * @return a reference to the stored values
179 */
181 {
182 return m_values;
183 }
184
185 /**
186 * @brief Provides the direct read-only access to the underlying std::vector<double>
187 * that stores the spectrum values.
188 * @return a const reference to the stored values
189 */
190 inline const Values& GetValues() const
191 {
192 return m_values;
193 }
194
195 /**
196 * @brief Get the value element at the position
197 * @param pos position
198 * @return the value element in that position (with bounds checking)
199 */
200 const double& ValuesAt(uint32_t pos) const;
201
202 /**
203 * addition operator
204 *
205 * @param lhs Left Hand Side of the operator
206 * @param rhs Right Hand Side of the operator
207 *
208 * @return the value of lhs + rhs
209 */
210 friend SpectrumValue operator+(const SpectrumValue& lhs, const SpectrumValue& rhs);
211
212 /**
213 * addition operator
214 *
215 * @param lhs Left Hand Side of the operator
216 * @param rhs Right Hand Side of the operator
217 *
218 * @return the value of lhs + rhs
219 */
220 friend SpectrumValue operator+(const SpectrumValue& lhs, double rhs);
221
222 /**
223 * addition operator
224 *
225 * @param lhs Left Hand Side of the operator
226 * @param rhs Right Hand Side of the operator
227 *
228 * @return the value of lhs + rhs
229 */
230 friend SpectrumValue operator+(double lhs, const SpectrumValue& rhs);
231
232 /**
233 * subtraction operator
234 *
235 * @param lhs Left Hand Side of the operator
236 * @param rhs Right Hand Side of the operator
237 *
238 * @return the value of lhs - rhs
239 */
240 friend SpectrumValue operator-(const SpectrumValue& lhs, const SpectrumValue& rhs);
241
242 /**
243 * subtraction operator
244 *
245 * @param lhs Left Hand Side of the operator
246 * @param rhs Right Hand Side of the operator
247 *
248 * @return the value of lhs - rhs
249 */
250 friend SpectrumValue operator-(const SpectrumValue& lhs, double rhs);
251
252 /**
253 * subtraction operator
254 *
255 * @param lhs Left Hand Side of the operator
256 * @param rhs Right Hand Side of the operator
257 *
258 * @return the value of lhs - rhs
259 */
260 friend SpectrumValue operator-(double lhs, const SpectrumValue& rhs);
261
262 /**
263 * multiplication component-by-component (Schur product)
264 *
265 * @param lhs Left Hand Side of the operator
266 * @param rhs Right Hand Side of the operator
267 *
268 * @return the value of lhs * rhs
269 */
270 friend SpectrumValue operator*(const SpectrumValue& lhs, const SpectrumValue& rhs);
271
272 /**
273 * multiplication by a scalar
274 *
275 * @param lhs Left Hand Side of the operator
276 * @param rhs Right Hand Side of the operator
277 *
278 * @return the value of lhs * rhs
279 */
280 friend SpectrumValue operator*(const SpectrumValue& lhs, double rhs);
281
282 /**
283 * multiplication of a scalar
284 *
285 * @param lhs Left Hand Side of the operator
286 * @param rhs Right Hand Side of the operator
287 *
288 * @return the value of lhs * rhs
289 */
290 friend SpectrumValue operator*(double lhs, const SpectrumValue& rhs);
291
292 /**
293 * division component-by-component
294 *
295 * @param lhs Left Hand Side of the operator
296 * @param rhs Right Hand Side of the operator
297 *
298 * @return the value of lhs / rhs
299 */
300 friend SpectrumValue operator/(const SpectrumValue& lhs, const SpectrumValue& rhs);
301
302 /**
303 * division by a scalar
304 *
305 * @param lhs Left Hand Side of the operator
306 * @param rhs Right Hand Side of the operator
307 *
308 * @return the value of *this / rhs
309 */
310 friend SpectrumValue operator/(const SpectrumValue& lhs, double rhs);
311
312 /**
313 * division of a scalar
314 *
315 * @param lhs Left Hand Side of the operator
316 * @param rhs Right Hand Side of the operator
317 *
318 * @return the value of *this / rhs
319 */
320 friend SpectrumValue operator/(double lhs, const SpectrumValue& rhs);
321
322 /**
323 * Compare two spectrum values
324 *
325 * @param lhs Left Hand Side of the operator
326 * @param rhs Right Hand Side of the operator
327 *
328 * @return true if lhs and rhs SpectruValues are equal
329 */
330 friend bool operator==(const SpectrumValue& lhs, const SpectrumValue& rhs);
331
332 /**
333 * Compare two spectrum values
334 *
335 * @param lhs Left Hand Side of the operator
336 * @param rhs Right Hand Side of the operator
337 *
338 * @return true if lhs and rhs SpectruValues are not equal
339 */
340 friend bool operator!=(const SpectrumValue& lhs, const SpectrumValue& rhs);
341
342 /**
343 * unary plus operator
344 *
345 * @param rhs Right Hand Side of the operator
346 * @return the value of *this
347 */
348 friend SpectrumValue operator+(const SpectrumValue& rhs);
349
350 /**
351 * unary minus operator
352 *
353 * @param rhs Right Hand Side of the operator
354 * @return the value of - *this
355 */
356 friend SpectrumValue operator-(const SpectrumValue& rhs);
357
358 /**
359 * left shift operator
360 *
361 * @param n position to shift
362 *
363 * @return the value of *this left shifted by n positions. In other
364 * words, the function of the set of frequencies represented by
365 * *this is left-shifted in frequency by n positions.
366 */
367 SpectrumValue operator<<(int n) const;
368
369 /**
370 * right shift operator
371 *
372 * @param n position to shift
373 *
374 * @return the value of *this right shifted by n positions. In other
375 * words, the function of the set of frequencies represented by
376 * *this is left-shifted in frequency by n positions.
377 */
378 SpectrumValue operator>>(int n) const;
379
380 /**
381 * Add the Right Hand Side of the operator to *this, component by component
382 *
383 * @param rhs the Right Hand Side
384 *
385 * @return a reference to *this
386 */
388
389 /**
390 * Subtract the Right Hand Side of the operator from *this, component by component
391 *
392 * @param rhs the Right Hand Side
393 *
394 * @return a reference to *this
395 */
397
398 /**
399 * Multiply *this by the Right Hand Side of the operator, component by component
400 *
401 * @param rhs the Right Hand Side
402 *
403 * @return a reference to *this
404 */
406
407 /**
408 * Divide *this by the Right Hand Side of the operator, component by component
409 *
410 * @param rhs the Right Hand Side
411 *
412 * @return a reference to *this
413 */
415
416 /**
417 * Add the value of the Right Hand Side of the operator to all
418 * components of *this
419 *
420 * @param rhs the Right Hand Side
421 *
422 * @return a reference to *this
423 */
424 SpectrumValue& operator+=(double rhs);
425
426 /**
427 * Subtract the value of the Right Hand Side of the operator from all
428 * components of *this
429 *
430 * @param rhs the Right Hand Side
431 *
432 * @return a reference to *this
433 */
434 SpectrumValue& operator-=(double rhs);
435
436 /**
437 * Multiply every component of *this by the value of the Right Hand
438 * Side of the operator
439 *
440 * @param rhs the Right Hand Side
441 *
442 * @return a reference to *this
443 */
444 SpectrumValue& operator*=(double rhs);
445
446 /**
447 * Divide every component of *this by the value of the Right Hand
448 * Side of the operator
449 *
450 * @param rhs the Right Hand Side
451 *
452 * @return a reference to *this
453 */
454 SpectrumValue& operator/=(double rhs);
455
456 /**
457 * Assign each component of *this to the value of the Right Hand
458 * Side of the operator
459 *
460 * @param rhs
461 *
462 * @return
463 */
464 SpectrumValue& operator=(double rhs);
465
466 /**
467 *
468 * @param x the operand
469 *
470 * @return the euclidean norm, i.e., the sum of the squares of all
471 * the values in x
472 */
473 friend double Norm(const SpectrumValue& x);
474
475 /**
476 *
477 * @param x the operand
478 *
479 * @return the sum of all
480 * the values in x
481 */
482 friend double Sum(const SpectrumValue& x);
483
484 /**
485 * @param x the operand
486 *
487 * @return the product of all
488 * the values in x
489 */
490 friend double Prod(const SpectrumValue& x);
491
492 /**
493 *
494 *
495 * @param lhs the base
496 * @param rhs the exponent
497 *
498 * @return each value in base raised to the exponent
499 */
500 friend SpectrumValue Pow(const SpectrumValue& lhs, double rhs);
501
502 /**
503 *
504 * @param lhs the base
505 * @param rhs the exponent
506 *
507 * @return the value in base raised to each value in the exponent
508 */
509 friend SpectrumValue Pow(double lhs, const SpectrumValue& rhs);
510
511 /**
512 *
513 *
514 * @param arg the argument
515 *
516 * @return the logarithm in base 10 of all values in the argument
517 */
518 friend SpectrumValue Log10(const SpectrumValue& arg);
519
520 /**
521 *
522 *
523 * @param arg the argument
524 *
525 * @return the logarithm in base 2 of all values in the argument
526 */
527 friend SpectrumValue Log2(const SpectrumValue& arg);
528
529 /**
530 *
531 *
532 * @param arg the argument
533 *
534 * @return the logarithm in base e of all values in the argument
535 */
536 friend SpectrumValue Log(const SpectrumValue& arg);
537
538 /**
539 *
540 *
541 * @param arg the argument
542 *
543 * @return the value of the integral \f$\int_F g(f) df \f$
544 */
545 friend double Integral(const SpectrumValue& arg);
546
547 /**
548 *
549 * @return a Ptr to a copy of this instance
550 */
551 Ptr<SpectrumValue> Copy() const;
552
553 /**
554 * TracedCallback signature for SpectrumValue.
555 *
556 * @param [in] value Value of the traced variable.
557 * @deprecated The non-const \c Ptr<SpectrumPhy> argument
558 * is deprecated and will be changed to \c Ptr<const SpectrumPhy>
559 * in a future release.
560 */
561 // NS_DEPRECATED() - tag for future removal
562 typedef void (*TracedCallback)(Ptr<SpectrumValue> value);
563
564 private:
565 /**
566 * Add a SpectrumValue (element to element addition)
567 * @param x SpectrumValue
568 */
569 void Add(const SpectrumValue& x);
570 /**
571 * Add a flat value to all the current elements
572 * @param s flat value
573 */
574 void Add(double s);
575 /**
576 * Subtracts a SpectrumValue (element by element subtraction)
577 * @param x SpectrumValue
578 */
579 void Subtract(const SpectrumValue& x);
580 /**
581 * Subtracts a flat value to all the current elements
582 * @param s flat value
583 */
584 void Subtract(double s);
585 /**
586 * Multiplies for a SpectrumValue (element to element multiplication)
587 * @param x SpectrumValue
588 */
589 void Multiply(const SpectrumValue& x);
590 /**
591 * Multiplies for a flat value to all the current elements
592 * @param s flat value
593 */
594 void Multiply(double s);
595 /**
596 * Divides by a SpectrumValue (element to element division)
597 * @param x SpectrumValue
598 */
599 void Divide(const SpectrumValue& x);
600 /**
601 * Divides by a flat value to all the current elements
602 * @param s flat value
603 */
604 void Divide(double s);
605 /**
606 * Change the values sign
607 */
608 void ChangeSign();
609 /**
610 * Shift the values to the left
611 * @param n number of positions to shift
612 */
613 void ShiftLeft(int n);
614 /**
615 * Shift the values to the right
616 * @param n number of positions to shift
617 */
618 void ShiftRight(int n);
619 /**
620 * Modifies each element so that it each element is raised to the exponent
621 *
622 * @param exp the exponent
623 */
624 void Pow(double exp);
625 /**
626 * Modifies each element so that it is
627 * the base raised to each element value
628 *
629 * @param base the base
630 */
631 void Exp(double base);
632 /**
633 * Applies a Log10 to each the elements
634 */
635 void Log10();
636 /**
637 * Applies a Log2 to each the elements
638 */
639 void Log2();
640 /**
641 * Applies a Log to each the elements
642 */
643 void Log();
644
646
647 /**
648 * Set of values which implement the codomain of the functions in
649 * the Function Space defined by SpectrumValue. There is no restriction
650 * on what these values represent (a transmission power density, a
651 * propagation loss, etc.).
652 *
653 */
655};
656
657std::ostream& operator<<(std::ostream& os, const SpectrumValue& pvf);
658
659double Norm(const SpectrumValue& x);
660double Sum(const SpectrumValue& x);
661double Prod(const SpectrumValue& x);
662SpectrumValue Pow(const SpectrumValue& lhs, double rhs);
663SpectrumValue Pow(double lhs, const SpectrumValue& rhs);
667double Integral(const SpectrumValue& arg);
668
669} // namespace ns3
670
671#endif /* SPECTRUM_VALUE_H */
Smart pointer class similar to boost::intrusive_ptr.
A template-based reference counting class.
Set of values corresponding to a given SpectrumModel.
friend SpectrumValue operator-(const SpectrumValue &lhs, const SpectrumValue &rhs)
subtraction operator
double & operator[](size_t index)
Access value at given frequency index.
void Subtract(const SpectrumValue &x)
Subtracts a SpectrumValue (element by element subtraction)
Values::const_iterator ConstValuesBegin() const
friend SpectrumValue operator+(const SpectrumValue &lhs, const SpectrumValue &rhs)
addition operator
friend double Prod(const SpectrumValue &x)
Bands::const_iterator ConstBandsEnd() const
void Divide(const SpectrumValue &x)
Divides by a SpectrumValue (element to element division)
friend double Norm(const SpectrumValue &x)
friend bool operator!=(const SpectrumValue &lhs, const SpectrumValue &rhs)
Compare two spectrum values.
friend double Integral(const SpectrumValue &arg)
SpectrumValue & operator=(double rhs)
Assign each component of *this to the value of the Right Hand Side of the operator.
Values::iterator ValuesBegin()
void Exp(double base)
Modifies each element so that it is the base raised to each element value.
Bands::const_iterator ConstBandsBegin() const
void ChangeSign()
Change the values sign.
friend SpectrumValue Log2(const SpectrumValue &arg)
void SetValues(Values &&values)
Directly set the values by moving the values from the input std::vector<double>
friend SpectrumValue Log10(const SpectrumValue &arg)
SpectrumValue operator<<(int n) const
left shift operator
void ShiftLeft(int n)
Shift the values to the left.
Ptr< SpectrumValue > Copy() const
friend SpectrumValue Log(const SpectrumValue &arg)
friend SpectrumValue operator/(const SpectrumValue &lhs, const SpectrumValue &rhs)
division component-by-component
Values & GetValues()
Provides the direct access to the underlying std::vector<double> that stores the spectrum values.
Values m_values
Set of values which implement the codomain of the functions in the Function Space defined by Spectrum...
uint32_t GetValuesN() const
Get the number of values stored in the array.
Values::iterator ValuesEnd()
Ptr< const SpectrumModel > GetSpectrumModel() const
SpectrumValue & operator*=(const SpectrumValue &rhs)
Multiply *this by the Right Hand Side of the operator, component by component.
Ptr< const SpectrumModel > m_spectrumModel
The spectrum model.
friend bool operator==(const SpectrumValue &lhs, const SpectrumValue &rhs)
Compare two spectrum values.
void ShiftRight(int n)
Shift the values to the right.
friend SpectrumValue operator*(const SpectrumValue &lhs, const SpectrumValue &rhs)
multiplication component-by-component (Schur product)
void SetValues(Values &values)
Directly set the values using the std::vector<double>
const Values & GetValues() const
Provides the direct read-only access to the underlying std::vector<double> that stores the spectrum v...
friend double Sum(const SpectrumValue &x)
void Add(const SpectrumValue &x)
Add a SpectrumValue (element to element addition)
void Multiply(const SpectrumValue &x)
Multiplies for a SpectrumValue (element to element multiplication)
SpectrumModelUid_t GetSpectrumModelUid() const
SpectrumValue & operator/=(const SpectrumValue &rhs)
Divide *this by the Right Hand Side of the operator, component by component.
SpectrumValue & operator+=(const SpectrumValue &rhs)
Add the Right Hand Side of the operator to *this, component by component.
Values::const_iterator ConstValuesEnd() const
SpectrumValue & operator-=(const SpectrumValue &rhs)
Subtract the Right Hand Side of the operator from *this, component by component.
SpectrumValue operator>>(int n) const
right shift operator
friend SpectrumValue Pow(const SpectrumValue &lhs, double rhs)
const double & ValuesAt(uint32_t pos) const
Get the value element at the position.
Forward calls to a chain of Callback.
#define NS_ASSERT_MSG(condition, message)
At runtime, in debugging builds, if this condition is not true, the program prints the message to out...
Definition assert.h:75
Every class exported by the ns3 library is enclosed in the ns3 namespace.
SpectrumValue Pow(double lhs, const SpectrumValue &rhs)
std::ostream & operator<<(std::ostream &os, const Angles &a)
Definition angles.cc:148
double Integral(const SpectrumValue &arg)
SpectrumValue Log2(const SpectrumValue &arg)
SpectrumValue Log10(const SpectrumValue &arg)
double Norm(const SpectrumValue &x)
SpectrumValue Log(const SpectrumValue &arg)
double Prod(const SpectrumValue &x)
std::vector< double > Values
Container for element values.
double Sum(const SpectrumValue &x)