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
  46 namespace gmx
  47 {
  48
  49 class Options;
  50
  51 /*! \brief
  52  * Abstract data module for writing data into a file.
  53  *
  54  * Implements features common to all plotting modules.  Subclasses implement
  55  * features specific to certain applications (AnalysisDataPlotModule implements
  56  * straightforward plotting).
  57  *
  58  * By default, the data is written into an xvgr file, according to the
  59  * options read from the Options object given to the constructor.
  60  * For non-xvgr data, it's possible to skip all headers by calling
  61  * setPlainOutput().
  62  *
  63  * Multipoint data is supported, in which case all the points are written to
  64  * the output, in the order in which they are added to the data.  A single
  65  * output line corresponds to a single frame.  In most cases with multipoint
  66  * data, setPlainOutput() should be called since the output does not make sense
  67  * as an xvgr file, but this is not enforced.
  68  *
  69  * \ingroup module_analysisdata
  70  */
  71 class AbstractPlotModule : public AnalysisDataModuleInterface
  72 {
  73     public:
  74         virtual ~AbstractPlotModule();
  75
  76         /*! \brief
  77          * Set the output file name.
  78          *
  79          * If no file name is set (or if \p fnm is NULL), no output occurs.
  80          */
  81         void setFileName(const std::string &fnm);
  82         /*! \brief
  83          * Set plain output.
  84          *
  85          * If \p bPlain is true, no xvgr headers are written to the file.
  86          * In this case, only setOmitX(), setXFormat(), and setYFormat()
  87          * methods have any effect on the output.
  88          */
  89         void setPlainOutput(bool bPlain);
  90         /*! \brief
  91          * Omit the X coordinates from the output.
  92          *
  93          * This method only makes sense when combined with setPlainOutput().
  94          */
  95         void setOmitX(bool bOmitX);
  96         /*! \brief
  97          * Set plot title.
  98          */
  99         void setTitle(const char *title);
 100         /*! \brief
 101          * Set plot subtitle.
 102          */
 103         void setSubtitle(const char *subtitle);
 104         /*! \brief
 105          * Set X axis label.
 106          */
 107         void setXLabel(const char *label);
 108         /*! \brief
 109          * Set X axis label for time.
 110          */
 111         void setXTimeLabel();
 112         /*! \brief
 113          * Set Y axis label.
 114          */
 115         void setYLabel(const char *label);
 116         /*! \brief
 117          * Add legend from an array of strings.
 118          *
 119          * Multiple calls to setLegend() and/or appendLegend() are added
 120          * together.
 121          */
 122         void setLegend(int nsets, const char * const *setname);
 123         /*! \brief
 124          * Add a legend string for the next data set.
 125          *
 126          * Multiple calls to setLegend() and/or appendLegend() are added
 127          * together.
 128          */
 129         void appendLegend(const char *setname);
 130         /*! \brief
 131          * Set field width and precision for X value output.
 132          */
 133         void setXFormat(int width, int prec, char fmt = 'f');
 134         /*! \brief
 135          * Set field width and precision for Y value output.
 136          */
 137         void setYFormat(int width, int prec, char fmt = 'f');
 138
 139         virtual int flags() const;
 140
 141         virtual void dataStarted(AbstractAnalysisData *data);
 142         virtual void frameStarted(real x, real dx);
 143         virtual void pointsAdded(real x, real dx, int firstcol, int n,
 144                                  const real *y, const real *dy,
 145                                  const bool *present) = 0;
 146         virtual void frameFinished();
 147         virtual void dataFinished();
 148
 149     protected:
 150         /*! \cond libapi */
 151         explicit AbstractPlotModule(const Options &options);
 152
 153         bool isFileOpen() const;
 154         void writeValue(real value) const;
 155         //! \endcond
 156
 157     private:
 158         class Impl;
 159
 160         Impl                   *_impl;
 161
 162         // Disallow copy and assign.
 163         AbstractPlotModule(const AbstractPlotModule &);
 164         void operator =(const AbstractPlotModule &);
 165 };
 166
 167
 168 /*! \brief
 169  * Plotting module for straightforward plotting of data.
 170  *
 171  * See AbstractPlotModule for common plotting options.
 172  *
 173  * \inpublicapi
 174  * \ingroup module_analysisdata
 175  */
 176 class AnalysisDataPlotModule : public AbstractPlotModule
 177 {
 178     public:
 179         explicit AnalysisDataPlotModule(const Options &options);
 180
 181         virtual void pointsAdded(real x, real dx, int firstcol, int n,
 182                                  const real *y, const real *dy,
 183                                  const bool *present);
 184
 185         // Copy and assign disallowed by base.
 186 };
 187
 188
 189 /*! \brief
 190  * Plotting module specifically for data consisting of vectors.
 191  *
 192  * See AbstractPlotModule for common plotting options.
 193  *
 194  * \inpublicapi
 195  * \ingroup module_analysisdata
 196  */
 197 class AnalysisDataVectorPlotModule : public AbstractPlotModule
 198 {
 199     public:
 200         explicit AnalysisDataVectorPlotModule(const Options &options);
 201
 202         /*! \brief
 203          * Set whether to write X component.
 204          */
 205         void setWriteX(bool bWrite);
 206         /*! \brief
 207          * Set whether to write Y component.
 208          */
 209         void setWriteY(bool bWrite);
 210         /*! \brief
 211          * Set whether to write Z component.
 212          */
 213         void setWriteZ(bool bWrite);
 214         /*! \brief
 215          * Set whether to write norm of the vector.
 216          */
 217         void setWriteNorm(bool bWrite);
 218         /*! \brief
 219          * Set mask for what to write.
 220          */
 221         void setWriteMask(bool bWrite[4]);
 222
 223         virtual void pointsAdded(real x, real dx, int firstcol, int n,
 224                                  const real *y, const real *dy,
 225                                  const bool *present);
 226
 227     private:
 228         bool                    _bWrite[4];
 229
 230         // Copy and assign disallowed by base.
 231 };
 232
 233 } // namespace gmx
 234
 235 #endif