A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
gnuplot.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2007 INRIA, 2008 Timo Bingmann
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Original Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
7 * Enhancements: Timo Bingmann <timo.bingmann@student.kit.edu>
8 */
9#ifndef GNUPLOT_H
10#define GNUPLOT_H
11
12#include <string>
13#include <utility>
14#include <vector>
15
16namespace ns3
17{
18
19/**
20 * \ingroup gnuplot
21 *
22 * \brief Abstract class to store a plot line to be used by ns3::Gnuplot.
23 *
24 * This class contains a reference counted data object in m_data. The data
25 * object contains different structs derived from struct Data by subclasses.
26 */
28{
29 public:
30 /**
31 * Reference-counting copy constructor.
32 * \param original Original GnuPlotDataset
33 */
34 GnuplotDataset(const GnuplotDataset& original);
35
36 /**
37 * Reference-counting destructor.
38 */
40
41 /**
42 * Reference-counting assignment operator.
43 * \param original Right-hand side of assignment operator
44 * \return Copy of original GnuplotDataset
45 */
46 GnuplotDataset& operator=(const GnuplotDataset& original);
47
48 /**
49 * \brief Change line title.
50 * \param title the new title string to use for this dataset.
51 *
52 * \note If you want your title to contain a newline character,
53 * escape it like this: "First line\\nSecond line" so that
54 * it is converted to "First line\nSecond line" in the plot file.
55 */
56 void SetTitle(const std::string& title);
57
58 /**
59 * \brief Change extra formatting style parameters for newly created objects.
60 * \param extra extra formatting
61 */
62 static void SetDefaultExtra(const std::string& extra);
63
64 /**
65 * \brief Add extra formatting parameters to this dataset.
66 * \param extra extra formatting
67 */
68 void SetExtra(const std::string& extra);
69
70 protected:
71 /// Friend because it accesses m_data and it's virtual functions directly in
72 /// GenerateOutput().
73 friend class Gnuplot;
74
75 /**
76 * \brief Extra gnuplot parameters set on every newly created dataset.
77 */
78 static std::string m_defaultExtra;
79
80 /**
81 * \brief Derived classes subclass this struct and add their own data fields.
82 */
83 struct Data;
84
85 /**
86 * Called by constructors of derived classes.
87 * \param data the reference counted data object representing this dataset.
88 */
90
91 /**
92 * Reference counted data object.
93 */
95};
96
97/**
98 * \ingroup gnuplot
99 *
100 * \class Gnuplot2dDataset
101 * \brief Class to represent a 2D points plot. Set the line or points style
102 * using SetStyle() and set points using Add().
103 */
105{
106 public:
107 /**
108 * The plotting style to use for this dataset.
109 */
121
122 /**
123 * Whether errorbars should be used for this dataset.
124 */
126 {
130 XY
131 };
132
133 /**
134 * \param title the title to be associated to this dataset (default "Untitled").
135 *
136 * Create an empty dataset. Usually, the dataset's title is
137 * displayed in the legend box.
138 */
139 Gnuplot2dDataset(const std::string& title = "Untitled");
140
141 /**
142 * Change default style for all newly created objects.
143 * \param style the style of plotting to use for newly created datasets.
144 */
145 static void SetDefaultStyle(Style style);
146
147 /**
148 * \param style the style of plotting to use for this dataset.
149 */
150 void SetStyle(Style style);
151
152 /**
153 * Change default errorbars style for all newly created objects.
154 * \param errorBars the style of errorbars to use for newly created datasets.
155 */
156 static void SetDefaultErrorBars(ErrorBars errorBars);
157
158 /**
159 * \param errorBars the style of errorbars to display.
160 *
161 * If you use any style other than none, you need
162 * to make sure you store the delta information in
163 * this dataset with the right GnuplotDataset::Add
164 * method.
165 */
166 void SetErrorBars(ErrorBars errorBars);
167
168 /**
169 * \param x x coord to new data point
170 * \param y y coord to new data point
171 *
172 * Use this method with error bar style NONE.
173 */
174 void Add(double x, double y);
175
176 /**
177 * \param x x coord to new data point
178 * \param y y coord to new data point
179 * \param errorDelta x and y data point uncertainty
180 *
181 * Use this method with error bar style X or Y.
182 */
183 void Add(double x, double y, double errorDelta);
184
185 /**
186 * \param x x coord to new data point
187 * \param y y coord to new data point
188 * \param xErrorDelta x data point uncertainty
189 * \param yErrorDelta y data point uncertainty
190 *
191 * Use this method with error bar style XY.
192 */
193 void Add(double x, double y, double xErrorDelta, double yErrorDelta);
194
195 /**
196 * Add an empty line in the data output sequence. Empty lines in the plot
197 * data break continuous lines and do other things in the output.
198 */
199 void AddEmptyLine();
200
201 private:
202 /**
203 * A point in a 2D plot
204 */
205 struct Point
206 {
207 bool empty; //!< the point is empty
208 double x; //!< X coordinate
209 double y; //!< Y coordinate
210 double dx; //!< X error delta
211 double dy; //!< Y error delta
212 };
213
214 /// The set of points in the dataset
215 typedef std::vector<Point> PointSet;
216
217 static Style m_defaultStyle; //!< default plot style
218 static ErrorBars m_defaultErrorBars; //!< default error bars type
219
220 /// Forward declaration of the internal data class.
221 struct Data2d;
222};
223
224/**
225 * \ingroup gnuplot
226 *
227 * \brief Class to represent a 2D function expression plot.
228 *
229 * Since the function expression is not escaped, styles and extras could just
230 * as well be included in the expression string.
231 */
233{
234 public:
235 /**
236 * \param title the title to be associated to this dataset.
237 * \param function function to plot
238 *
239 * Create an function dataset. Usually, the dataset's title is displayed in
240 * the legend box.
241 */
242 Gnuplot2dFunction(const std::string& title = "Untitled", const std::string& function = "");
243
244 /**
245 * \param function new function string to set
246 */
247 void SetFunction(const std::string& function);
248
249 private:
250 /// Forward declaration of the internal data class.
251 struct Function2d;
252};
253
254/**
255 * \ingroup gnuplot
256 *
257 * \brief Class to represent a 3D points plot. Set the line or points style
258 * using SetStyle() and set points using Add().
259 */
261{
262 public:
263 /**
264 * \param title the title to be associated to this dataset.
265 *
266 * Create an empty dataset. Usually, the dataset's title is
267 * displayed in the legend box.
268 */
269 Gnuplot3dDataset(const std::string& title = "Untitled");
270
271 /**
272 * Change default style for all newly created objects.
273 * \param style the style of plotting to use for newly created datasets.
274 */
275 static void SetDefaultStyle(const std::string& style);
276
277 /**
278 * \param style the style of plotting to use for this dataset.
279 */
280 void SetStyle(const std::string& style);
281
282 /**
283 * \param x x coord to new data point
284 * \param y y coord to new data point
285 * \param z z coord to new data point
286 *
287 * Use this method to add a new 3D point
288 */
289 void Add(double x, double y, double z);
290
291 /**
292 * Add an empty line in the data output sequence. Empty lines in the plot
293 * data break continuous lines and do other things in the output.
294 */
295 void AddEmptyLine();
296
297 private:
298 /**
299 * A point in a 3D plot
300 */
301 struct Point
302 {
303 bool empty; //!< the point is empty
304 double x; //!< X coordinate
305 double y; //!< Y coordinate
306 double z; //!< Z coordinate
307 };
308
309 /// The set of points in the dataset
310 typedef std::vector<Point> PointSet;
311
312 static std::string m_defaultStyle; //!< default plot style
313
314 /// Forward declaration of the internal data class.
315 struct Data3d;
316};
317
318/**
319 * \ingroup gnuplot
320 *
321 * \brief Class to represent a 3D function expression plot.
322 *
323 * Since the function expression is not escaped, styles and extras could just as
324 * well be included in the expression string. The only difference to
325 * Gnuplot2dFunction is the splot command string.
326 */
328{
329 public:
330 /**
331 * \param title the title to be associated to this dataset.
332 * \param function function to plot
333 *
334 * Create an function dataset. Usually, the dataset's title is displayed in
335 * the legend box.
336 */
337 Gnuplot3dFunction(const std::string& title = "Untitled", const std::string& function = "");
338
339 /**
340 * \param function new function string to set
341 */
342 void SetFunction(const std::string& function);
343
344 private:
345 /// Forward declaration of the internal data class.
346 struct Function3d;
347};
348
349/**
350 * \ingroup gnuplot
351 *
352 * \brief a simple class to generate gnuplot-ready plotting commands
353 * from a set of datasets.
354 *
355 * This class really represents a single graph on which multiple datasets
356 * can be plotted.
357 */
359{
360 public:
361 /**
362 * \param outputFilename the name of the file where the rendering of the
363 * graph will be generated if you feed the command stream output by
364 * Gnuplot::GenerateOutput to the gnuplot program.
365 * \param title title line of the plot page
366 */
367 Gnuplot(const std::string& outputFilename = "", const std::string& title = "");
368
369 /**
370 * \param outputFilename the name of the file where the rendering of the
371 * graph will be generated if you feed the command stream output by
372 * Gnuplot::GenerateOutput to the gnuplot program.
373 */
374 void SetOutputFilename(const std::string& outputFilename);
375
376 /**
377 * Crude attempt to auto-detect the correct terminal setting by inspecting
378 * the filename's extension.
379 * \param filename output filename
380 * \return File extension of the provided filename
381 */
382 static std::string DetectTerminal(const std::string& filename);
383
384 /**
385 * \param terminal terminal setting string for output. The default terminal
386 * string is "png"
387 */
388 void SetTerminal(const std::string& terminal);
389
390 /**
391 * \param title set new plot title string to use for this plot.
392 */
393 void SetTitle(const std::string& title);
394
395 /**
396 * \param xLegend the legend for the x horizontal axis
397 * \param yLegend the legend for the y vertical axis
398 */
399 void SetLegend(const std::string& xLegend, const std::string& yLegend);
400
401 /**
402 * \param extra set extra gnuplot directive for output.
403 */
404 void SetExtra(const std::string& extra);
405
406 /**
407 * \param extra append extra gnuplot directive for output.
408 */
409 void AppendExtra(const std::string& extra);
410
411 /**
412 * \param dataset add a dataset to the graph to be plotted.
413 */
414 void AddDataset(const GnuplotDataset& dataset);
415
416 /**
417 * \param os the output stream on which the relevant gnuplot
418 * commands should be generated. Including output file and terminal
419 * headers.
420 *
421 * \brief Writes gnuplot commands and data values to a single
422 * output stream.
423 */
424 void GenerateOutput(std::ostream& os);
425
426 /**
427 * \param osControl the output stream on which the relevant gnuplot
428 * control commands should be generated. Including output file and
429 * terminal headers.
430 * \param osData the output stream on which the relevant gnuplot
431 * data values should be generated.
432 * \param dataFileName the name for the data file that will be
433 * written.
434 *
435 * \brief Writes gnuplot commands and data values to two
436 * different outputs streams.
437 */
438 void GenerateOutput(std::ostream& osControl, std::ostream& osData, std::string dataFileName);
439
440 /**
441 * \param index the index for the data stream in the data file.
442 *
443 * \brief Sets the current data stream index in the data file.
444 */
445 void SetDataFileDatasetIndex(unsigned int index);
446
447 private:
448 /// Type for Datasets to be used in plots
449 typedef std::vector<GnuplotDataset> Datasets;
450
451 std::string m_outputFilename; //!< Output file name
452 std::string m_terminal; //!< Gnuplot "terminal" to use
453
454 Datasets m_datasets; //!< Data sets
455
456 std::string m_title; //!< Plot title
457 std::string m_xLegend; //!< X axis legend
458 std::string m_yLegend; //!< Y axis legend
459 std::string m_extra; //!< extra parameters for the plot
460
461 bool m_generateOneOutputFile; //!< true if only one plot will be generated
462
463 unsigned int m_dataFileDatasetIndex; //!< Data set index to plot
464};
465
466/**
467 * \ingroup gnuplot
468 *
469 * \brief a simple class to group together multiple gnuplots into one file,
470 * e.g. for PDF multi-page output terminals.
471 */
473{
474 public:
475 /**
476 * \param outputFilename the name of the file where the rendering of the
477 * graph will be generated if you feed the command stream output by
478 * GnuplotCollection::GenerateOutput to the gnuplot program.
479 */
480 GnuplotCollection(const std::string& outputFilename);
481
482 /**
483 * \param terminal terminal setting string for output. The default terminal
484 * string is guessed from the output filename's extension.
485 */
486 void SetTerminal(const std::string& terminal);
487
488 /**
489 * \param plot add a plot to the collection to be plotted.
490 */
491 void AddPlot(const Gnuplot& plot);
492
493 /**
494 * Return a pointer to one of the added plots.
495 * \param id index of plot to return
496 * \return reference to plot, throws std::range_error if it does not exist.
497 */
498 Gnuplot& GetPlot(unsigned int id);
499
500 /**
501 * \param os the output stream on which the relevant gnuplot commands should
502 * be generated.
503 */
504 void GenerateOutput(std::ostream& os);
505
506 /**
507 * \param osControl the output stream on which the relevant gnuplot
508 * control commands should be generated. Including output file and
509 * terminal headers.
510 * \param osData the output stream on which the relevant gnuplot
511 * data values should be generated.
512 * \param dataFileName the name for the data file that will be
513 * written.
514 */
515 void GenerateOutput(std::ostream& osControl, std::ostream& osData, std::string dataFileName);
516
517 private:
518 /// Type of the Gnuplot collection
519 typedef std::vector<Gnuplot> Plots;
520
521 std::string m_outputFilename; //!< Output file name
522 std::string m_terminal; //!< Gnuplot "terminal" to use
523
524 Plots m_plots; //!< Plots in the collection
525};
526
527} // namespace ns3
528
529#endif /* GNUPLOT_H */
Class to represent a 2D points plot.
Definition gnuplot.h:105
void AddEmptyLine()
Add an empty line in the data output sequence.
Definition gnuplot.cc:409
static Style m_defaultStyle
default plot style
Definition gnuplot.h:217
static void SetDefaultStyle(Style style)
Change default style for all newly created objects.
Definition gnuplot.cc:342
ErrorBars
Whether errorbars should be used for this dataset.
Definition gnuplot.h:126
static void SetDefaultErrorBars(ErrorBars errorBars)
Change default errorbars style for all newly created objects.
Definition gnuplot.cc:354
void SetErrorBars(ErrorBars errorBars)
Definition gnuplot.cc:360
std::vector< Point > PointSet
The set of points in the dataset.
Definition gnuplot.h:215
void SetStyle(Style style)
Definition gnuplot.cc:348
void Add(double x, double y)
Definition gnuplot.cc:366
Style
The plotting style to use for this dataset.
Definition gnuplot.h:111
static ErrorBars m_defaultErrorBars
default error bars type
Definition gnuplot.h:218
Gnuplot2dDataset(const std::string &title="Untitled")
Definition gnuplot.cc:336
Class to represent a 2D function expression plot.
Definition gnuplot.h:233
void SetFunction(const std::string &function)
Definition gnuplot.cc:496
Gnuplot2dFunction(const std::string &title="Untitled", const std::string &function="")
Definition gnuplot.cc:490
Class to represent a 3D points plot.
Definition gnuplot.h:261
void AddEmptyLine()
Add an empty line in the data output sequence.
Definition gnuplot.cc:622
Gnuplot3dDataset(const std::string &title="Untitled")
Definition gnuplot.cc:593
std::vector< Point > PointSet
The set of points in the dataset.
Definition gnuplot.h:310
static std::string m_defaultStyle
default plot style
Definition gnuplot.h:312
void Add(double x, double y, double z)
Definition gnuplot.cc:611
static void SetDefaultStyle(const std::string &style)
Change default style for all newly created objects.
Definition gnuplot.cc:599
void SetStyle(const std::string &style)
Definition gnuplot.cc:605
Class to represent a 3D function expression plot.
Definition gnuplot.h:328
Gnuplot3dFunction(const std::string &title="Untitled", const std::string &function="")
Definition gnuplot.cc:703
void SetFunction(const std::string &function)
Definition gnuplot.cc:709
a simple class to group together multiple gnuplots into one file, e.g.
Definition gnuplot.h:473
std::string m_outputFilename
Output file name.
Definition gnuplot.h:521
GnuplotCollection(const std::string &outputFilename)
Definition gnuplot.cc:895
void AddPlot(const Gnuplot &plot)
Definition gnuplot.cc:908
void SetTerminal(const std::string &terminal)
Definition gnuplot.cc:902
Gnuplot & GetPlot(unsigned int id)
Return a pointer to one of the added plots.
Definition gnuplot.cc:914
std::string m_terminal
Gnuplot "terminal" to use.
Definition gnuplot.h:522
Plots m_plots
Plots in the collection.
Definition gnuplot.h:524
void GenerateOutput(std::ostream &os)
Definition gnuplot.cc:927
std::vector< Gnuplot > Plots
Type of the Gnuplot collection.
Definition gnuplot.h:519
Abstract class to store a plot line to be used by ns3::Gnuplot.
Definition gnuplot.h:28
GnuplotDataset(const GnuplotDataset &original)
Reference-counting copy constructor.
Definition gnuplot.cc:106
static void SetDefaultExtra(const std::string &extra)
Change extra formatting style parameters for newly created objects.
Definition gnuplot.cc:143
GnuplotDataset & operator=(const GnuplotDataset &original)
Reference-counting assignment operator.
Definition gnuplot.cc:121
void SetExtra(const std::string &extra)
Add extra formatting parameters to this dataset.
Definition gnuplot.cc:149
Data * m_data
Reference counted data object.
Definition gnuplot.h:94
static std::string m_defaultExtra
Extra gnuplot parameters set on every newly created dataset.
Definition gnuplot.h:78
void SetTitle(const std::string &title)
Change line title.
Definition gnuplot.cc:137
~GnuplotDataset()
Reference-counting destructor.
Definition gnuplot.cc:112
a simple class to generate gnuplot-ready plotting commands from a set of datasets.
Definition gnuplot.h:359
std::string m_yLegend
Y axis legend.
Definition gnuplot.h:458
void AddDataset(const GnuplotDataset &dataset)
Definition gnuplot.cc:785
void SetLegend(const std::string &xLegend, const std::string &yLegend)
Definition gnuplot.cc:765
void SetTerminal(const std::string &terminal)
Definition gnuplot.cc:753
std::string m_terminal
Gnuplot "terminal" to use.
Definition gnuplot.h:452
std::string m_extra
extra parameters for the plot
Definition gnuplot.h:459
unsigned int m_dataFileDatasetIndex
Data set index to plot.
Definition gnuplot.h:463
void AppendExtra(const std::string &extra)
Definition gnuplot.cc:778
Datasets m_datasets
Data sets.
Definition gnuplot.h:454
void GenerateOutput(std::ostream &os)
Writes gnuplot commands and data values to a single output stream.
Definition gnuplot.cc:791
std::string m_title
Plot title.
Definition gnuplot.h:456
std::vector< GnuplotDataset > Datasets
Type for Datasets to be used in plots.
Definition gnuplot.h:449
void SetDataFileDatasetIndex(unsigned int index)
Sets the current data stream index in the data file.
Definition gnuplot.cc:888
std::string m_xLegend
X axis legend.
Definition gnuplot.h:457
std::string m_outputFilename
Output file name.
Definition gnuplot.h:451
Gnuplot(const std::string &outputFilename="", const std::string &title="")
Definition gnuplot.cc:716
void SetExtra(const std::string &extra)
Definition gnuplot.cc:772
void SetTitle(const std::string &title)
Definition gnuplot.cc:759
void SetOutputFilename(const std::string &outputFilename)
Definition gnuplot.cc:726
bool m_generateOneOutputFile
true if only one plot will be generated
Definition gnuplot.h:461
static std::string DetectTerminal(const std::string &filename)
Crude attempt to auto-detect the correct terminal setting by inspecting the filename's extension.
Definition gnuplot.cc:732
Every class exported by the ns3 library is enclosed in the ns3 namespace.
uint8_t data[writeSize]
Structure storing the data to for a 2D plot.
Definition gnuplot.cc:162
A point in a 2D plot.
Definition gnuplot.h:206
double y
Y coordinate.
Definition gnuplot.h:209
double dx
X error delta.
Definition gnuplot.h:210
bool empty
the point is empty
Definition gnuplot.h:207
double x
X coordinate.
Definition gnuplot.h:208
double dy
Y error delta.
Definition gnuplot.h:211
Structure storing the function to be used for a 2D plot.
Definition gnuplot.cc:424
Structure storing the data for a 3D plot.
Definition gnuplot.cc:509
A point in a 3D plot.
Definition gnuplot.h:302
bool empty
the point is empty
Definition gnuplot.h:303
double x
X coordinate.
Definition gnuplot.h:304
double z
Z coordinate.
Definition gnuplot.h:306
double y
Y coordinate.
Definition gnuplot.h:305
Structure storing the function to be used for a 3D plot.
Definition gnuplot.cc:637
Structure storing the data to plot.
Definition gnuplot.cc:28