src/gromacs/fileio/xvgr.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
   5  * Copyright (c) 2001-2004, The GROMACS development team.
   6  * Copyright (c) 2010,2014,2015,2017,2018 by the GROMACS development team.
   7  * Copyright (c) 2019,2020, by the GROMACS development team, led by
   8  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   9  * and including many others, as listed in the AUTHORS file in the
  10  * top-level source directory and at http://www.gromacs.org.
  11  *
  12  * GROMACS is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU Lesser General Public License
  14  * as published by the Free Software Foundation; either version 2.1
  15  * of the License, or (at your option) any later version.
  16  *
  17  * GROMACS is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20  * Lesser General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Lesser General Public
  23  * License along with GROMACS; if not, see
  24  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  25  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  26  *
  27  * If you want to redistribute modifications to GROMACS, please
  28  * consider that scientific software is very special. Version
  29  * control is crucial - bugs must be traceable. We will be happy to
  30  * consider code for inclusion in the official distribution, but
  31  * derived work must not be called official GROMACS. Details are found
  32  * in the README & COPYING files - if they are missing, get the
  33  * official version at http://www.gromacs.org.
  34  *
  35  * To help us fund GROMACS development, we humbly ask that you cite
  36  * the research papers on the package. Check out http://www.gromacs.org.
  37  */
  38 #ifndef GMX_FILEIO_XVGR_H
  39 #define GMX_FILEIO_XVGR_H
  40
  41 #include <stdio.h>
  42
  43 #include <string>
  44 #include <vector>
  45
  46 #include "gromacs/math/multidimarray.h"
  47 #include "gromacs/mdspan/extensions.h"
  48 #include "gromacs/utility/basedefinitions.h"
  49 #include "gromacs/utility/real.h"
  50
  51 struct gmx_output_env_t;
  52
  53 /***************************************************
  54  *            XVGR   DEFINITIONS
  55  ***************************************************/
  56 enum
  57 {
  58     elNone,
  59     elSolid,
  60     elDotted,
  61     elDashed,
  62     elLongDashed,
  63     elDotDashed,
  64     elNR
  65 };
  66 /* xvgr line-styles */
  67
  68 enum
  69 {
  70     ecWhite,
  71     ecFrank,
  72     ecBlack = ecFrank,
  73     ecRed,
  74     ecGreen,
  75     ecBlue,
  76     ecYellow,
  77     ecBrown,
  78     ecGray,
  79     ecPurple,
  80     ecLightBlue,
  81     ecViolet,
  82     ecHolland,
  83     ecLila,
  84     ecDarkGray,
  85     ecAquamarine,
  86     ecOlive,
  87     ecNR
  88 };
  89 /* xvgr line-colors */
  90
  91 enum
  92 {
  93     eppNone,
  94     eppColor,
  95     eppPattern,
  96     eppNR
  97 };
  98 /* xvgr pattern type */
  99
 100 enum
 101 {
 102     evView,
 103     evWorld,
 104     evNR
 105 };
 106 /* view type */
 107
 108 /***************************************************
 109  *            XVGR   ROUTINES
 110  ***************************************************/
 111
 112 /* Strings such as titles, lables and legends can contain escape sequences
 113  * for formatting. Currently supported are:
 114  * \s : start subscript
 115  * \S : start superscript
 116  * \N : end sub/superscript
 117  * \symbol : where symbol is the full name of a greek letter
 118  *           (see the xvgrstr function in xvgr.c for the full list)
 119  *           when starting with a capital, a capital symbol will be printed,
 120  *           note that symbol does not need to be followed by a space
 121  * \8 : (deprecated) start symbol font
 122  * \4 : (deprecated) end symbol font
 123  */
 124
 125 gmx_bool output_env_get_print_xvgr_codes(const struct gmx_output_env_t* oenv);
 126 /* Returns if we should print xmgrace or xmgr codes */
 127
 128 enum
 129 {
 130     exvggtNONE,
 131     exvggtXNY,
 132     exvggtXYDY,
 133     exvggtXYDYDY,
 134     exvggtNR
 135 };
 136
 137 void xvgr_header(FILE*                          fp,
 138                  const char*                    title,
 139                  const std::string&             xaxis,
 140                  const std::string&             yaxis,
 141                  int                            exvg_graph_type,
 142                  const struct gmx_output_env_t* oenv);
 143 /* In most cases you want to use xvgropen_type, which does the same thing
 144  * but takes a filename and opens it.
 145  */
 146
 147 FILE* xvgropen_type(const char*                    fn,
 148                     const char*                    title,
 149                     const std::string&             xaxis,
 150                     const std::string&             yaxis,
 151                     int                            exvg_graph_type,
 152                     const struct gmx_output_env_t* oenv);
 153 /* Open a file, and write a title, and axis-labels in Xvgr format
 154  * or write nothing when oenv specifies so.
 155  * The xvgr graph type enum is defined above.
 156  */
 157
 158 FILE* xvgropen(const char*                    fn,
 159                const char*                    title,
 160                const std::string&             xaxis,
 161                const std::string&             yaxis,
 162                const struct gmx_output_env_t* oenv);
 163 /* Calls xvgropen_type with graph type xvggtXNY. */
 164
 165 /* Close xvgr file, and clean up internal file buffers correctly */
 166 void xvgrclose(FILE* fp);
 167
 168 void xvgr_subtitle(FILE* out, const char* subtitle, const struct gmx_output_env_t* oenv);
 169 /* Set the subtitle in xvgr */
 170
 171 void xvgr_view(FILE* out, real xmin, real ymin, real xmax, real ymax, const struct gmx_output_env_t* oenv);
 172 /* Set the view in xvgr */
 173
 174 void xvgr_world(FILE* out, real xmin, real ymin, real xmax, real ymax, const struct gmx_output_env_t* oenv);
 175 /* Set the world in xvgr */
 176
 177 void xvgrLegend(FILE* out, const std::vector<std::string>& setNames, const struct gmx_output_env_t* oenv);
 178 /* Make a legend box, and also modifies the view to make room for the legend */
 179
 180 void xvgr_legend(FILE* out, int nsets, const char* const* setnames, const struct gmx_output_env_t* oenv);
 181 /* Make a legend box, and also modifies the view to make room for the legend */
 182
 183 void xvgr_new_dataset(FILE* out, int nr_first, int nsets, const char** setnames, const struct gmx_output_env_t* oenv);
 184 /* End the previous data set(s) and start new one(s).
 185     nr_first = the global set number of the first new set (or 0 if no legend)
 186     nsets = the number of sets (or 0 if no legends)
 187     setnames = the set names (or NULL if no legends)
 188  */
 189
 190 void xvgr_line_props(FILE* out, int NrSet, int LineStyle, int LineColor, const struct gmx_output_env_t* oenv);
 191 /* Set xvgr line styles and colors */
 192
 193 void xvgr_box(FILE*                          out,
 194               int                            LocType,
 195               real                           xmin,
 196               real                           ymin,
 197               real                           xmax,
 198               real                           ymax,
 199               int                            LineStyle,
 200               int                            LineWidth,
 201               int                            LineColor,
 202               int                            BoxFill,
 203               int                            BoxColor,
 204               int                            BoxPattern,
 205               const struct gmx_output_env_t* oenv);
 206 /* Make a box */
 207
 208 int read_xvg_legend(const char* fn, double*** y, int* ny, char** subtitle, char*** legend);
 209 /* Read an xvg file for post processing. The number of rows is returned
 210  * fn is the filename, y is a pointer to a 2D array (to be allocated by
 211  * the routine) ny is the number of columns (including X if appropriate).
 212  * If subtitle!=NULL, read the subtitle (when present),
 213  * the subtitle string will be NULL when not present.
 214  * If legend!=NULL, read the legends for the sets (when present),
 215  * 0 is the first y legend, the legend string will be NULL when not present.
 216  */
 217
 218 /* \brief Read only the data from an xvg file for post processing.
 219  *
 220  * Note: this function is deprecated in favor of readXvg, which is
 221  *       used under the hood in this function.
 222  *
 223  * \param[out]    nx Number of rows.
 224  * \param[in]     fn Xvg file to read.
 225  * \param[in/out] y  Pointer to 2D array (allocated by the routine).
 226  * \param[in/out] ny Number of columns.
 227  *
 228  * Todo: Port all read_xvg calls to use readXvgData
 229  */
 230 int read_xvg(const char* fn, double*** y, int* ny);
 231
 232 /* \brief Read only the data from an xvg file for post processing.
 233  *
 234  * \param[out] XvgData Data in row major.
 235  * \param[in]  fn      Xvg file to read.
 236  */
 237 gmx::MultiDimArray<std::vector<double>, gmx::dynamicExtents2D> readXvgData(const std::string& fn);
 238
 239
 240 void write_xvg(const char*                    fn,
 241                const char*                    title,
 242                int                            nx,
 243                int                            ny,
 244                real**                         y,
 245                const char**                   leg,
 246                const struct gmx_output_env_t* oenv);
 247 /* Write a two D array (y) of dimensions nx rows times
 248  * ny columns to a file. If leg != NULL it will be written too.
 249  */
 250
 251
 252 /* This function reads ascii (xvg) files and extracts the data sets to a
 253  * two dimensional array which is returned.
 254  */
 255 real** read_xvg_time(const char* fn,
 256                      gmx_bool    bHaveT,
 257                      gmx_bool    bTB,
 258                      real        tb,
 259                      gmx_bool    bTE,
 260                      real        te,
 261                      int         nsets_in,
 262                      int*        nset,
 263                      int*        nval,
 264                      real*       dt,
 265                      real**      t);
 266 #endif