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/common.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         /*! \brief
 181          * Set plot subtitle.
 182          */
 183         void setSubtitle(const char *subtitle);
 184         /*! \brief
 185          * Set X axis label.
 186          */
 187         void setXLabel(const char *label);
 188         /*! \brief
 189          * Treat X axis as time.
 190          *
 191          * Sets the label for the axis accordingly and also scales output to
 192          * take into account the correct time unit.
 193          */
 194         void setXAxisIsTime();
 195         /*! \brief
 196          * Set Y axis label.
 197          */
 198         void setYLabel(const char *label);
 199         /*! \brief
 200          * Add legend from an array of strings.
 201          *
 202          * Multiple calls to setLegend() and/or appendLegend() are added
 203          * together.
 204          */
 205         void setLegend(int nsets, const char * const *setname);
 206         /*! \brief
 207          * Add a legend string for the next data set.
 208          *
 209          * Multiple calls to setLegend() and/or appendLegend() are added
 210          * together.
 211          */
 212         void appendLegend(const char *setname);
 213         //! \copydoc appendLegend(const char *)
 214         void appendLegend(const std::string &setname);
 215         /*! \brief
 216          * Set field width and precision for X value output.
 217          */
 218         void setXFormat(int width, int precision, char format = 'f');
 219         /*! \brief
 220          * Set field width and precision for Y value output.
 221          */
 222         void setYFormat(int width, int precision, char format = 'f');
 223
 224         virtual int flags() const;
 225
 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();
 231
 232     protected:
 233         /*! \cond libapi */
 234         AbstractPlotModule();
 235         //! Creates AbstractPlotModule and assign common settings.
 236         explicit AbstractPlotModule(const AnalysisDataPlotSettings &settings);
 237
 238         //! Whether an output file has been opened.
 239         bool isFileOpen() const;
 240         /*! \brief
 241          * Appends a single value to the current output line.
 242          *
 243          * \param[in] value  Value to append.
 244          *
 245          * Should be used from pointsAdded() implementations in derived classes
 246          * to write out individual y values to the output.
 247          *
 248          * Must not be called if isFileOpen() returns false.
 249          */
 250         void writeValue(const AnalysisDataValue &value) const;
 251         //! \endcond
 252
 253     private:
 254         class Impl;
 255
 256         PrivateImplPointer<Impl> impl_;
 257 };
 258
 259
 260 /*! \brief
 261  * Plotting module for straightforward plotting of data.
 262  *
 263  * See AbstractPlotModule for common plotting options.
 264  *
 265  * \inpublicapi
 266  * \ingroup module_analysisdata
 267  */
 268 class AnalysisDataPlotModule : public AbstractPlotModule
 269 {
 270     public:
 271         AnalysisDataPlotModule();
 272         //! Creates AnalysisDataPlotModule and assign common settings.
 273         explicit AnalysisDataPlotModule(const AnalysisDataPlotSettings &settings);
 274
 275         virtual void pointsAdded(const AnalysisDataPointSetRef &points);
 276
 277         // Copy and assign disallowed by base.
 278 };
 279
 280
 281 /*! \brief
 282  * Plotting module specifically for data consisting of vectors.
 283  *
 284  * See AbstractPlotModule for common plotting options.
 285  *
 286  * \inpublicapi
 287  * \ingroup module_analysisdata
 288  */
 289 class AnalysisDataVectorPlotModule : public AbstractPlotModule
 290 {
 291     public:
 292         AnalysisDataVectorPlotModule();
 293         //! Creates AnalysisDataVectorPlotModule and assign common settings.
 294         explicit AnalysisDataVectorPlotModule(const AnalysisDataPlotSettings &settings);
 295
 296         /*! \brief
 297          * Set whether to write X component.
 298          */
 299         void setWriteX(bool bWrite);
 300         /*! \brief
 301          * Set whether to write Y component.
 302          */
 303         void setWriteY(bool bWrite);
 304         /*! \brief
 305          * Set whether to write Z component.
 306          */
 307         void setWriteZ(bool bWrite);
 308         /*! \brief
 309          * Set whether to write norm of the vector.
 310          */
 311         void setWriteNorm(bool bWrite);
 312         /*! \brief
 313          * Set mask for what to write.
 314          */
 315         void setWriteMask(bool bWrite[4]);
 316
 317         virtual void pointsAdded(const AnalysisDataPointSetRef &points);
 318
 319     private:
 320         bool                    bWrite_[4];
 321
 322         // Copy and assign disallowed by base.
 323 };
 324
 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;
 331
 332 } // namespace gmx
 333
 334 #endif