#
# = Graphics
#
# The GSL library itself does not include any utilities to visualize computation results.
# Some examples found in the GSL manual use 
# {GNU graph}[http://www.gnu.org/software/plotutils/plotutils.html"target="_top] 
# to show the results: the data are stored in data files, and then
# displayed by using <tt>GNU graph</tt>.
# Ruby/GSL provides simple interfaces to <tt>GNU graph</tt>
# to plot vectors or histograms directly without storing them in data files.
# Although the methods described below do not cover all the functionalities 
# of <tt>GNU graph</tt>, these are useful to check calculations and get some 
# speculations on the data.
#
#
# == {}[link:index.html"name="1] Plotting vectors
# ---
# * Vector.graph(y[,  options])
# * Vector.graph(nil, y[, y2, y3, ...,  options])
# * Vector.graph(x, y1, y2, ...., options)
# * Vector.graph([x1, y1], [x2, y2], ...., options)
# * GSL::graph(y[, options])
# * GSL::graph(nil, y[, y2, y3, ...,  options])
# * GSL::graph(x, y1, y2, ...., options)
# * GSL::graph([x1, y1], [x2, y2], ...., options)
#
#   These methods use the <tt>GNU graph</tt> utility to plot vectors.
#   The options <tt>options</tt> given by a <tt>String</tt>. If <tt>nil</tt> is 
#   given for <tt>ARGV[0]</tt>, auto-generated abscissa are used.
#
#   Ex:
#      >> require("gsl")
#      >> x = Vector.linspace(0, 2.0*M_PI, 20)
#      >> c = Sf::cos(x)
#      >> s = Sf::sin(x)
#      >> Vector.graph(x, c, s, "-T X -C -L 'cos(x), sin(x)'")
#
#   This is equivalent to <tt>Vector.graph([x, c], [x, s], "-T X -C -L 'cos(x), sin(x)'")</tt>.
#
#   To create a PNG file,
#      >> Vector.graph(x, c, s, "-T png -C -L 'cos(x), sin(x)' > fig.png")
#
# ---
# * GSL::Vector#graph(options)
# * GSL::Vector#graph(x[, options])
#
#   These methods plot the vector using the GNU <tt>graph</tt> 
#   command. The options for the <tt>graph</tt> command are given by a <tt>String</tt>.
#
#   Ex1:  
#        >> x = Vector[1..5]
#        [ 1.000e+00 2.000e+00 3.000e+00 4.000e+00 5.000e+00 ]
#        >> x.graph("-m 2")      # dotted line
#        >> x.graph("-C -l x")   # color, x log scale
#        >> x.graph("-X \"X axis\"")  # with an axis label
#
#   Ex2: x-y plot
#        >> require("gsl")
#        >> x = Vector.linspace(0, 2.0*M_PI, 20)
#        >> c = Sf::cos(x)
#        >> c.graph(x, "-T X -C -g 3 -L 'cos(x)'")
#
# == {}[link:index.html"name="2] Drawing histogram 
# ---
# * GSL::Histogram#graph(options)
#
#   This method uses the GNU plotutils <tt>graph</tt> to draw a histogram.
#
# == {}[link:index.html"name="3] Plotting Functions
# ---
# * GSL::Function#graph(x[, options])
#
#   This method uses <tt>GNU graph</tt> to plot the function <tt>self</tt>.
#   The argument <tt>x</tt> is given by a <tt>GSL::Vector</tt> or an <tt>Array</tt>.
#
#   Ex: Plot sin(x)
#        f = Function.alloc { |x| Math::sin(x) }
#        x = Vector.linspace(0, 2*M_PI, 50)
#        f.graph(x, "-T X -g 3 -C -L 'sin(x)'")
#
# == {}[link:index.html"name="4] Other way
# The code below uses <tt>GNUPLOT</tt> directly to plot vectors.
#
#        #!/usr/bin/env ruby
#        require("gsl")
#        x = Vector.linspace(0, 2*M_PI, 50)
#        y = Sf::sin(x)
#        IO.popen("gnuplot -persist", "w") do |io|
#          io.print("plot '-'\n")
#          x.each_index do |i|
#            io.printf("%e %e\n", x[i], y[i])
#          end
#          io.print("e\n")
#          io.flush
#        end
#
# It is also possible to use the Ruby Gnuplot library.
#      require("gnuplot")
#      require("gsl")
#      require("gsl/gnuplot");
#
#      Gnuplot.open do |gp|
#        Gnuplot::Plot.new( gp ) do |plot|
#   
#          plot.xrange "[0:10]"
#          plot.yrange "[-1.5:1.5]"
#          plot.title  "Sin Wave Example"
#          plot.xlabel "x"
#          plot.ylabel "sin(x)"
#          plot.pointsize 3
#          plot.grid 
#
#          x = GSL::Vector[0..10]
#          y = GSL::Sf::sin(x)
#
#          plot.data = [
#            Gnuplot::DataSet.new( "sin(x)" ) { |ds|
#              ds.with = "lines"
#              ds.title = "String function"
#              ds.linewidth = 4
#            },
#         
#            Gnuplot::DataSet.new( [x, y] ) { |ds|
#              ds.with = "linespoints"
#              ds.title = "Array data"
#            }
#          ]
#
#        end
#      end
#
# {prev}[link:files/rdoc/const_rdoc.html]
#
# {Reference index}[link:files/rdoc/ref_rdoc.html]
# {top}[link:files/rdoc/index_rdoc.html]
#
#