src/gromacs/analysisdata/modules/plot.h

   1 /*
   2  *
   3  *                This source code is part of
   4  *
   5  *                 G   R   O   M   A   C   S
   6  *
   7  *          GROningen MAchine for Chemical Simulations
   8  *
   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.
  13
  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.
  18  *
  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.
  25  *
  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.
  28  *
  29  * For more info, check our website at http://www.gromacs.org
  30  */
  31 /*! \file
  32  * \brief
  33  * Declares gmx::AnalysisDataPlotModule for plotting data (into a file).
  34  *
  35  * \inpublicapi
  36  * \ingroup module_analysisdata
  37  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  38  */
  39 #ifndef GMX_ANALYSISDATA_MODULES_PLOT_H
  40 #define GMX_ANALYSISDATA_MODULES_PLOT_H
  41
  42 #include <string>
  43
  44 #include "../datamodule.h"
  45 #include "../../options/timeunitmanager.h"
  46
  47 namespace gmx
  48 {
  49
  50 class Options;
  51 class SelectionCollection;
  52
  53 /*! \brief
  54  * Common settings for data plots.
  55  *
  56  * \inpublicapi
  57  * \ingroup module_analysisdata
  58  */
  59 class AnalysisDataPlotSettings
  60 {
  61     public:
  62         //! Constructs default analysis plot settings.
  63         AnalysisDataPlotSettings();
  64
  65         //! Returns the selection collection set with setSelectionCollection().
  66         const SelectionCollection *selectionCollection() const
  67         {
  68             return selections_;
  69         }
  70         //! Returns the time unit set with setTimeUnit().
  71         TimeUnit timeUnit() const { return timeUnit_; }
  72         /*! \brief
  73          * Returns the plot format.
  74          *
  75          * \todo Use a proper enum.
  76          */
  77         int plotFormat() const { return plotFormat_; }
  78
  79         /*! \brief
  80          * Set selection collection to print as comments into the output.
  81          *
  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
  85          * to the output.
  86          */
  87         void setSelectionCollection(const SelectionCollection *selections);
  88         /*! \brief
  89          * Sets the time unit for the plot.
  90          *
  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.
  95          */
  96         void setTimeUnit(TimeUnit timeUnit) { timeUnit_ = timeUnit; }
  97
  98
  99         /*! \brief
 100          * Adds common options for setting plot options.
 101          *
 102          * \param[in,out] options Options object to which options are added.
 103          */
 104         void addOptions(Options *options);
 105
 106     private:
 107         const SelectionCollection *selections_;
 108         TimeUnit                timeUnit_;
 109         int                     plotFormat_;
 110 };
 111
 112 /*! \brief
 113  * Abstract data module for writing data into a file.
 114  *
 115  * Implements features common to all plotting modules.  Subclasses implement
 116  * features specific to certain applications (AnalysisDataPlotModule implements
 117  * straightforward plotting).
 118  *
 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
 122  * setPlainOutput().
 123  *
 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.
 129  *
 130  * \ingroup module_analysisdata
 131  */
 132 class AbstractPlotModule : public AnalysisDataModuleInterface
 133 {
 134     public:
 135         virtual ~AbstractPlotModule();
 136
 137         /*! \brief
 138          * Set the output file name.
 139          *
 140          * If no file name is set (or if \p fnm is NULL), no output occurs.
 141          */
 142         void setFileName(const std::string &fnm);
 143         /*! \brief
 144          * Set plain output.
 145          *
 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.
 149          */
 150         void setPlainOutput(bool bPlain);
 151         /*! \brief
 152          * Omit the X coordinates from the output.
 153          *
 154          * This method only makes sense when combined with setPlainOutput().
 155          */
 156         void setOmitX(bool bOmitX);
 157         /*! \brief
 158          * Set plot title.
 159          */
 160         void setTitle(const char *title);
 161         /*! \brief
 162          * Set plot subtitle.
 163          */
 164         void setSubtitle(const char *subtitle);
 165         /*! \brief
 166          * Set X axis label.
 167          */
 168         void setXLabel(const char *label);
 169         /*! \brief
 170          * Treat X axis as time.
 171          *
 172          * Sets the label for the axis accordingly and also scales output to
 173          * take into account the correct time unit.
 174          */
 175         void setXAxisIsTime();
 176         /*! \brief
 177          * Set Y axis label.
 178          */
 179         void setYLabel(const char *label);
 180         /*! \brief
 181          * Add legend from an array of strings.
 182          *
 183          * Multiple calls to setLegend() and/or appendLegend() are added
 184          * together.
 185          */
 186         void setLegend(int nsets, const char * const *setname);
 187         /*! \brief
 188          * Add a legend string for the next data set.
 189          *
 190          * Multiple calls to setLegend() and/or appendLegend() are added
 191          * together.
 192          */
 193         void appendLegend(const char *setname);
 194         /*! \brief
 195          * Set field width and precision for X value output.
 196          */
 197         void setXFormat(int width, int prec, char fmt = 'f');
 198         /*! \brief
 199          * Set field width and precision for Y value output.
 200          */
 201         void setYFormat(int width, int prec, char fmt = 'f');
 202
 203         virtual int flags() const;
 204
 205         virtual void dataStarted(AbstractAnalysisData *data);
 206         virtual void frameStarted(const AnalysisDataFrameHeader &header);
 207         virtual void pointsAdded(const AnalysisDataPointSetRef &points) = 0;
 208         virtual void frameFinished(const AnalysisDataFrameHeader &header);
 209         virtual void dataFinished();
 210
 211     protected:
 212         /*! \cond libapi */
 213         explicit AbstractPlotModule(const AnalysisDataPlotSettings &settings);
 214
 215         bool isFileOpen() const;
 216         void writeValue(real value) const;
 217         //! \endcond
 218
 219     private:
 220         class Impl;
 221
 222         Impl                   *_impl;
 223
 224         // Disallow copy and assign.
 225         AbstractPlotModule(const AbstractPlotModule &);
 226         void operator =(const AbstractPlotModule &);
 227 };
 228
 229
 230 /*! \brief
 231  * Plotting module for straightforward plotting of data.
 232  *
 233  * See AbstractPlotModule for common plotting options.
 234  *
 235  * \inpublicapi
 236  * \ingroup module_analysisdata
 237  */
 238 class AnalysisDataPlotModule : public AbstractPlotModule
 239 {
 240     public:
 241         explicit AnalysisDataPlotModule(const AnalysisDataPlotSettings &settings);
 242
 243         virtual void pointsAdded(const AnalysisDataPointSetRef &points);
 244
 245         // Copy and assign disallowed by base.
 246 };
 247
 248
 249 /*! \brief
 250  * Plotting module specifically for data consisting of vectors.
 251  *
 252  * See AbstractPlotModule for common plotting options.
 253  *
 254  * \inpublicapi
 255  * \ingroup module_analysisdata
 256  */
 257 class AnalysisDataVectorPlotModule : public AbstractPlotModule
 258 {
 259     public:
 260         explicit AnalysisDataVectorPlotModule(const AnalysisDataPlotSettings &settings);
 261
 262         /*! \brief
 263          * Set whether to write X component.
 264          */
 265         void setWriteX(bool bWrite);
 266         /*! \brief
 267          * Set whether to write Y component.
 268          */
 269         void setWriteY(bool bWrite);
 270         /*! \brief
 271          * Set whether to write Z component.
 272          */
 273         void setWriteZ(bool bWrite);
 274         /*! \brief
 275          * Set whether to write norm of the vector.
 276          */
 277         void setWriteNorm(bool bWrite);
 278         /*! \brief
 279          * Set mask for what to write.
 280          */
 281         void setWriteMask(bool bWrite[4]);
 282
 283         virtual void pointsAdded(const AnalysisDataPointSetRef &points);
 284
 285     private:
 286         bool                    _bWrite[4];
 287
 288         // Copy and assign disallowed by base.
 289 };
 290
 291 } // namespace gmx
 292
 293 #endif