src/gromacs/analysisdata/modules/plot.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2010,2011,2012,2013,2014, 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.
   8  *
   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.
  13  *
  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.
  18  *
  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.
  23  *
  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.
  31  *
  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.
  34  */
  35 /*! \file
  36  * \brief
  37  * Declares gmx::AnalysisDataPlotModule for plotting data (into a file).
  38  *
  39  * \inpublicapi
  40  * \ingroup module_analysisdata
  41  * \author Teemu Murtola <teemu.murtola@gmail.com>
  42  */
  43 #ifndef GMX_ANALYSISDATA_MODULES_PLOT_H
  44 #define GMX_ANALYSISDATA_MODULES_PLOT_H
  45
  46 #include <string>
  47
  48 #include <boost/shared_ptr.hpp>
  49
  50 #include "gromacs/analysisdata/datamodule.h"
  51 #include "gromacs/options/timeunitmanager.h"
  52 #include "gromacs/utility/classhelpers.h"
  53
  54 namespace gmx
  55 {
  56
  57 class AnalysisDataValue;
  58 class Options;
  59 class SelectionCollection;
  60
  61 /*! \brief
  62  * Common settings for data plots.
  63  *
  64  * \inpublicapi
  65  * \ingroup module_analysisdata
  66  */
  67 class AnalysisDataPlotSettings
  68 {
  69     public:
  70         //! Constructs default analysis plot settings.
  71         AnalysisDataPlotSettings();
  72
  73         //! Returns the selection collection set with setSelectionCollection().
  74         const SelectionCollection *selectionCollection() const
  75         {
  76             return selections_;
  77         }
  78         //! Returns the time unit set with setTimeUnit().
  79         TimeUnit timeUnit() const { return timeUnit_; }
  80         /*! \brief
  81          * Returns the plot format.
  82          *
  83          * \todo Use a proper enum.
  84          */
  85         int plotFormat() const { return plotFormat_; }
  86
  87         /*! \brief
  88          * Set selection collection to print as comments into the output.
  89          *
  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
  93          * to the output.
  94          */
  95         void setSelectionCollection(const SelectionCollection *selections);
  96         /*! \brief
  97          * Sets the time unit for the plot.
  98          *
  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.
 103          */
 104         void setTimeUnit(TimeUnit timeUnit) { timeUnit_ = timeUnit; }
 105
 106
 107         /*! \brief
 108          * Adds common options for setting plot options.
 109          *
 110          * \param[in,out] options Options object to which options are added.
 111          */
 112         void addOptions(Options *options);
 113
 114     private:
 115         const SelectionCollection *selections_;
 116         TimeUnit                   timeUnit_;
 117         int                        plotFormat_;
 118 };
 119
 120 /*! \brief
 121  * Abstract data module for writing data into a file.
 122  *
 123  * Implements features common to all plotting modules.  Subclasses implement
 124  * features specific to certain applications (AnalysisDataPlotModule implements
 125  * straightforward plotting).
 126  *
 127  * By default, the data is written into an xvgr file, according to the
 128  * options read from the AnalysisDataPlotSettings object given to the
 129  * constructor.
 130  * For non-xvgr data, it's possible to skip all headers by calling
 131  * setPlainOutput().
 132  *
 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.
 136  *
 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
 139  * to the data.
 140  *
 141  * \ingroup module_analysisdata
 142  */
 143 class AbstractPlotModule : public AnalysisDataModuleSerial
 144 {
 145     public:
 146         virtual ~AbstractPlotModule();
 147
 148         /*! \brief
 149          * Set common settings for the plotting.
 150          */
 151         void setSettings(const AnalysisDataPlotSettings &settings);
 152         /*! \brief
 153          * Set the output file name.
 154          *
 155          * If no file name is set (or if \p filename is empty), no output occurs.
 156          */
 157         void setFileName(const std::string &filename);
 158         /*! \brief
 159          * Set plain output.
 160          *
 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.
 164          */
 165         void setPlainOutput(bool bPlain);
 166         /*! \brief
 167          * Plot errors as a separate output column after each value column.
 168          */
 169         void setErrorsAsSeparateColumn(bool bSeparate);
 170         /*! \brief
 171          * Omit the X coordinates from the output.
 172          *
 173          * This method only makes sense when combined with setPlainOutput().
 174          */
 175         void setOmitX(bool bOmitX);
 176         /*! \brief
 177          * Set plot title.
 178          */
 179         void setTitle(const char *title);
 180         //! \copydoc setTitle(const char *)
 181         void setTitle(const std::string &title);
 182         /*! \brief
 183          * Set plot subtitle.
 184          */
 185         void setSubtitle(const char *subtitle);
 186         //! \copydoc setSubtitle(const char *)
 187         void setSubtitle(const std::string &subtitle);
 188         /*! \brief
 189          * Set X axis label.
 190          */
 191         void setXLabel(const char *label);
 192         /*! \brief
 193          * Treat X axis as time.
 194          *
 195          * Sets the label for the axis accordingly and also scales output to
 196          * take into account the correct time unit.
 197          */
 198         void setXAxisIsTime();
 199         /*! \brief
 200          * Set Y axis label.
 201          */
 202         void setYLabel(const char *label);
 203         /*! \brief
 204          * Add legend from an array of strings.
 205          *
 206          * Multiple calls to setLegend() and/or appendLegend() are added
 207          * together.
 208          */
 209         void setLegend(int nsets, const char * const *setname);
 210         /*! \brief
 211          * Add a legend string for the next data set.
 212          *
 213          * Multiple calls to setLegend() and/or appendLegend() are added
 214          * together.
 215          */
 216         void appendLegend(const char *setname);
 217         //! \copydoc appendLegend(const char *)
 218         void appendLegend(const std::string &setname);
 219         /*! \brief
 220          * Set field width and precision for X value output.
 221          */
 222         void setXFormat(int width, int precision, char format = 'f');
 223         /*! \brief
 224          * Set field width and precision for Y value output.
 225          */
 226         void setYFormat(int width, int precision, char format = 'f');
 227
 228         virtual int flags() const;
 229
 230         virtual void dataStarted(AbstractAnalysisData *data);
 231         virtual void frameStarted(const AnalysisDataFrameHeader &header);
 232         virtual void pointsAdded(const AnalysisDataPointSetRef &points) = 0;
 233         virtual void frameFinished(const AnalysisDataFrameHeader &header);
 234         virtual void dataFinished();
 235
 236     protected:
 237         /*! \cond libapi */
 238         AbstractPlotModule();
 239         //! Creates AbstractPlotModule and assign common settings.
 240         explicit AbstractPlotModule(const AnalysisDataPlotSettings &settings);
 241
 242         //! Whether an output file has been opened.
 243         bool isFileOpen() const;
 244         /*! \brief
 245          * Appends a single value to the current output line.
 246          *
 247          * \param[in] value  Value to append.
 248          *
 249          * Should be used from pointsAdded() implementations in derived classes
 250          * to write out individual y values to the output.
 251          *
 252          * Must not be called if isFileOpen() returns false.
 253          */
 254         void writeValue(const AnalysisDataValue &value) const;
 255         //! \endcond
 256
 257     private:
 258         class Impl;
 259
 260         PrivateImplPointer<Impl> impl_;
 261 };
 262
 263
 264 /*! \brief
 265  * Plotting module for straightforward plotting of data.
 266  *
 267  * See AbstractPlotModule for common plotting options.
 268  *
 269  * \inpublicapi
 270  * \ingroup module_analysisdata
 271  */
 272 class AnalysisDataPlotModule : public AbstractPlotModule
 273 {
 274     public:
 275         AnalysisDataPlotModule();
 276         //! Creates AnalysisDataPlotModule and assign common settings.
 277         explicit AnalysisDataPlotModule(const AnalysisDataPlotSettings &settings);
 278
 279         virtual void pointsAdded(const AnalysisDataPointSetRef &points);
 280
 281         // Copy and assign disallowed by base.
 282 };
 283
 284
 285 /*! \brief
 286  * Plotting module specifically for data consisting of vectors.
 287  *
 288  * See AbstractPlotModule for common plotting options.
 289  *
 290  * \inpublicapi
 291  * \ingroup module_analysisdata
 292  */
 293 class AnalysisDataVectorPlotModule : public AbstractPlotModule
 294 {
 295     public:
 296         AnalysisDataVectorPlotModule();
 297         //! Creates AnalysisDataVectorPlotModule and assign common settings.
 298         explicit AnalysisDataVectorPlotModule(const AnalysisDataPlotSettings &settings);
 299
 300         /*! \brief
 301          * Set whether to write X component.
 302          */
 303         void setWriteX(bool bWrite);
 304         /*! \brief
 305          * Set whether to write Y component.
 306          */
 307         void setWriteY(bool bWrite);
 308         /*! \brief
 309          * Set whether to write Z component.
 310          */
 311         void setWriteZ(bool bWrite);
 312         /*! \brief
 313          * Set whether to write norm of the vector.
 314          */
 315         void setWriteNorm(bool bWrite);
 316         /*! \brief
 317          * Set mask for what to write.
 318          */
 319         void setWriteMask(bool bWrite[4]);
 320
 321         virtual void pointsAdded(const AnalysisDataPointSetRef &points);
 322
 323     private:
 324         bool                    bWrite_[4];
 325
 326         // Copy and assign disallowed by base.
 327 };
 328
 329 //! Smart pointer to manage an AnalysisDataPlotModule object.
 330 typedef boost::shared_ptr<AnalysisDataPlotModule>
 331     AnalysisDataPlotModulePointer;
 332 //! Smart pointer to manage an AnalysisDataVectorPlotModule object.
 333 typedef boost::shared_ptr<AnalysisDataVectorPlotModule>
 334     AnalysisDataVectorPlotModulePointer;
 335
 336 } // namespace gmx
 337
 338 #endif