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 <boost/shared_ptr.hpp>
46 #include "../datamodule.h"
47 #include "../../options/timeunitmanager.h"
48 #include "../../utility/common.h"
54 class SelectionCollection;
57 * Common settings for data plots.
60 * \ingroup module_analysisdata
62 class AnalysisDataPlotSettings
65 //! Constructs default analysis plot settings.
66 AnalysisDataPlotSettings();
68 //! Returns the selection collection set with setSelectionCollection().
69 const SelectionCollection *selectionCollection() const
73 //! Returns the time unit set with setTimeUnit().
74 TimeUnit timeUnit() const { return timeUnit_; }
76 * Returns the plot format.
78 * \todo Use a proper enum.
80 int plotFormat() const { return plotFormat_; }
83 * Set selection collection to print as comments into the output.
85 * Formatted selection text from all selections in \p selections is
86 * printed as comments in the output file.
87 * If this method is not called, no selection information is written
90 void setSelectionCollection(const SelectionCollection *selections);
92 * Sets the time unit for the plot.
94 * The value is used only if AbstractPlotModule::setXAxisIsTime() is
95 * called, in which case it is used to print the appropriate axis label
96 * and to scale the values.
97 * If not called, the default time unit is ps.
99 void setTimeUnit(TimeUnit timeUnit) { timeUnit_ = timeUnit; }
103 * Adds common options for setting plot options.
105 * \param[in,out] options Options object to which options are added.
107 void addOptions(Options *options);
110 const SelectionCollection *selections_;
116 * Abstract data module for writing data into a file.
118 * Implements features common to all plotting modules. Subclasses implement
119 * features specific to certain applications (AnalysisDataPlotModule implements
120 * straightforward plotting).
122 * By default, the data is written into an xvgr file, according to the
123 * options read from the Options object given to the constructor.
124 * For non-xvgr data, it's possible to skip all headers by calling
127 * Multipoint data is supported, in which case all the points are written to
128 * the output, in the order in which they are added to the data. A single
129 * output line corresponds to a single frame. In most cases with multipoint
130 * data, setPlainOutput() should be called since the output does not make sense
131 * as an xvgr file, but this is not enforced.
133 * \ingroup module_analysisdata
135 class AbstractPlotModule : public AnalysisDataModuleInterface
138 virtual ~AbstractPlotModule();
141 * Set common settings for the plotting.
143 void setSettings(const AnalysisDataPlotSettings &settings);
145 * Set the output file name.
147 * If no file name is set (or if \p filename is empty), no output occurs.
149 void setFileName(const std::string &filename);
153 * If \p bPlain is true, no xvgr headers are written to the file.
154 * In this case, only setOmitX(), setXFormat(), and setYFormat()
155 * methods have any effect on the output.
157 void setPlainOutput(bool bPlain);
159 * Omit the X coordinates from the output.
161 * This method only makes sense when combined with setPlainOutput().
163 void setOmitX(bool bOmitX);
167 void setTitle(const char *title);
171 void setSubtitle(const char *subtitle);
175 void setXLabel(const char *label);
177 * Treat X axis as time.
179 * Sets the label for the axis accordingly and also scales output to
180 * take into account the correct time unit.
182 void setXAxisIsTime();
186 void setYLabel(const char *label);
188 * Add legend from an array of strings.
190 * Multiple calls to setLegend() and/or appendLegend() are added
193 void setLegend(int nsets, const char * const *setname);
195 * Add a legend string for the next data set.
197 * Multiple calls to setLegend() and/or appendLegend() are added
200 void appendLegend(const char *setname);
202 * Set field width and precision for X value output.
204 void setXFormat(int width, int precision, char format = 'f');
206 * Set field width and precision for Y value output.
208 void setYFormat(int width, int precision, char format = 'f');
210 virtual int flags() const;
212 virtual void dataStarted(AbstractAnalysisData *data);
213 virtual void frameStarted(const AnalysisDataFrameHeader &header);
214 virtual void pointsAdded(const AnalysisDataPointSetRef &points) = 0;
215 virtual void frameFinished(const AnalysisDataFrameHeader &header);
216 virtual void dataFinished();
220 AbstractPlotModule();
221 //! Creates AbstractPlotModule and assign common settings.
222 explicit AbstractPlotModule(const AnalysisDataPlotSettings &settings);
224 //! Whether an output file has been opened.
225 bool isFileOpen() const;
227 * Appends a single value to the current output line.
229 * \param[in] value Value to append.
231 * Should be used from pointsAdded() implementations in derived classes
232 * to write out individual y values to the output.
234 * Must not be called if isFileOpen() returns false.
236 void writeValue(real value) const;
242 PrivateImplPointer<Impl> impl_;
247 * Plotting module for straightforward plotting of data.
249 * See AbstractPlotModule for common plotting options.
252 * \ingroup module_analysisdata
254 class AnalysisDataPlotModule : public AbstractPlotModule
257 AnalysisDataPlotModule();
258 //! Creates AnalysisDataPlotModule and assign common settings.
259 explicit AnalysisDataPlotModule(const AnalysisDataPlotSettings &settings);
261 virtual void pointsAdded(const AnalysisDataPointSetRef &points);
263 // Copy and assign disallowed by base.
268 * Plotting module specifically for data consisting of vectors.
270 * See AbstractPlotModule for common plotting options.
273 * \ingroup module_analysisdata
275 class AnalysisDataVectorPlotModule : public AbstractPlotModule
278 AnalysisDataVectorPlotModule();
279 //! Creates AnalysisDataVectorPlotModule and assign common settings.
280 explicit AnalysisDataVectorPlotModule(const AnalysisDataPlotSettings &settings);
283 * Set whether to write X component.
285 void setWriteX(bool bWrite);
287 * Set whether to write Y component.
289 void setWriteY(bool bWrite);
291 * Set whether to write Z component.
293 void setWriteZ(bool bWrite);
295 * Set whether to write norm of the vector.
297 void setWriteNorm(bool bWrite);
299 * Set mask for what to write.
301 void setWriteMask(bool bWrite[4]);
303 virtual void pointsAdded(const AnalysisDataPointSetRef &points);
308 // Copy and assign disallowed by base.
311 //! Smart pointer to manage an AnalysisDataPlotModule object.
312 typedef boost::shared_ptr<AnalysisDataPlotModule>
313 AnalysisDataPlotModulePointer;
314 //! Smart pointer to manage an AnalysisDataVectorPlotModule object.
315 typedef boost::shared_ptr<AnalysisDataVectorPlotModule>
316 AnalysisDataVectorPlotModulePointer;