Project

General

Profile

Statistics
| Branch: | Revision:

root / include / cstatistic.h @ ffa9279f

History | View | Annotate | Download (8.52 KB)

1
//==========================================================================
2
//  CSTATISTIC.H - part of
3
//                     OMNeT++/OMNEST
4
//            Discrete System Simulation in C++
5
//
6
//
7
//  Declaration of the following classes:
8
//    cStatistic : base for statistics
9
//
10
//==========================================================================
11

    
12
/*--------------------------------------------------------------*
13
  Copyright (C) 1992-2008 Andras Varga
14
  Copyright (C) 2006-2008 OpenSim Ltd.
15

16
  This file is distributed WITHOUT ANY WARRANTY. See the file
17
  `license' for details on this and other legal matters.
18
*--------------------------------------------------------------*/
19

    
20
#ifndef __CSTATISTIC_H
21
#define __CSTATISTIC_H
22

    
23
#include <stdio.h>
24
#include "cownedobject.h"
25
#include "simtime.h"
26

    
27
NAMESPACE_BEGIN
28

    
29
class cTransientDetection;
30
class cAccuracyDetection;
31

    
32

    
33
/**
34
 * Base class of different statistic collecting classes.
35
 * cStatistic is the base class for all statistical data
36
 * collection classes. cStatistic itself adds no data members
37
 * or algorithms to cOwnedObject, it only defines virtual functions
38
 * that will be redefined in descendants. No instance of cStatistic
39
 * can be created.
40
 *
41
 * @ingroup Statistics
42
 */
43
class SIM_API cStatistic : public cOwnedObject
44
{
45
  public:
46
    cTransientDetection *td;    // ptr to associated object
47
    cAccuracyDetection *ra;     // ptr to associated object
48
    int genk;                   // index of random number generator to use
49

    
50
  protected:
51
    // internal: utility function for implementing loadFromFile() functions
52
    void freadvarsf (FILE *f,  const char *fmt, ...);
53
    // internal: for collecting the attributes to record into the scalar file
54
    virtual void getAttributesToRecord(opp_string_map& attributes) {}
55

    
56
  public:
57
    /** @name Constructors, destructor, assignment. */
58
    //@{
59

    
60
    /**
61
     * Copy constructor.
62
     */
63
    cStatistic(const cStatistic& r);
64

    
65
    /**
66
     * Constructor, creates an object with the given name
67
     */
68
    explicit cStatistic(const char *name=NULL);
69

    
70
    /**
71
     * Destructor.
72
     */
73
    virtual ~cStatistic();
74

    
75
    /**
76
     * Assignment operator. It is present since descendants may refer to it.
77
     * The name member is not copied; see cNamedObject's operator=() for more details.
78
     */
79
    cStatistic& operator=(const cStatistic& res);
80
    //@}
81

    
82
    /** @name Redefined cObject member functions. */
83
    //@{
84

    
85
    /* Note: No dup() because this is an abstract class! */
86

    
87
    /**
88
     * Serializes the object into an MPI send buffer.
89
     * Used by the simulation kernel for parallel execution.
90
     * See cObject for more details.
91
     */
92
    virtual void parsimPack(cCommBuffer *buffer);
93

    
94
    /**
95
     * Deserializes the object from an MPI receive buffer
96
     * Used by the simulation kernel for parallel execution.
97
     * See cObject for more details.
98
     */
99
    virtual void parsimUnpack(cCommBuffer *buffer);
100
    //@}
101

    
102
    /** @name Collecting values. */
103
    //@{
104

    
105
    /**
106
     * Collects one value.
107
     */
108
    virtual void collect(double value) = 0;
109

    
110
    /**
111
     * Convenience method, delegates to collect(double).
112
     */
113
    virtual void collect(SimTime value) {collect(value.dbl());}
114

    
115
    /**
116
     * Returns true if this object collects weighted statistics.
117
     */
118
    virtual bool isWeighted() const = 0;
119

    
120
    /**
121
     * Collects one value with a given weight.
122
     */
123
    virtual void collect2(double value, double weight);
124

    
125
    /**
126
     * Updates this object with data coming from another statistics
127
     * object. The result is as if this object had collected all the
128
     * observations fed into the other object as well.
129
     */
130
    virtual void merge(const cStatistic *other) = 0;
131

    
132
    /**
133
     * This function should be redefined in derived classes to clear
134
     * the results collected so far.
135
     */
136
    virtual void clearResult() = 0;
137
    //@}
138

    
139
    /** @name Statistics of collected data. */
140
    //@{
141

    
142
    /**
143
     * Returns the number of the observations.
144
     */
145
    virtual long getCount() const = 0;
146

    
147
    /**
148
     * Returns the sum of the values.
149
     * @see getWeightedSum()
150
     */
151
    virtual double getSum() const = 0;
152

    
153
    /**
154
     * Returns the sum of the squared values.
155
     * @see getWeightedSqrSum()
156
     */
157
    virtual double getSqrSum() const = 0;
158

    
159
    /**
160
     * Returns the minimum of the values.
161
     */
162
    virtual double getMin() const = 0;
163

    
164
    /**
165
     * Returns the maximum of the values.
166
     */
167
    virtual double getMax() const = 0;
168

    
169
    /**
170
     * Returns the mean of the (weighted) observations.
171
     */
172
    virtual double getMean() const = 0;
173

    
174
    /**
175
     * Returns the standard deviation of the (weighted) observations.
176
     */
177
    virtual double getStddev() const = 0;
178

    
179
    /**
180
     * Returns the variance of the (weighted) observations.
181
     */
182
    virtual double getVariance() const = 0;
183
    //@}
184

    
185
    /** @name Weighted statistics. */
186
    //@{
187
    /**
188
     * Returns the sum of weights.
189
     */
190
    virtual double getWeights() const = 0;
191

    
192
    /**
193
     * Returns the sum of weight*value products.
194
     */
195
    virtual double getWeightedSum() const = 0;
196

    
197
    /**
198
     * Returns the sum of squared weights.
199
     */
200
    virtual double getSqrSumWeights() const = 0;
201

    
202
    /**
203
     * Returns the sum of weight*value*value products.
204
     */
205
    virtual double getWeightedSqrSum() const = 0;
206
    //@}
207

    
208
    /** @name Transient and result accuracy detection. */
209
    //@{
210

    
211
    /**
212
     * Assigns transient and accuracy detection objects to the statistic
213
     * object.
214
     */
215
    void addTransientDetection(cTransientDetection *object);
216

    
217
    /**
218
     * Assigns transient and accuracy detection objects to the statistic
219
     * object.
220
     */
221
    void addAccuracyDetection(cAccuracyDetection *object);
222

    
223
    /**
224
     * Returns the assigned transient and accuracy detection objects.
225
     */
226
    cTransientDetection *getTransientDetectionObject() const  {return td;}
227

    
228
    /**
229
     * Returns the assigned transient and accuracy detection objects.
230
     */
231
    cAccuracyDetection  *getAccuracyDetectionObject() const  {return ra;}
232
    //@}
233

    
234
    /** @name Generating random numbers based on the collected data */
235
    //@{
236

    
237
    /**
238
     * Sets the index of the random number generator to use when the
239
     * object has to generate a random number based on the statistics
240
     * stored.
241
     */
242
    void setGenK(int gen_nr)   {genk=gen_nr;}
243

    
244
    /**
245
     * Generates a random number based on the collected data. Uses the random number generator set by setGenK().
246
     * This method is pure virtual, implementation is provided in subclasses.
247
     */
248
    virtual double random() const = 0;
249
    //@}
250

    
251
    /** @name Writing to text file, reading from text file, recording to scalar file. */
252
    //@{
253

    
254
    /**
255
     * Writes the contents of the object into a text file.
256
     * This method is pure virtual, implementation is provided in subclasses.
257
     */
258
    virtual void saveToFile(FILE *) const = 0;
259

    
260
    /**
261
     * Reads the object data from a file written out by saveToFile().
262
     * This method is pure virtual, implementation is provided in subclasses.
263
     */
264
    virtual void loadFromFile(FILE *) = 0;
265

    
266
    /**
267
     * Records the statistics into the scalar result file. (Recorded data
268
     * includes the number of observations, mean, standard deviation, min,
269
     * max, potential histogram data, etc.)  The name of the recorded
270
     * statistic will be the object name (see getFullName()).
271
     *
272
     * Note that this operation may have side effect: if this object is a
273
     * histogram, the method may invoke the transform() on the histogram
274
     * object, to force it set up histogram cells before recording.
275
     */
276
    virtual void record()  {recordAs(NULL, NULL);}
277

    
278
    /**
279
     * Records the statistics into the scalar result file, with the given
280
     * unit (e.g. "s", "m/s", etc). The name of the recorded statistic
281
     * will be the object name (see getName()).
282
     *
283
     * Note that this operation may have side effect: if this object is a
284
     * histogram, the method may invoke the transform() on the histogram
285
     * object, to force it set up histogram cells before recording.
286
     */
287
    virtual void recordWithUnit(const char *unit)  {recordAs(NULL, unit);}
288

    
289
    /**
290
     * Records the statistics into the scalar result file, with the given name,
291
     * and optionally, the given unit (e.g. "s", "m/s", etc).
292
     *
293
     * Note that this operation may have side effect: if this object is a
294
     * histogram, the method may invoke the transform() on the histogram
295
     * object, to force it set up histogram cells before recording.
296
     */
297
    virtual void recordAs(const char *name, const char *unit=NULL);
298
    //@}
299
};
300

    
301
NAMESPACE_END
302

    
303
#endif
304