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.
   5  * Copyright (c) 2015,2018,2019,2020, by the GROMACS development team, led by
   6  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   7  * and including many others, as listed in the AUTHORS file in the
   8  * top-level source directory and at http://www.gromacs.org.
   9  *
  10  * GROMACS is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Lesser General Public License
  12  * as published by the Free Software Foundation; either version 2.1
  13  * of the License, or (at your option) any later version.
  14  *
  15  * GROMACS is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public
  21  * License along with GROMACS; if not, see
  22  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  23  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  24  *
  25  * If you want to redistribute modifications to GROMACS, please
  26  * consider that scientific software is very special. Version
  27  * control is crucial - bugs must be traceable. We will be happy to
  28  * consider code for inclusion in the official distribution, but
  29  * derived work must not be called official GROMACS. Details are found
  30  * in the README & COPYING files - if they are missing, get the
  31  * official version at http://www.gromacs.org.
  32  *
  33  * To help us fund GROMACS development, we humbly ask that you cite
  34  * the research papers on the package. Check out http://www.gromacs.org.
  35  */
  36 /*! \file
  37  * \brief
  38  * Declares gmx::AnalysisDataPlotModule for plotting data (into a file).
  39  *
  40  * \inpublicapi
  41  * \ingroup module_analysisdata
  42  * \author Teemu Murtola <teemu.murtola@gmail.com>
  43  */
  44 #ifndef GMX_ANALYSISDATA_MODULES_PLOT_H
  45 #define GMX_ANALYSISDATA_MODULES_PLOT_H
  46
  47 #include <memory>
  48 #include <string>
  49
  50 #include "gromacs/analysisdata/datamodule.h"
  51 #include "gromacs/options/timeunitmanager.h"
  52 #include "gromacs/utility/classhelpers.h"
  53
  54 enum class XvgFormat : int;
  55
  56 namespace gmx
  57 {
  58
  59 class AnalysisDataValue;
  60 class IOptionsContainer;
  61 class SelectionCollection;
  62
  63 /*! \brief
  64  * Common settings for data plots.
  65  *
  66  * \inpublicapi
  67  * \ingroup module_analysisdata
  68  */
  69 class AnalysisDataPlotSettings
  70 {
  71 public:
  72     //! Constructs default analysis plot settings.
  73     AnalysisDataPlotSettings();
  74
  75     //! Returns the selection collection set with setSelectionCollection().
  76     const SelectionCollection* selectionCollection() const { return selections_; }
  77     //! Returns the time unit set with setTimeUnit().
  78     TimeUnit timeUnit() const { return timeUnit_; }
  79     /*! \brief
  80      * Returns the plot format.
  81      */
  82     XvgFormat plotFormat() const { return plotFormat_; }
  83
  84     /*! \brief
  85      * Set selection collection to print as comments into the output.
  86      *
  87      * Formatted selection text from all selections in \p selections is
  88      * printed as comments in the output file.
  89      * If this method is not called, no selection information is written
  90      * to the output.
  91      */
  92     void setSelectionCollection(const SelectionCollection* selections);
  93     /*! \brief
  94      * Sets the time unit for the plot.
  95      *
  96      * The value is used only if AbstractPlotModule::setXAxisIsTime() is
  97      * called, in which case it is used to print the appropriate axis label
  98      * and to scale the values.
  99      * If not called, the default time unit is ps.
 100      */
 101     void setTimeUnit(TimeUnit timeUnit) { timeUnit_ = timeUnit; }
 102
 103
 104     /*! \brief
 105      * Adds common options for setting plot options.
 106      *
 107      * \param[in,out] options Options object to which options are added.
 108      */
 109     void initOptions(IOptionsContainer* options);
 110
 111 private:
 112     const SelectionCollection* selections_;
 113     TimeUnit                   timeUnit_;
 114     XvgFormat                  plotFormat_;
 115 };
 116
 117 /*! \brief
 118  * Abstract data module for writing data into a file.
 119  *
 120  * Implements features common to all plotting modules.  Subclasses implement
 121  * features specific to certain applications (AnalysisDataPlotModule implements
 122  * straightforward plotting).
 123  *
 124  * By default, the data is written into an xvgr file, according to the
 125  * options read from the AnalysisDataPlotSettings object given to the
 126  * constructor.
 127  * For non-xvgr data, it's possible to skip all headers by calling
 128  * setPlainOutput().
 129  *
 130  * A single output line corresponds to a single frame.  In most cases with
 131  * multipoint data, setPlainOutput() should be called since the output does not
 132  * make sense as an xvgr file, but this is not enforced.
 133  *
 134  * Multipoint data and multiple data sets are both supported, in which case all
 135  * the points are written to the output, in the order in which they are added
 136  * to the data.
 137  *
 138  * \ingroup module_analysisdata
 139  */
 140 class AbstractPlotModule : public AnalysisDataModuleSerial
 141 {
 142 public:
 143     ~AbstractPlotModule() override;
 144
 145     /*! \brief
 146      * Set common settings for the plotting.
 147      */
 148     void setSettings(const AnalysisDataPlotSettings& settings);
 149     /*! \brief
 150      * Set the output file name.
 151      *
 152      * If no file name is set (or if \p filename is empty), no output occurs.
 153      */
 154     void setFileName(const std::string& filename);
 155     /*! \brief
 156      * Set plain output.
 157      *
 158      * If \p bPlain is true, no xvgr headers are written to the file.
 159      * In this case, only setOmitX(), setXFormat(), and setYFormat()
 160      * methods have any effect on the output.
 161      */
 162     void setPlainOutput(bool bPlain);
 163     /*! \brief
 164      * Plot errors as a separate output column after each value column.
 165      */
 166     void setErrorsAsSeparateColumn(bool bSeparate);
 167     /*! \brief
 168      * Omit the X coordinates from the output.
 169      *
 170      * This method only makes sense when combined with setPlainOutput().
 171      */
 172     void setOmitX(bool bOmitX);
 173     /*! \brief
 174      * Set plot title.
 175      */
 176     void setTitle(const char* title);
 177     //! \copydoc setTitle(const char *)
 178     void setTitle(const std::string& title);
 179     /*! \brief
 180      * Set plot subtitle.
 181      */
 182     void setSubtitle(const char* subtitle);
 183     //! \copydoc setSubtitle(const char *)
 184     void setSubtitle(const std::string& subtitle);
 185     /*! \brief
 186      * Set X axis label.
 187      */
 188     void setXLabel(const char* label);
 189     /*! \brief
 190      * Treat X axis as time.
 191      *
 192      * Sets the label for the axis accordingly and also scales output to
 193      * take into account the correct time unit.
 194      */
 195     void setXAxisIsTime();
 196     /*! \brief
 197      * Set Y axis label.
 198      */
 199     void setYLabel(const char* label);
 200     /*! \brief
 201      * Add legend from an array of strings.
 202      *
 203      * Multiple calls to setLegend() and/or appendLegend() are added
 204      * together.
 205      */
 206     void setLegend(int nsets, const char* const* setname);
 207     /*! \brief
 208      * Add a legend string for the next data set.
 209      *
 210      * Multiple calls to setLegend() and/or appendLegend() are added
 211      * together.
 212      */
 213     void appendLegend(const char* setname);
 214     //! \copydoc appendLegend(const char *)
 215     void appendLegend(const std::string& setname);
 216     /*! \brief
 217      * Set field width and precision for X value output.
 218      */
 219     void setXFormat(int width, int precision, char format = 'f');
 220     /*! \brief
 221      * Set field width and precision for Y value output.
 222      */
 223     void setYFormat(int width, int precision, char format = 'f');
 224
 225     int flags() const override;
 226
 227     void dataStarted(AbstractAnalysisData* data) override;
 228     void frameStarted(const AnalysisDataFrameHeader& header) override;
 229     void pointsAdded(const AnalysisDataPointSetRef& points) override = 0;
 230     void frameFinished(const AnalysisDataFrameHeader& header) override;
 231     void dataFinished() override;
 232
 233 protected:
 234     /*! \cond libapi */
 235     AbstractPlotModule();
 236     //! Creates AbstractPlotModule and assign common settings.
 237     explicit AbstractPlotModule(const AnalysisDataPlotSettings& settings);
 238
 239     //! Whether an output file has been opened.
 240     bool isFileOpen() const;
 241     /*! \brief
 242      * Appends a single value to the current output line.
 243      *
 244      * \param[in] value  Value to append.
 245      *
 246      * Should be used from pointsAdded() implementations in derived classes
 247      * to write out individual y values to the output.
 248      *
 249      * Must not be called if isFileOpen() returns false.
 250      */
 251     void writeValue(const AnalysisDataValue& value) const;
 252     //! \endcond
 253
 254 private:
 255     class Impl;
 256
 257     PrivateImplPointer<Impl> impl_;
 258 };
 259
 260
 261 /*! \brief
 262  * Plotting module for straightforward plotting of data.
 263  *
 264  * See AbstractPlotModule for common plotting options.
 265  *
 266  * \inpublicapi
 267  * \ingroup module_analysisdata
 268  */
 269 class AnalysisDataPlotModule : public AbstractPlotModule
 270 {
 271 public:
 272     AnalysisDataPlotModule();
 273     //! Creates AnalysisDataPlotModule and assign common settings.
 274     explicit AnalysisDataPlotModule(const AnalysisDataPlotSettings& settings);
 275
 276     void pointsAdded(const AnalysisDataPointSetRef& points) override;
 277
 278     // Copy and assign disallowed by base.
 279 };
 280
 281
 282 /*! \brief
 283  * Plotting module specifically for data consisting of vectors.
 284  *
 285  * See AbstractPlotModule for common plotting options.
 286  *
 287  * \inpublicapi
 288  * \ingroup module_analysisdata
 289  */
 290 class AnalysisDataVectorPlotModule : public AbstractPlotModule
 291 {
 292 public:
 293     AnalysisDataVectorPlotModule();
 294     //! Creates AnalysisDataVectorPlotModule and assign common settings.
 295     explicit AnalysisDataVectorPlotModule(const AnalysisDataPlotSettings& settings);
 296
 297     /*! \brief
 298      * Set whether to write X component.
 299      */
 300     void setWriteX(bool bWrite);
 301     /*! \brief
 302      * Set whether to write Y component.
 303      */
 304     void setWriteY(bool bWrite);
 305     /*! \brief
 306      * Set whether to write Z component.
 307      */
 308     void setWriteZ(bool bWrite);
 309     /*! \brief
 310      * Set whether to write norm of the vector.
 311      */
 312     void setWriteNorm(bool bWrite);
 313     /*! \brief
 314      * Set mask for what to write.
 315      */
 316     void setWriteMask(const bool bWrite[4]);
 317
 318     void pointsAdded(const AnalysisDataPointSetRef& points) override;
 319
 320 private:
 321     bool bWrite_[4];
 322
 323     // Copy and assign disallowed by base.
 324 };
 325
 326 //! Smart pointer to manage an AnalysisDataPlotModule object.
 327 typedef std::shared_ptr<AnalysisDataPlotModule> AnalysisDataPlotModulePointer;
 328 //! Smart pointer to manage an AnalysisDataVectorPlotModule object.
 329 typedef std::shared_ptr<AnalysisDataVectorPlotModule> AnalysisDataVectorPlotModulePointer;
 330
 331 } // namespace gmx
 332
 333 #endif