gnuPlot.hpp

Go to the documentation of this file.

/** \file gnuPlot.hpp
  * \author Jared R. Males (jaredmales@gmail.com)
  * \brief Declaration and definition of an interface to the gnuplot program
  * \ingroup plotting_files
  * 
*/
 
//***********************************************************************//
// Copyright 2015-2023 Jared R. Males (jaredmales@gmail.com)
//
// This file is part of mxlib.
//
// mxlib is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// mxlib is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with mxlib.  If not, see <http://www.gnu.org/licenses/>.
//***********************************************************************//
 
#ifndef math_plot_gnuPlot_hpp
#define math_plot_gnuPlot_hpp
 
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
#include <stdio.h>
#include <fcntl.h>
#include <poll.h>
 
#include <stdlib.h>
 
#include <string>
#include <iostream>
#include <fstream>
#include <vector>
 
#include <cmath>
 
#include <map>
 
#include "../constants.hpp"
#include "../../mxError.hpp"
#include "../../sys/timeUtils.hpp"
 
#ifndef MX_GP_FNAME_SZ
///The size of the string for managing the stderr fifo
/** \ingroup plotting
  */
#define MX_GP_FNAME_SZ (128)
#endif
   
#ifndef MX_GP_TEMP_SZ
///The size of the string for managing temporary file names
/** \ingroup plotting
  */
#define MX_GP_TEMP_SZ (128)
#endif
 
#ifndef MX_GP_FC_TIME
/** \def MX_GP_FC_TIME
  * Time, in microseconds, to wait for gnuplot startup and file creation to complete.
  * Opening is retried after each timeout of this length for MX_GP_FC_RETRIES attempts.
  * \ingroup plotting
  */ 
#define MX_GP_FC_TIME (10000)
#endif
   
#ifndef MX_GP_FC_RETRIES
/** \def MX_GP_FC_RETRIES 
  * Number of times to retry opening the gnuplot stderr file.
  * \ingroup plotting
  */
#define MX_GP_FC_RETRIES (10)
#endif
 
namespace mx
{
namespace math 
{
 
   
//Get the gnuplot binary format string for a type
//Specializations below.
template<typename dataT>
std::string gpBinaryFormat()
{
   static_assert(std::is_fundamental<dataT>::value || !std::is_fundamental<dataT>::value, "No gnuplot format specifier available for this type.");
   return "";
}
 
struct gpCurve
{
    std::string m_file;
 
    std::string m_title;
 
    std::string m_modifiers;
 
    std::string m_binary;
 
    gpCurve(){}
 
    gpCurve( const std::string & file,
             const std::string & title,
             const std::string & modifiers 
           ) : m_file(file), m_title(title), m_modifiers(modifiers)
    {}
 
    gpCurve( const std::string & file,
             const std::string & title,
             const std::string & modifiers,
             const std::string & binary
           ) : m_file(file), m_title(title), m_modifiers(modifiers), m_binary(binary)
    {}
 
    gpCurve( const gpCurve & gpc )
    {
        m_file = gpc.m_file;
        m_title = gpc.m_title;
        m_modifiers = gpc.m_modifiers;
        m_binary = gpc.m_binary;
    }
    
};
 
/// An interactive c++ interface to gnuplot
/** Spawns a gnuplot sesssion and communicates with it.
  * \ingroup plotting 
  * 
  * \todo Use mxError for error reporting.
  * 
  * An example of using gnuPlot to plot data from a file: 
  * \code
  * gnuPlot gp; //This automatically connects, and is now ready to plot.
  * 
  * gp.plot("my_data_file.dat", "u 1:2 w l"); //Plots the data in the file
  * \endcode
  * 
  * Arrays can be plotted directly:
  * \code
  * std::vector<float> x;
  * std::vector<double> y;
  * 
  * //...code to populate x and y
  * 
  * gp.plot(x, y); //Plots y vs x.  
  * \endcode
  * Note that the vector data types are different -- this is handled automatically.
  * 
  * To get a response from the gnuplot session:
  * \code
  * std::cout << gp.getResponse("show terminal") << "\n"; //Sends the command to gnuplot, gets the response.
  * \endcode
  * Error checking and reporting is not straightforward since gnuplot does not return a result if there is no error.  If there is an error,
  * it can take several hundred milliseconds for a response to be available.  So for a typical 
  * plot command, say, one does not want to try to read the stderr ouput just in case as this will just time out with a delay.
  *
  * For cases where a response is expected, the following example shows how to check for errors.
  * \code
  * errno = 0;
  * std::string response = gp.getResponse("show terminal"); //Waits up to 0.5 seconds, or a user specified timeout. 
  * 
  * if(response == "") //This indicates some error occurred, or a timeout.
  * {
  *   if(gp.gpError())
  *   {
  *      std::cerr << "gnuplot returned error:\n" << gp.gpErrorMsg() << "\n";
  *   }
  *   else if(errno)
  *   {
  *      perror("error getting response: ");
  *   }
  *   else
  *   {
  *      std::cerr << "timed out\n";
  *   }
  * }
  * else
  * {
  *   std::cout << response << "\n";
  * }
  * 
  * \endcode
  */
class gnuPlot
{
protected:   
 
   int _connected {0};
   
   ///Set to true if the response indicates a gnuplot error
   bool _gpError {false};
   std::string _gpErrorMsg;
   
   ///File stream for the gnuplot interface
   FILE * _pipeH {0};
   
   ///Where to create gnuplot stderr fifo
   /** Default is /dev/shm/
     */
   std::string _errLocation;
   
   ///File name of the gnuplot stderr fifo
   std::string _errFName;
   
   ///File descriptor for the gnuplot stderr fifo
   int _errFD {0};
   
   ///Location of temporary files 
   /** Default is /dev/shm/
     */
   std::string _tempLocation;
   
   ///Vector of all temporary file names opened, used for removal on destruction.
   std::vector<std::string> _tempFiles;
 
   ///Flag to control whether temporary files are deleted on destruction.  Default is true (files deleted).
   bool _deleteTemp {true};
 
   std::map<std::string, gpCurve> m_curveMap;
   
public:
   
   gnuPlot();
   
   ~gnuPlot();
 
   ///Connect to gnuplot
   /** Spawns a gnuplot session using popen with stderr redirected to a temporary file.  The temporary file
     * is opened for reading.
     *
     * \retval 0 on success
     * \retval -1 on error
     */ 
   int connect();
   
   ///Return the value of the gpError flag.
   /** This flag is set if gnuplot returns an error message (see checkResponse()).  The error message
     * can be accessed with gpErrorMsg(). 
     *
     * \retval 0 if no error
     * \retval -1 if an error has occurred. 
     */
   bool gpError();
   
   ///Return the gnuplot error message
   /** The error message is extracted by checkResponse() when the response from gnuplot begins with "gnuplot>".
     */
   std::string gpErrorMsg();
   
   ///Send a command to gnuplot
   /** The newline is appended to the command, and then it is sent to gnuplot.
     *
     *
     * \retval 0 on success
     * \retval -1 on error
     */ 
   int command( const std::string & com, ///< [in] the command string
                bool flush = true        ///< [in] [optional] if true (default), then the output stream is flushed once the command is written
              );
     
   ///Check for a response from gnuplot.
   /** It typically takes some time for a response from gnuplot to become readable,
     * whether an error occurs or not. It is often 0.3 seconds or more.  If there is no error, there will be no response so waiting
     * for a response to check for errors after every command can be very time consuming.  Thus it is a choice whether to check 
     * for errors from gnuplot after every command, and what timeout to use. 
     * 
     * \todo investigate having a second thread monitor for responses.
     * 
     * gnuplot terminates all outputs with \c \\n\\n, so this reads up to these two characters.  It then strips any leading and trailing whitespace. 
     * If the response begins with \c gnuplot>, then the response is an error.  In this case, checkResponse returns -1 and the gpError flag is set.  If gpError is not set 
     * but the return value is -1, then some other error occurred (check \c errno).
     * 
     * \retval 0 on timeout or successful read
     * \retval -1 on error, or if the gnuplot response indicates an error.
     */
   int checkResponse( std::string & response, ///< [out] contains the response from gnuplot, but is empty on timeout or error.
                      double timeout = 0      ///< [in] [optional] the length of time, in seconds, to wait for a response. Default is 0, but a minimum of 0.5 if a response is expected.
                    );
   
   ///Get a response from gnuplot for a given command.
   /** This should only be used if a response is expected.
     *
     * \returns "" (empty string) on timeout or error (\c errno and gpError() should be checked), and the response from gnuplot otherwise.
     */ 
   std::string getResponse( const std::string & com, ///< [in] the command string
                            double timeout=0.5       ///< [in] the length of time, in seconds, to wait for a response. Default is 0.5, which is the minimum that should be used.
                          );
 
   
   /// Issue the \b replot command
   /**
     * \retval 0 on success
     * \retval -1 on error
     */
   int replot();
   
   /// Set the x-axis range 
   /** Sends the command:
     * \verbatim
     * set xrange [x0:x1]
     * \endverbatim
     * 
     * \returns 0 on success
     * \returns -1 on error
     */
    int xrange( double x0,
                double x1
              ); 
 
   /// Unset the x-axis range 
   /** Sends the command:
     * \verbatim
     * unset xrange
     * \endverbatim
     * 
     * \returns 0 on success
     * \returns -1 on error
     */
    int xrange(); 
 
    /// Set the y-axis range 
    /** Sends the command:
      * \verbatim
      * set yrange [y0:y1]
      * \endverbatim
      * 
      * \returns 0 on success
      * \returns -1 on error
      */
    int yrange( double y0,
                double y1
              ); 
 
    /// Unset the y-axis range 
    /** Sends the command:
      * \verbatim
      * unset yrange
      * \endverbatim
      * 
      * \returns 0 on success
      * \returns -1 on error
      */
    int yrange();
 
   /// Set the y axis to log scale
   /** Sends the command:
     * \verbatim
       set log y
      \endverbatim
     *
     * \retval 0 on success
     * \retval -1 on error
     */
   int logy();
   
   /// Set the x axis to log scale
   /** Sends the command:
     * \verbatim
       set log x
      \endverbatim
     *
     * \retval 0 on success
     * \retval -1 on error
     */
   int logx();
   
   /// Set the x and y axes to log scale
   /** Sends the commands:
     * \verbatim
       set log x
       set log y
      \endverbatim
     *
     * \retval 0 on success
     * \retval -1 on error
     */
   int logxy();
   
   /// Unset the y axis from log scale
   /** Sends the command:
     * \verbatim
       unset log y
      \endverbatim
     *
     * \retval 0 on success
     * \retval -1 on error
     */
   int ulogy();
   
   /// Unset the x axis from log scale
   /** Sends the command:
     * \verbatim
       unset log x
      \endverbatim
     *
     * \retval 0 on success
     * \retval -1 on error
     */
   int ulogx();
   
   /// Unset the x and y axes from log scale
   /** Sends the command:
     * \verbatim
       unset log x
       unset log y
      \endverbatim
     *
     * \retval 0 on success
     * \retval -1 on error
     */
   int ulogxy();
   
   /// Plot from a file specifying all curve components.
   /** Forms the gnuplot plot command as follows:
     * \verbatim
     * plot '<fname>' <modifiers> t '<title>'
     * \endverbatim
     * The modifiers string can contain any modifiers such as \a using, etc.  Should generally not include \a title.
     * 
     * \retval 0 on success
     * \retval -1 on error
     */
   int plot( const std::string & fname,     ///< [in] the name (with full path) of the file containing data to plot
             const std::string & modifiers, ///< [in] contains any modifiers to the plot command.
             const std::string & title,     ///< [in] the title for this curve
             const std::string & name       ///< [in] the name for this curve.  If "" then curve# is used.
           );
 
   /// Plot from a file without specifying the title
   /** Forms the gnuplot plot command as follows:
     * \verbatim
     * plot '<fname>' <modifiers> t ''
     * \endverbatim
     * The modifiers string can contain any modifiers such as \a using, etc.  Should generally not include \a title.
     * 
     * \retval 0 on success
     * \retval -1 on error
     * 
     * \overload
     */
   int plot( const std::string & fname,     ///< [in] the name (with full path) of the file containing data to plot
             const std::string & modifiers, ///< [in] contains any modifiers to the plot command.
             const std::string & name       ///< [in] the name for this curve.  If "" then the curve# is used.
           );
 
   /// Plot from a file without modifiers
   /** The file name is used for the identifying name
     *  
     * Forms the gnuplot plot command as follows:
     * \verbatim
     * plot '<fname>' <modifiers> t ''
     * \endverbatim
     * The modifiers string can contain any modifiers such as \a using, etc.  Should generally not include \a title.
     * 
     * \retval 0 on success
     * \retval -1 on error
     * 
     * \overload
     */
   int plot( const std::string & fname,     ///< [in] the name (with full path) of the file containing data to plot
             const std::string & name       ///< [in] the name for this curve.  If "" then the curve# is used
           );
 
   /// Plot from a file without specifying the name or any modifiers
   /** The file name is used for the identifying name
     *  
     * Forms the gnuplot plot command as follows:
     * \verbatim
     * plot '<fname>' t ''
     * \endverbatim
     * The modifiers string can contain any modifiers such as \a using, etc.  Should generally not include \a title.
     * 
     * \retval 0 on success
     * \retval -1 on error
     * 
     * \overload
     */
   int plot( const std::string & fname /**< [in] the name (with full path) of the file containing data to plot */  );
   
   /// Plot data from an array
   /** Copies the data in the array to a temporary binary file, and then forms the gnuplot plot command as follows:
     * \verbatim 
     *  plot "temp-file-name" binary format="%dataT" u 1 t "title" <modifiers>
     * \endverbatim
     * The modifiers string \b must \b NOT contain the \b binary, \b format, \b using, or the \b title  modifiers, but can contain any other modifiers.  Title is
     * specified so that the name of the temporary file name is not printed on the plot. 
     *
     * \retval 0 on success
     * \retval -1 on error
     */
   template<typename dataT>
   int plot( const dataT * y,               ///< [in] a pointer to an array of data
             size_t N,                      ///< [in] the length of the array
             const std::string & modifiers, ///< [in] contains any modifiers to the plot command other than \b binary, \b format, \b using, and \b title.
             const std::string & title,     ///< [in] contains the title of the data set, default is an empty string and no key on the plot
             const std::string & name       ///< [in] the identifying name of this curve
           );      
   
   /// Plot data from an array
   /** Copies the data in the array to a temporary binary file, and then forms the gnuplot plot command as follows:
     * \verbatim 
     *  plot "temp-file-name" binary format="%dataT" u 1 t '' <modifiers>
     * \endverbatim
     * The modifiers string \b must \b NOT contain the \b binary, \b format, \b using, or the \b title  modifiers, but can contain any other modifiers.  Title is
     * specified so that the name of the temporary file name is not printed on the plot. 
     *
     * \retval 0 on success
     * \retval -1 on error
     */
   template<typename dataT>
   int plot( const dataT * y,               ///< [in] a pointer to an array of data
             size_t N,                      ///< [in] the length of the array
             const std::string & modifiers, ///< [in] contains any modifiers to the plot command other than \b binary, \b format, \b using, and \b title.
             const std::string & name       ///< [in] the identifying name of this curve
           );
 
   /// Plot data from an array
   /** Copies the data in the array to a temporary binary file, and then forms the gnuplot plot command as follows:
     * \verbatim 
     *  plot "temp-file-name" binary format="%dataT" u 1 t '' <modifiers>
     * \endverbatim
     *
     *
     * \retval 0 on success
     * \retval -1 on error
     */
   template<typename dataT>
   int plot( const dataT * y,               ///< [in] a pointer to an array of data
             size_t N,                      ///< [in] the length of the array
             const std::string & name       ///< [in] the identifying name of this curve
           );
 
   /// Plot data from an array
   /** Copies the data in the array to a temporary binary file, and then forms the gnuplot plot command as follows:
     * \verbatim 
     *  plot "temp-file-name" binary format="%dataT" u 1 t ''
     * \endverbatim
     *
     * \retval 0 on success
     * \retval -1 on error
     */
   template<typename dataT>
   int plot( const dataT * y, ///< [in] a pointer to an array of data
             size_t N         ///< [in] the length of the array
           );
 
 
 
   /// Plot data from a vector
   /** Copies the data in the vector to a temporary binary file, and then forms the gnuplot plot command as follows:
     * \verbatim 
     *  plot "temp-file-name" binary format="%dataT" u 1 t "title" <modifiers>
     * \endverbatim
     * The modifiers string \b must \b NOT contain the \b binary, \b format, \b using, or the \b title  modifiers, but can contain any other modifiers.  Title is
     * specified so that the name of the temporary file name is not printed on the plot. 
     * 
     * \retval 0 on success
     * \retval -1 on error
     */
   template<typename dataT>
   int plot( const std::vector<dataT> & y,  ///< [in] the vector containing the data
             const std::string & modifiers, ///< [in] contains any modifiers to the plot command other than \b binary, \b format, \b using, and \b title.
             const std::string & title,     ///< [in] contains the title of the data set, default is an empty string and no key on the plot
             const std::string & name       ///< [in] the identifying name of this curve
           ); 
   
   /// Plot data from a vector
   /** Copies the data in the vector to a temporary binary file, and then forms the gnuplot plot command as follows:
     * \verbatim 
     *  plot "temp-file-name" binary format="%dataT" u 1 t '' <modifiers>
     * \endverbatim
     * The modifiers string \b must \b NOT contain the \b binary, \b format, \b using, or the \b title  modifiers, but can contain any other modifiers.  Title is
     * specified so that the name of the temporary file name is not printed on the plot. 
     * 
     * \retval 0 on success
     * \retval -1 on error
     */
   template<typename dataT>
   int plot( const std::vector<dataT> & y,  ///< [in] the vector containing the data
             const std::string & modifiers, ///< [in] contains any modifiers to the plot command other than \b binary, \b format, \b using, and \b title.
             const std::string & name       ///< [in] the identifying name of this curve
           );
 
   /// Plot data from a vector
   /** Copies the data in the vector to a temporary binary file, and then forms the gnuplot plot command as follows:
     * \verbatim 
     *  plot "temp-file-name" binary format="%dataT" u 1 t '' 
     * \endverbatim
     * 
     * \retval 0 on success
     * \retval -1 on error
     */
   template<typename dataT>
   int plot( const std::vector<dataT> & y,  ///< [in] the vector containing the data
             const std::string & name       ///< [in] the identifying name of this curve
           );
 
   /// Plot data from a vector
   /** Copies the data in the vector to a temporary binary file, and then forms the gnuplot plot command as follows:
     * \verbatim 
     *  plot "temp-file-name" binary format="%dataT" u 1 t '' 
     * \endverbatim
     * 
     * \retval 0 on success
     * \retval -1 on error
     */
   template<typename dataT>
   int plot( const std::vector<dataT> & y /**< [in] the vector containing the data*/);
 
 
   /// Plot y vs. x data from arrays
   /** Copies the data in the arrays to a temporary binary file, and then forms the gnuplot plot command as follows:
     * \verbatim 
       plot "temp-file-name" binary format="%dataTx%dataTy" u 1:2 t "title" <modifiers>
      \endverbatim
     * The modifiers string \b must \b NOT contain the \b binary, \b format, \b using, or the \b title  modifiers, but can contain any other modifiers.  Title is
     * specified so that the name of the temporary file name is not printed on the plot. 
     * 
     * \retval 0 on success
     * \retval -1 on error
     */
   template<typename dataTx, typename dataTy>
   int plot( const dataTx * x,              ///< [in] a pointer to an array of data for the independent variable
             const dataTy * y,              ///< [in] a pointer to an array of data for the dependent variable
             size_t N,                      ///< [in] the length of the arrays
             const std::string & modifiers, ///< [in] contains any modifiers to the plot command other than \b binary, \b format, \b using, and \b title.
             const std::string & title,     ///< [in] contains the title of the data set
             const std::string & name       ///< [in] the identifying name of the curve
           );
   
   /// Plot y vs. x data from arrays
   /** Copies the data in the arrays to a temporary binary file, and then forms the gnuplot plot command as follows:
     * \verbatim 
     *  plot "temp-file-name" binary format="%dataTx%dataTy" u 1:2 t '' <modifiers>
     * \endverbatim
     * The modifiers string \b must \b NOT contain the \b binary, \b format, \b using, or the \b title  modifiers, but can contain any other modifiers.  Title is
     * specified so that the name of the temporary file name is not printed on the plot. 
     * 
     * \retval 0 on success
     * \retval -1 on error
     */
   template<typename dataTx, typename dataTy>
   int plot( const dataTx * x,              ///< [in] a pointer to an array of data for the independent variable
             const dataTy * y,              ///< [in] a pointer to an array of data for the dependent variable
             size_t N,                      ///< [in] the length of the arrays
             const std::string & modifiers, ///< [in] contains any modifiers to the plot command other than \b binary, \b format, \b using, and \b title.
             const std::string & name       ///< [in] the identifying name of the curve
           );
 
   /// Plot y vs. x data from arrays
   /** Copies the data in the arrays to a temporary binary file, and then forms the gnuplot plot command as follows:
     * \verbatim 
     *  plot "temp-file-name" binary format="%dataTx%dataTy" u 1:2 t ''
     * \endverbatim
     * 
     * \retval 0 on success
     * \retval -1 on error
     */
   template<typename dataTx, typename dataTy>
   int plot( const dataTx * x,              ///< [in] a pointer to an array of data for the independent variable
             const dataTy * y,              ///< [in] a pointer to an array of data for the dependent variable
             size_t N,                      ///< [in] the length of the arrays
             const std::string & name       ///< [in] the identifying name of the curve
           );
 
   /// Plot y vs. x data from arrays
   /** Copies the data in the arrays to a temporary binary file, and then forms the gnuplot plot command as follows:
     * \verbatim 
     *  plot "temp-file-name" binary format="%dataTx%dataTy" u 1:2 t ''
     * \endverbatim
     * 
     * \retval 0 on success
     * \retval -1 on error
     */
   template<typename dataTx, typename dataTy>
   int plot( const dataTx * x,  ///< [in] a pointer to an array of data for the independent variable
             const dataTy * y,  ///< [in] a pointer to an array of data for the dependent variable
             size_t N           ///< [in] the length of the arrays
           );
    
 
   /// Plot y vs. x data from vectors
   /** Copies the data in the vectors to a temporary binary file, and then forms the gnuplot plot command as follows:
     * \verbatim 
       plot "temp-file-name" binary format="%dataTx%dataTy" u 1:2 t "title" <modifiers>
      \endverbatim
     * The modifiers string \b must \b NOT contain the \b binary, \b format, \b using, or the \b title  modifiers, but can contain any other modifiers.  Title is
     * specified so that the name of the temporary file name is not printed on the plot. 
     *
     * \retval 0 on success
     * \retval -1 on error
     */
   template<typename dataTx, typename dataTy>
   int plot( const std::vector<dataTx> & x,  ///< [in] a vector of data for the independent variable
             const std::vector<dataTy> & y,  ///< [in] a vector of data for the dependent variable
             const std::string & modifiers,  ///< [in] contains any modifiers to the plot command other than \b binary, \b format, \b using, and \b title.
             const std::string & title,      ///< [in] contains the title of the data set
             const std::string & name        ///< [in] the identifying name of the curve
           );
   
   /// Plot y vs. x data from vectors
   /** Copies the data in the vectors to a temporary binary file, and then forms the gnuplot plot command as follows:
     * \verbatim 
       plot "temp-file-name" binary format="%dataTx%dataTy" u 1:2 t '' <modifiers>
      \endverbatim
     * The modifiers string \b must \b NOT contain the \b binary, \b format, \b using, or the \b title  modifiers, but can contain any other modifiers.  Title is
     * specified so that the name of the temporary file name is not printed on the plot. 
     *
     * \retval 0 on success
     * \retval -1 on error
     */
   template<typename dataTx, typename dataTy>
   int plot( const std::vector<dataTx> & x,  ///< [in] a vector of data for the independent variable
             const std::vector<dataTy> & y,  ///< [in] a vector of data for the dependent variable
             const std::string & modifiers,  ///< [in] contains any modifiers to the plot command other than \b binary, \b format, \b using, and \b title.
             const std::string & name        ///< [in] the identifying name of the curve
           );
 
   /// Plot y vs. x data from vectors
   /** Copies the data in the vectors to a temporary binary file, and then forms the gnuplot plot command as follows:
     * \verbatim 
     *  plot "temp-file-name" binary format="%dataTx%dataTy" u 1:2 t ''
     * \endverbatim
     *
     * \retval 0 on success
     * \retval -1 on error
     */
   template<typename dataTx, typename dataTy>
   int plot( const std::vector<dataTx> & x,  ///< [in] a vector of data for the independent variable
             const std::vector<dataTy> & y,  ///< [in] a vector of data for the dependent variable
             const std::string & name        ///< [in] the identifying name of the curve
           );
 
   /// Plot y vs. x data from vectors
   /** Copies the data in the vectors to a temporary binary file, and then forms the gnuplot plot command as follows:
     * \verbatim 
     *  plot "temp-file-name" binary format="%dataTx%dataTy" u 1:2 t ''
     * \endverbatim
     *
     * \retval 0 on success
     * \retval -1 on error
     */
   template<typename dataTx, typename dataTy>
   int plot( const std::vector<dataTx> & x,  ///< [in] a vector of data for the independent variable
             const std::vector<dataTy> & y  ///< [in] a vector of data for the dependent variable
           );
 
 
   /// Plot a single point
   /** Copies the position as a length-1 vector to a temporary binary file, and then plots it.
     * 
     *
     * \retval 0 on success
     * \retval -1 on error
     */
   template<typename dataTx, typename dataTy>
   int point( dataTx x,                           ///< [in] the independent axis (x) coordinate of the point
              dataTy y,                           ///< [in] the dependent axis (y) coordinate of the point
              const std::string & modifiers = "", ///< [in] [optional] contains any modifiers to the plot command other than \b binary, \b format, \b using, and \b title.
              const std::string & title = ""      ///< [in] [optional] contains the title of the data set, default is an empty string and no key on the plot
            );
   
   /// Draw a circle on the plot
   /** Creates a circle with specified center and radius, and plots it.
     */
   int circle( double xcen,                        ///< [in] the x-coordinate of the circle center
               double ycen,                        ///< [in] the y-coordinate of the circle center
               double radius,                      ///< [in] the circle radius
               const std::string & modifiers = "", ///< [in] [optional] contains any modifiers to the plot command other than \b binary, \b format, \b using, and \b title.
               const std::string & title = "",     ///< [in] [optional] contains the title of the data set, default is an empty string and no key on the plot
               int npoints =  10                   ///< [in] [optional] specifies the number of points in each half circle.  Default 10 is usually sufficient.
             );
   
   /// Draw a circle on the plot around the origin
   /** Creates a circle with radius and center (0,0), and plots it.
     */
   int circle( double radius,                      ///< [in] the circle radius
               const std::string & modifiers = "", ///< [in] [optional] contains any modifiers to the plot command other than \b binary, \b format, \b using, and \b title.
               const std::string & title = "",     ///< [in] [optional] contains the title of the data set, default is an empty string and no key on the plot
               int npoints =  10                   ///< [in] [optional] specifies the number of points in each half circle.  Default 10 is usually sufficient.
             );
   
    /// Clear all the curves
    void clear();
 
    /// Clear all the curves and reset plot configuration
    void reset();
 
    /// List the curves and their specifications.
    void listCurves();
 
    /// Modify the modifiers for a curve
    void modifiers( const std::string & name,     ///< [in] the name of the curve
                    const std::string & modifiers ///< [in] the new modifiers
                  );
 
    /// Modify the title for a curve
    void title( const std::string & name, ///< [in] the name of the curve
                const std::string & title ///< [in] the new title
              );
 
protected:
   
   /// Implementation of 1-D binary plotting.
   int plotImpl( const void * y, 
                 size_t Nbytes,
                 const std::string & binary,
                 const std::string & modifiers, 
                 const std::string & title,
                 const std::string & name
               );
   
   /// Implementation of 2-d binary plotting.
   int plotImpl( const void * x, 
                 const void * y, 
                 size_t Npts,
                 size_t sizex,
                 size_t sizey,
                 const std::string & binaryx,
                 const std::string & binaryy,
                 const std::string & modifiers, 
                 const std::string & title,
                 const std::string & name
               );
 
   /// Issue the plot command for all the curves
   int doPlotCommand();
 
   ///Open a temporary binary file, and provide the filename. 
   FILE * openTempFile(char * fname);
   
 
 
private:
   ///Initialize an instance, only used at construction
   void init();
   
   
};
 
 
 
template<typename dataT>
int gnuPlot::plot( const dataT * y, 
                   size_t N,  
                   const std::string & modifiers, 
                   const std::string & title,
                   const std::string & name
                 )
{
   return plotImpl(y, N*sizeof(dataT), gpBinaryFormat<dataT>(), modifiers, title, name);
}
  
template<typename dataT>
int gnuPlot::plot( const dataT * y, 
                   size_t N,  
                   const std::string & modifiers, 
                   const std::string & name
                 )
{
   return plotImpl(y, N*sizeof(dataT), gpBinaryFormat<dataT>(), modifiers, "", name);
}
 
template<typename dataT>
int gnuPlot::plot( const dataT * y, 
                   size_t N,  
                   const std::string & name
                 )
{
   return plotImpl(y, N*sizeof(dataT), gpBinaryFormat<dataT>(), "", "", name);
}
 
template<typename dataT>
int gnuPlot::plot( const dataT * y, 
                   size_t N
                 )
{
   return plotImpl(y, N*sizeof(dataT), gpBinaryFormat<dataT>(), "", "", "");
}
 
template<typename dataT>
int gnuPlot::plot( const std::vector<dataT> & y, 
                   const std::string & modifiers, 
                   const std::string & title,
                   const std::string & name
                 )
{
   return plot<dataT>( y.data(), y.size(), modifiers, title, name);
}
 
template<typename dataT>
int gnuPlot::plot( const std::vector<dataT> & y, 
                   const std::string & modifiers, 
                   const std::string & name
                 )
{
   return plot<dataT>( y.data(), y.size(), modifiers, "", name);
}
 
template<typename dataT>
int gnuPlot::plot( const std::vector<dataT> & y, 
                   const std::string & name
                 )
{
   return plot<dataT>( y.data(), y.size(), "", "", name);
}
 
template<typename dataT>
int gnuPlot::plot( const std::vector<dataT> & y)
{
   return plot<dataT>( y.data(), y.size(), "", "", "");
}
 
 
template<typename dataTx, typename dataTy>
int gnuPlot::plot( const dataTx * x, 
                   const dataTy * y, 
                   size_t N, 
                   const std::string & modifiers, 
                   const std::string & title,
                   const std::string & name
                 )
{
   return plotImpl(x, y, N, sizeof(dataTx), sizeof(dataTy), gpBinaryFormat<dataTx>(), gpBinaryFormat<dataTy>(), modifiers, title, name);
}
 
template<typename dataTx, typename dataTy>
int gnuPlot::plot( const dataTx * x, 
                   const dataTy * y, 
                   size_t N, 
                   const std::string & modifiers, 
                   const std::string & name
                 )
{
   return plotImpl(x, y, N, sizeof(dataTx), sizeof(dataTy), gpBinaryFormat<dataTx>(), gpBinaryFormat<dataTy>(), modifiers, "", name);
}
 
template<typename dataTx, typename dataTy>
int gnuPlot::plot( const dataTx * x, 
                   const dataTy * y, 
                   size_t N, 
                   const std::string & name
                 )
{
   return plotImpl(x, y, N, sizeof(dataTx), sizeof(dataTy), gpBinaryFormat<dataTx>(), gpBinaryFormat<dataTy>(), "", "", name);
}
 
template<typename dataTx, typename dataTy>
int gnuPlot::plot( const dataTx * x, 
                   const dataTy * y, 
                   size_t N
                 )
{
   return plotImpl(x, y, N, sizeof(dataTx), sizeof(dataTy), gpBinaryFormat<dataTx>(), gpBinaryFormat<dataTy>(), "", "", "");
}
 
template<typename dataTx, typename dataTy>
int gnuPlot::plot( const std::vector<dataTx> & x, 
                   const std::vector<dataTy> & y, 
                   const std::string & modifiers, 
                   const std::string & title,
                   const std::string & name
                 )
{
   return plot( x.data(), y.data(), x.size(), modifiers, title, name);
}
 
template<typename dataTx, typename dataTy>
int gnuPlot::plot( const std::vector<dataTx> & x, 
                   const std::vector<dataTy> & y, 
                   const std::string & modifiers, 
                   const std::string & name
                 )
{
   return plot( x.data(), y.data(), x.size(), modifiers, "", name);
}
 
template<typename dataTx, typename dataTy>
int gnuPlot::plot( const std::vector<dataTx> & x, 
                   const std::vector<dataTy> & y, 
                   const std::string & name
                 )
{
   return plot( x.data(), y.data(), x.size(), "", "", name);
}
 
template<typename dataTx, typename dataTy>
int gnuPlot::plot( const std::vector<dataTx> & x, 
                   const std::vector<dataTy> & y 
                 )
{
   return plot( x.data(), y.data(), x.size(), "", "", "");
}
 
template<typename dataTx, typename dataTy>
int gnuPlot::point( dataTx x, 
                    dataTy y, 
                    const std::string & modifiers, 
                    const std::string & title
                  )
{
   
   return plot(&x, &y, 1, modifiers, title);
}
 
template<>
std::string gpBinaryFormat<char>();
 
template<>
std::string gpBinaryFormat<unsigned char>();
 
template<>
std::string gpBinaryFormat<short>();
 
template<>
std::string gpBinaryFormat<unsigned short>();
 
template<>
std::string gpBinaryFormat<int>();
 
template<>
std::string gpBinaryFormat<unsigned int>();
 
template<>
std::string gpBinaryFormat<long>();
 
template<>
std::string gpBinaryFormat<unsigned long>();
 
template<>
std::string gpBinaryFormat<float>();
 
template<>
std::string gpBinaryFormat<double>();
 
}//namespace math
}//namespace mx
 
   
#endif //math_plot_gnuPlot_hpp