#
# = Interpolation
# This chapter describes functions for performing interpolation.
# The library provides a variety of interpolation methods, including
# Cubic splines and Akima splines. The interpolation types are interchangeable,
# allowing different methods to be used without recompiling. Interpolations can
# be defined for both normal and periodic boundary conditions. Additional
# functions are available for computing derivatives and integrals of
# interpolating functions.
#
# 1. {Interpolation classes}[link:rdoc/interp_rdoc.html#label-Interpolation+Classes]
# 1. {Initializing interpolation objects}[link:rdoc/interp_rdoc.html#label-Initializing+interpolation+objects]
# 1. {Index Look-up and Acceleration}[link:rdoc/interp_rdoc.html#label-Index+Look-up+and+Acceleration]
# 1. {Evaluation of Interpolating Functions}[link:rdoc/interp_rdoc.html#label-Evaluation+of+Interpolating+Functions]
# 1. {Higher level interface: GSL::Spline class}[link:rdoc/interp_rdoc.html#label-Higher+level+interface]
#    1. {Class initialization}[link:rdoc/interp_rdoc.html#label-Class+initialization]
#    1. {Evaluation}[link:rdoc/interp_rdoc.html#label-Evaluation]
#    1. {Finding and acceleration}[link:rdoc/interp_rdoc.html#label-Finding+and+acceleration]
#
# == Interpolation Classes
# * GSL
#   * Interp (class)
#     * Accel (class)
#   * Spline (class)
#
# == Initializing interpolation objects
#
# ---
# * GSL::Interp.alloc(T, n)
# * GSL::Interp.alloc(T, x, y)
# * GSL::Interp.alloc(x, y)
#
#   These methods create an  interpolation object of type <tt>T</tt> for <tt>n</tt>
#   data-points.
#
#   The library provides six types, which are specifiled by an identifier of a
#   constant or a string:
#
#   * Interp::LINEAR or "linear"
#
#     Linear interpolation. This interpolation method does not require any additional memory.
#   * Interp::POLYNOMIAL or "polynomial"
#
#     Polynomial interpolation. This method should only be used for interpolating small numbers of points because polynomial interpolation introduces large oscillations, even for well-behaved datasets. The number of terms in the interpolating polynomial is equal to the number of points.
#
#   * Interp::CSPLINE or "cspline"
#
#     Cubic spline with natural boundary conditions.
#   * Interp::CSPLINE_PERIODIC or "gsl_cspline_periodic" or "cspline_periodic"
#
#     Cubic spline with periodic boundary conditions
#   * Interp::AKIMA or "akima"
#
#     Non-rounded Akima spline with natural boundary conditions. This method uses the non-rounded corner algorithm of Wodicka.
#   * Interp::AKIMA_PERIODIC or "akima_periodic"
#
#     Non-rounded Akima spline with periodic boundary conditions. This method uses the non-rounded corner algorithm of Wodicka.
#
#     * ex: For cubic spline for 10 points,
#         sp = Interp.alloc("cspline", 10)
#
# ---
# * GSL::Interp#init(xa, ya)
#
#   This method initializes the interpolation object interp for the data
#   <tt>(xa,ya)</tt> where <tt>xa</tt> and <tt>ya</tt> are vectors.
#   The interpolation object (<tt>GSL::Interp</tt>) does not save the data
#   vectors <tt>xa, ya</tt> and only stores the static state computed from the data.
#   The <tt>xa</tt> vector is always assumed to be strictly ordered; the behavior
#   for other arrangements is not defined.
#
#
# ---
# * GSL::Interp#name
#
#   This returns the name of the interpolation type used by <tt>self</tt>.
#
#
#
# ---
# * GSL::Interp#min_size
#
#   This returns the minimum number of points required by the interpolation
#   type of <tt>self</tt>. For example, Akima spline interpolation requires
#   a minimum of 5 points.
#
# == Index Look-up and Acceleration
# ---
# * GSL::Interp.bsearch(xa, x, index_lo, index_hi)
#
#   This returns the index i of the vector <tt>xa</tt> such that
#   <tt>xa[i] <= x < x[i+1]</tt>. The index is searched for in the range
#   <tt>[index_lo,index_hi]</tt>.
#
#
# ---
# * GSL::Interp#accel
#
#   In C level, the library requires a <tt>gsl_interp_accel</tt> object,
#   but it is hidden in Ruby/GSL. It is automatically allocated
#   when a <tt>GSL::Interp</tt> object is created, stored in it,
#   and destroyed when the <tt>Interp</tt> object
#   is cleaned by the Ruby GC.
#   This method is used to access to the <tt>Interp::Accel</tt> object
#   stored in <tt>self</tt>.
#
# ---
# * GSL::Interp#find(xa, x)
# * GSL::Interp#accel_find(xa, x)
# * GSL::Interp::Accel#find(xa, x)
#
#   This method performs a lookup action on the data array <tt>xa</tt>.
#   This is how lookups are performed during evaluation
#   of an interpolation. The function returns an index <tt>i</tt> such that
#   <tt>xa[i] <= x < xa[i+1]</tt>.
#
#
# == Evaluation of Interpolating Functions
#
# ---
# * GSL::Interp#eval(xa, ya, x)
# * GSL::Interp#eval_e(xa, ya, x)
#
#   These methods return the interpolated value for a given point <tt>x</tt>,
#   using the interpolation object <tt>self</tt>, data vectors <tt>xa</tt> and <tt>ya</tt>.
#   The data <tt>x</tt> can be a <tt>Numeric, Vector, Matrix</tt> or an <tt>NArray</tt>.
# ---
# * GSL::Interp#eval_deriv(xa, ya, x)
# * GSL::Interp#eval_deriv_e(xa, ya, x)
#
#   These methods return the derivative of an interpolated function for a
#   given point <tt>x</tt>, using the interpolation object <tt>self</tt>,
#   data vectors <tt>xa</tt> and <tt>ya</tt>.
#
# ---
# * GSL::Interp#eval_deriv2(xa, ya, x)
# * GSL::Interp#eval_deriv2_e(xa, ya, x)
#
#   These methods return the second derivative of an interpolated function
#   for a given point <tt>x</tt>, using the interpolation object <tt>self</tt>,
#   data vectors <tt>xa</tt> and <tt>ya</tt>.
#
# ---
# * GSL::Interp#eval_integ(xa, ya, a, b)
# * GSL::Interp#eval_integ_e(xa, ya, a, b)
#
#   These methods return the numerical integral result of an interpolated
#   function over the range <tt>[a, b]</tt>, using the interpolation object <tt>self</tt>,
#   data vectors <tt>xa</tt> and <tt>ya</tt>.
#
# == Higher level interface
# === Class initialization
#
# ---
# * GSL::Spline.alloc(T, n)
# * GSL::Spline.alloc(T, x, y)
# * GSL::Spline.alloc(x, y, T)
#
#   This creates a <tt>GSL::Spline</tt> object of type <tt>T</tt> for <tt>n</tt>
#   data-points. The type <tt>T</tt> is the same as <tt>GSL::Interp</tt> class.
#
#   These two are equivalent.
#   * <tt>GSL::Spline.alloc</tt> and <tt>GSL::Spline#init</tt>
#       sp = GSL::Spline.alloc(T, n)
#       sp.init(x, y)                 # x and y are vectors of length n
#   * <tt>GSL::Spline.alloc</tt> with two vectors
#       sp = GSL::Spline.alloc(T, x, y)
#   If <tt>T</tt> is not given, "cspline" is used.
#
# ---
# * GSL::Spline#init(xa, ya)
#
#   This initializes a <tt>GSL::Spline</tt> object <tt>self</tt> for the data
#   (<tt>xa, ya</tt>) where <tt>xa</tt> and <tt>ya</tt> are Ruby arrays of equal sizes
#   or <tt>GSL::Vector</tt>.
#
# ---
# * GSL::Spline#name
#
#   This returns the name of the spline type used by <tt>self</tt>.
#
# === Evaluation
# ---
# * GSL::Spline#eval(x)
#
#   This returns the interpolated value for a given point <tt>x</tt>.
#   The data <tt>x</tt> can be a <tt>Numeric, Vector, Matrix</tt> or an <tt>NArray</tt>.
#
#   NOTE: In a GSL-C program, a <tt>gsl_interp_accel</tt> object is required to use
#   the function <tt>gsl_spline_eval</tt>.
#   In Ruby/GSL, the <tt>gsl_interp_accel</tt> is hidden, it is automatically
#   allocated when a <tt>GSL::Spline</tt> object is created,
#   and also destroyed when the <tt>Spline</tt> object
#   is cleaned by the Ruby GC. The accel object can be accessed via the method
#   <tt>GSL::Spline#accel</tt>.
#
# ---
# * GSL::Spline#eval_deriv(x)
#
#   This returns the derivative of an interpolated function for a given point <tt>x</tt>, usingthe data arrays <tt>xa</tt> and <tt>ya</tt> set by <tt>init</tt>.
#
# ---
# * GSL::Spline#eval_deriv2(x)
#
#   This returns the second derivative at <tt>x</tt>.
#
# ---
# * GSL::Spline#eval_integ(a, b)
#
#   Returns the numerical integral over the range [<tt>a, b</tt>].
#
# === Finding and acceleration
# ---
# * GSL::Spline#find(xa, x)
# * GSL::Spline#accel_find(xa, x)
#
#   This method performs a lookup action on the data array <tt>xa</tt>.
#   This is how lookups are performed during evaluation
#   of an interpolation. The function returns an index <tt>i</tt> such that
#   <tt>xa[i] <= x < xa[i+1]</tt>.
#
# See also the GSL manual and the examples in <tt>examples/</tt>
#
# {prev}[link:rdoc/odeiv_rdoc.html]
# {next}[link:rdoc/diff_rdoc.html]
#
# {Reference index}[link:rdoc/ref_rdoc.html]
# {top}[link:index.html]
#
#
#
