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