2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2010,2011,2012, by the GROMACS development team, led by
5 * David van der Spoel, Berk Hess, Erik Lindahl, and including many
6 * others, as listed in the AUTHORS file in the top-level source
7 * directory and at http://www.gromacs.org.
9 * GROMACS is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Lesser General Public License
11 * as published by the Free Software Foundation; either version 2.1
12 * of the License, or (at your option) any later version.
14 * GROMACS is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Lesser General Public License for more details.
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with GROMACS; if not, see
21 * http://www.gnu.org/licenses, or write to the Free Software Foundation,
22 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
24 * If you want to redistribute modifications to GROMACS, please
25 * consider that scientific software is very special. Version
26 * control is crucial - bugs must be traceable. We will be happy to
27 * consider code for inclusion in the official distribution, but
28 * derived work must not be called official GROMACS. Details are found
29 * in the README & COPYING files - if they are missing, get the
30 * official version at http://www.gromacs.org.
32 * To help us fund GROMACS development, we humbly ask that you cite
33 * the research papers on the package. Check out http://www.gromacs.org.
37 * Declares gmx::AnalysisDataPlotModule for plotting data (into a file).
40 * \ingroup module_analysisdata
41 * \author Teemu Murtola <teemu.murtola@gmail.com>
43 #ifndef GMX_ANALYSISDATA_MODULES_PLOT_H
44 #define GMX_ANALYSISDATA_MODULES_PLOT_H
48 #include <boost/shared_ptr.hpp>
50 #include "../datamodule.h"
51 #include "../../options/timeunitmanager.h"
52 #include "../../utility/common.h"
58 class SelectionCollection;
61 * Common settings for data plots.
64 * \ingroup module_analysisdata
66 class AnalysisDataPlotSettings
69 //! Constructs default analysis plot settings.
70 AnalysisDataPlotSettings();
72 //! Returns the selection collection set with setSelectionCollection().
73 const SelectionCollection *selectionCollection() const
77 //! Returns the time unit set with setTimeUnit().
78 TimeUnit timeUnit() const { return timeUnit_; }
80 * Returns the plot format.
82 * \todo Use a proper enum.
84 int plotFormat() const { return plotFormat_; }
87 * Set selection collection to print as comments into the output.
89 * Formatted selection text from all selections in \p selections is
90 * printed as comments in the output file.
91 * If this method is not called, no selection information is written
94 void setSelectionCollection(const SelectionCollection *selections);
96 * Sets the time unit for the plot.
98 * The value is used only if AbstractPlotModule::setXAxisIsTime() is
99 * called, in which case it is used to print the appropriate axis label
100 * and to scale the values.
101 * If not called, the default time unit is ps.
103 void setTimeUnit(TimeUnit timeUnit) { timeUnit_ = timeUnit; }
107 * Adds common options for setting plot options.
109 * \param[in,out] options Options object to which options are added.
111 void addOptions(Options *options);
114 const SelectionCollection *selections_;
120 * Abstract data module for writing data into a file.
122 * Implements features common to all plotting modules. Subclasses implement
123 * features specific to certain applications (AnalysisDataPlotModule implements
124 * straightforward plotting).
126 * By default, the data is written into an xvgr file, according to the
127 * options read from the Options object given to the constructor.
128 * For non-xvgr data, it's possible to skip all headers by calling
131 * Multipoint data is supported, in which case all the points are written to
132 * the output, in the order in which they are added to the data. A single
133 * output line corresponds to a single frame. In most cases with multipoint
134 * data, setPlainOutput() should be called since the output does not make sense
135 * as an xvgr file, but this is not enforced.
137 * \ingroup module_analysisdata
139 class AbstractPlotModule : public AnalysisDataModuleInterface
142 virtual ~AbstractPlotModule();
145 * Set common settings for the plotting.
147 void setSettings(const AnalysisDataPlotSettings &settings);
149 * Set the output file name.
151 * If no file name is set (or if \p filename is empty), no output occurs.
153 void setFileName(const std::string &filename);
157 * If \p bPlain is true, no xvgr headers are written to the file.
158 * In this case, only setOmitX(), setXFormat(), and setYFormat()
159 * methods have any effect on the output.
161 void setPlainOutput(bool bPlain);
163 * Omit the X coordinates from the output.
165 * This method only makes sense when combined with setPlainOutput().
167 void setOmitX(bool bOmitX);
171 void setTitle(const char *title);
175 void setSubtitle(const char *subtitle);
179 void setXLabel(const char *label);
181 * Treat X axis as time.
183 * Sets the label for the axis accordingly and also scales output to
184 * take into account the correct time unit.
186 void setXAxisIsTime();
190 void setYLabel(const char *label);
192 * Add legend from an array of strings.
194 * Multiple calls to setLegend() and/or appendLegend() are added
197 void setLegend(int nsets, const char * const *setname);
199 * Add a legend string for the next data set.
201 * Multiple calls to setLegend() and/or appendLegend() are added
204 void appendLegend(const char *setname);
206 * Set field width and precision for X value output.
208 void setXFormat(int width, int precision, char format = 'f');
210 * Set field width and precision for Y value output.
212 void setYFormat(int width, int precision, char format = 'f');
214 virtual int flags() const;
216 virtual void dataStarted(AbstractAnalysisData *data);
217 virtual void frameStarted(const AnalysisDataFrameHeader &header);
218 virtual void pointsAdded(const AnalysisDataPointSetRef &points) = 0;
219 virtual void frameFinished(const AnalysisDataFrameHeader &header);
220 virtual void dataFinished();
224 AbstractPlotModule();
225 //! Creates AbstractPlotModule and assign common settings.
226 explicit AbstractPlotModule(const AnalysisDataPlotSettings &settings);
228 //! Whether an output file has been opened.
229 bool isFileOpen() const;
231 * Appends a single value to the current output line.
233 * \param[in] value Value to append.
235 * Should be used from pointsAdded() implementations in derived classes
236 * to write out individual y values to the output.
238 * Must not be called if isFileOpen() returns false.
240 void writeValue(real value) const;
246 PrivateImplPointer<Impl> impl_;
251 * Plotting module for straightforward plotting of data.
253 * See AbstractPlotModule for common plotting options.
256 * \ingroup module_analysisdata
258 class AnalysisDataPlotModule : public AbstractPlotModule
261 AnalysisDataPlotModule();
262 //! Creates AnalysisDataPlotModule and assign common settings.
263 explicit AnalysisDataPlotModule(const AnalysisDataPlotSettings &settings);
265 virtual void pointsAdded(const AnalysisDataPointSetRef &points);
267 // Copy and assign disallowed by base.
272 * Plotting module specifically for data consisting of vectors.
274 * See AbstractPlotModule for common plotting options.
277 * \ingroup module_analysisdata
279 class AnalysisDataVectorPlotModule : public AbstractPlotModule
282 AnalysisDataVectorPlotModule();
283 //! Creates AnalysisDataVectorPlotModule and assign common settings.
284 explicit AnalysisDataVectorPlotModule(const AnalysisDataPlotSettings &settings);
287 * Set whether to write X component.
289 void setWriteX(bool bWrite);
291 * Set whether to write Y component.
293 void setWriteY(bool bWrite);
295 * Set whether to write Z component.
297 void setWriteZ(bool bWrite);
299 * Set whether to write norm of the vector.
301 void setWriteNorm(bool bWrite);
303 * Set mask for what to write.
305 void setWriteMask(bool bWrite[4]);
307 virtual void pointsAdded(const AnalysisDataPointSetRef &points);
312 // Copy and assign disallowed by base.
315 //! Smart pointer to manage an AnalysisDataPlotModule object.
316 typedef boost::shared_ptr<AnalysisDataPlotModule>
317 AnalysisDataPlotModulePointer;
318 //! Smart pointer to manage an AnalysisDataVectorPlotModule object.
319 typedef boost::shared_ptr<AnalysisDataVectorPlotModule>
320 AnalysisDataVectorPlotModulePointer;