2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2010,2011,2012,2013, by the GROMACS development team, led by
5 * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
6 * and including many others, as listed in the AUTHORS file in the
7 * top-level source 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"
57 class AnalysisDataValue;
59 class SelectionCollection;
62 * Common settings for data plots.
65 * \ingroup module_analysisdata
67 class AnalysisDataPlotSettings
70 //! Constructs default analysis plot settings.
71 AnalysisDataPlotSettings();
73 //! Returns the selection collection set with setSelectionCollection().
74 const SelectionCollection *selectionCollection() const
78 //! Returns the time unit set with setTimeUnit().
79 TimeUnit timeUnit() const { return timeUnit_; }
81 * Returns the plot format.
83 * \todo Use a proper enum.
85 int plotFormat() const { return plotFormat_; }
88 * Set selection collection to print as comments into the output.
90 * Formatted selection text from all selections in \p selections is
91 * printed as comments in the output file.
92 * If this method is not called, no selection information is written
95 void setSelectionCollection(const SelectionCollection *selections);
97 * Sets the time unit for the plot.
99 * The value is used only if AbstractPlotModule::setXAxisIsTime() is
100 * called, in which case it is used to print the appropriate axis label
101 * and to scale the values.
102 * If not called, the default time unit is ps.
104 void setTimeUnit(TimeUnit timeUnit) { timeUnit_ = timeUnit; }
108 * Adds common options for setting plot options.
110 * \param[in,out] options Options object to which options are added.
112 void addOptions(Options *options);
115 const SelectionCollection *selections_;
121 * Abstract data module for writing data into a file.
123 * Implements features common to all plotting modules. Subclasses implement
124 * features specific to certain applications (AnalysisDataPlotModule implements
125 * straightforward plotting).
127 * By default, the data is written into an xvgr file, according to the
128 * options read from the AnalysisDataPlotSettings object given to the
130 * For non-xvgr data, it's possible to skip all headers by calling
133 * A single output line corresponds to a single frame. In most cases with
134 * multipoint data, setPlainOutput() should be called since the output does not
135 * make sense as an xvgr file, but this is not enforced.
137 * Multipoint data and multiple data sets are both supported, in which case all
138 * the points are written to the output, in the order in which they are added
141 * \ingroup module_analysisdata
143 class AbstractPlotModule : public AnalysisDataModuleSerial
146 virtual ~AbstractPlotModule();
149 * Set common settings for the plotting.
151 void setSettings(const AnalysisDataPlotSettings &settings);
153 * Set the output file name.
155 * If no file name is set (or if \p filename is empty), no output occurs.
157 void setFileName(const std::string &filename);
161 * If \p bPlain is true, no xvgr headers are written to the file.
162 * In this case, only setOmitX(), setXFormat(), and setYFormat()
163 * methods have any effect on the output.
165 void setPlainOutput(bool bPlain);
167 * Plot errors as a separate output column after each value column.
169 void setErrorsAsSeparateColumn(bool bSeparate);
171 * Omit the X coordinates from the output.
173 * This method only makes sense when combined with setPlainOutput().
175 void setOmitX(bool bOmitX);
179 void setTitle(const char *title);
183 void setSubtitle(const char *subtitle);
187 void setXLabel(const char *label);
189 * Treat X axis as time.
191 * Sets the label for the axis accordingly and also scales output to
192 * take into account the correct time unit.
194 void setXAxisIsTime();
198 void setYLabel(const char *label);
200 * Add legend from an array of strings.
202 * Multiple calls to setLegend() and/or appendLegend() are added
205 void setLegend(int nsets, const char * const *setname);
207 * Add a legend string for the next data set.
209 * Multiple calls to setLegend() and/or appendLegend() are added
212 void appendLegend(const char *setname);
213 //! \copydoc appendLegend(const char *)
214 void appendLegend(const std::string &setname);
216 * Set field width and precision for X value output.
218 void setXFormat(int width, int precision, char format = 'f');
220 * Set field width and precision for Y value output.
222 void setYFormat(int width, int precision, char format = 'f');
224 virtual int flags() const;
226 virtual void dataStarted(AbstractAnalysisData *data);
227 virtual void frameStarted(const AnalysisDataFrameHeader &header);
228 virtual void pointsAdded(const AnalysisDataPointSetRef &points) = 0;
229 virtual void frameFinished(const AnalysisDataFrameHeader &header);
230 virtual void dataFinished();
234 AbstractPlotModule();
235 //! Creates AbstractPlotModule and assign common settings.
236 explicit AbstractPlotModule(const AnalysisDataPlotSettings &settings);
238 //! Whether an output file has been opened.
239 bool isFileOpen() const;
241 * Appends a single value to the current output line.
243 * \param[in] value Value to append.
245 * Should be used from pointsAdded() implementations in derived classes
246 * to write out individual y values to the output.
248 * Must not be called if isFileOpen() returns false.
250 void writeValue(const AnalysisDataValue &value) const;
256 PrivateImplPointer<Impl> impl_;
261 * Plotting module for straightforward plotting of data.
263 * See AbstractPlotModule for common plotting options.
266 * \ingroup module_analysisdata
268 class AnalysisDataPlotModule : public AbstractPlotModule
271 AnalysisDataPlotModule();
272 //! Creates AnalysisDataPlotModule and assign common settings.
273 explicit AnalysisDataPlotModule(const AnalysisDataPlotSettings &settings);
275 virtual void pointsAdded(const AnalysisDataPointSetRef &points);
277 // Copy and assign disallowed by base.
282 * Plotting module specifically for data consisting of vectors.
284 * See AbstractPlotModule for common plotting options.
287 * \ingroup module_analysisdata
289 class AnalysisDataVectorPlotModule : public AbstractPlotModule
292 AnalysisDataVectorPlotModule();
293 //! Creates AnalysisDataVectorPlotModule and assign common settings.
294 explicit AnalysisDataVectorPlotModule(const AnalysisDataPlotSettings &settings);
297 * Set whether to write X component.
299 void setWriteX(bool bWrite);
301 * Set whether to write Y component.
303 void setWriteY(bool bWrite);
305 * Set whether to write Z component.
307 void setWriteZ(bool bWrite);
309 * Set whether to write norm of the vector.
311 void setWriteNorm(bool bWrite);
313 * Set mask for what to write.
315 void setWriteMask(bool bWrite[4]);
317 virtual void pointsAdded(const AnalysisDataPointSetRef &points);
322 // Copy and assign disallowed by base.
325 //! Smart pointer to manage an AnalysisDataPlotModule object.
326 typedef boost::shared_ptr<AnalysisDataPlotModule>
327 AnalysisDataPlotModulePointer;
328 //! Smart pointer to manage an AnalysisDataVectorPlotModule object.
329 typedef boost::shared_ptr<AnalysisDataVectorPlotModule>
330 AnalysisDataVectorPlotModulePointer;