3 * This source code is part of
7 * GROningen MAchine for Chemical Simulations
9 * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
10 * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
11 * Copyright (c) 2001-2009, The GROMACS development team,
12 * check out http://www.gromacs.org for more information.
14 * This program is free software; you can redistribute it and/or
15 * modify it under the terms of the GNU General Public License
16 * as published by the Free Software Foundation; either version 2
17 * of the License, or (at your option) any later version.
19 * If you want to redistribute modifications, please consider that
20 * scientific software is very special. Version control is crucial -
21 * bugs must be traceable. We will be happy to consider code for
22 * inclusion in the official distribution, but derived work must not
23 * be called official GROMACS. Details are found in the README & COPYING
24 * files - if they are missing, get the official version at www.gromacs.org.
26 * To help us fund GROMACS development, we humbly ask that you cite
27 * the papers on the package - you can find them in the top README file.
29 * For more info, check our website at http://www.gromacs.org
33 * Declares gmx::AnalysisDataPlotModule for plotting data (into a file).
36 * \ingroup module_analysisdata
37 * \author Teemu Murtola <teemu.murtola@cbr.su.se>
39 #ifndef GMX_ANALYSISDATA_MODULES_PLOT_H
40 #define GMX_ANALYSISDATA_MODULES_PLOT_H
44 #include "../datamodule.h"
45 #include "../../options/timeunitmanager.h"
51 class SelectionCollection;
54 * Common settings for data plots.
57 * \ingroup module_analysisdata
59 class AnalysisDataPlotSettings
62 //! Constructs default analysis plot settings.
63 AnalysisDataPlotSettings();
65 //! Returns the selection collection set with setSelectionCollection().
66 const SelectionCollection *selectionCollection() const
70 //! Returns the time unit set with setTimeUnit().
71 TimeUnit timeUnit() const { return timeUnit_; }
73 * Returns the plot format.
75 * \todo Use a proper enum.
77 int plotFormat() const { return plotFormat_; }
80 * Set selection collection to print as comments into the output.
82 * Formatted selection text from all selections in \p selections is
83 * printed as comments in the output file.
84 * If this method is not called, no selection information is written
87 void setSelectionCollection(const SelectionCollection *selections);
89 * Sets the time unit for the plot.
91 * The value is used only if AbstractPlotModule::setXAxisIsTime() is
92 * called, in which case it is used to print the appropriate axis label
93 * and to scale the values.
94 * If not called, the default time unit is ps.
96 void setTimeUnit(TimeUnit timeUnit) { timeUnit_ = timeUnit; }
100 * Adds common options for setting plot options.
102 * \param[in,out] options Options object to which options are added.
104 void addOptions(Options *options);
107 const SelectionCollection *selections_;
113 * Abstract data module for writing data into a file.
115 * Implements features common to all plotting modules. Subclasses implement
116 * features specific to certain applications (AnalysisDataPlotModule implements
117 * straightforward plotting).
119 * By default, the data is written into an xvgr file, according to the
120 * options read from the Options object given to the constructor.
121 * For non-xvgr data, it's possible to skip all headers by calling
124 * Multipoint data is supported, in which case all the points are written to
125 * the output, in the order in which they are added to the data. A single
126 * output line corresponds to a single frame. In most cases with multipoint
127 * data, setPlainOutput() should be called since the output does not make sense
128 * as an xvgr file, but this is not enforced.
130 * \ingroup module_analysisdata
132 class AbstractPlotModule : public AnalysisDataModuleInterface
135 virtual ~AbstractPlotModule();
138 * Set the output file name.
140 * If no file name is set (or if \p fnm is NULL), no output occurs.
142 void setFileName(const std::string &fnm);
146 * If \p bPlain is true, no xvgr headers are written to the file.
147 * In this case, only setOmitX(), setXFormat(), and setYFormat()
148 * methods have any effect on the output.
150 void setPlainOutput(bool bPlain);
152 * Omit the X coordinates from the output.
154 * This method only makes sense when combined with setPlainOutput().
156 void setOmitX(bool bOmitX);
160 void setTitle(const char *title);
164 void setSubtitle(const char *subtitle);
168 void setXLabel(const char *label);
170 * Treat X axis as time.
172 * Sets the label for the axis accordingly and also scales output to
173 * take into account the correct time unit.
175 void setXAxisIsTime();
179 void setYLabel(const char *label);
181 * Add legend from an array of strings.
183 * Multiple calls to setLegend() and/or appendLegend() are added
186 void setLegend(int nsets, const char * const *setname);
188 * Add a legend string for the next data set.
190 * Multiple calls to setLegend() and/or appendLegend() are added
193 void appendLegend(const char *setname);
195 * Set field width and precision for X value output.
197 void setXFormat(int width, int prec, char fmt = 'f');
199 * Set field width and precision for Y value output.
201 void setYFormat(int width, int prec, char fmt = 'f');
203 virtual int flags() const;
205 virtual void dataStarted(AbstractAnalysisData *data);
206 virtual void frameStarted(real x, real dx);
207 virtual void pointsAdded(real x, real dx, int firstcol, int n,
208 const real *y, const real *dy,
209 const bool *present) = 0;
210 virtual void frameFinished();
211 virtual void dataFinished();
215 explicit AbstractPlotModule(const AnalysisDataPlotSettings &settings);
217 bool isFileOpen() const;
218 void writeValue(real value) const;
226 // Disallow copy and assign.
227 AbstractPlotModule(const AbstractPlotModule &);
228 void operator =(const AbstractPlotModule &);
233 * Plotting module for straightforward plotting of data.
235 * See AbstractPlotModule for common plotting options.
238 * \ingroup module_analysisdata
240 class AnalysisDataPlotModule : public AbstractPlotModule
243 explicit AnalysisDataPlotModule(const AnalysisDataPlotSettings &settings);
245 virtual void pointsAdded(real x, real dx, int firstcol, int n,
246 const real *y, const real *dy,
247 const bool *present);
249 // Copy and assign disallowed by base.
254 * Plotting module specifically for data consisting of vectors.
256 * See AbstractPlotModule for common plotting options.
259 * \ingroup module_analysisdata
261 class AnalysisDataVectorPlotModule : public AbstractPlotModule
264 explicit AnalysisDataVectorPlotModule(const AnalysisDataPlotSettings &settings);
267 * Set whether to write X component.
269 void setWriteX(bool bWrite);
271 * Set whether to write Y component.
273 void setWriteY(bool bWrite);
275 * Set whether to write Z component.
277 void setWriteZ(bool bWrite);
279 * Set whether to write norm of the vector.
281 void setWriteNorm(bool bWrite);
283 * Set mask for what to write.
285 void setWriteMask(bool bWrite[4]);
287 virtual void pointsAdded(real x, real dx, int firstcol, int n,
288 const real *y, const real *dy,
289 const bool *present);
294 // Copy and assign disallowed by base.