BTSpline1D.hh

Go to the documentation of this file.

// @(#) $Id: BTSpline1D.hh,v 1.1 2005/08/20 21:45:11 tjrob Exp $  $Name:  $
//
// ********************************************************************
// * DISCLAIMER                                                       *
// *                                                                  *
// * Neither the authors of this software system, nor their employing *
// * institutes,nor the agencies providing financial support for this *
// * work  make  any representation or  warranty, express or implied, *
// * regarding  this  software system or assume any liability for its *
// * use.                                                             *
// *                                                                  *
// * This  code  implementation is the  intellectual property  of     *
// * FERMILAB.                                                        *
// * By copying,  distributing  or modifying the Program (or any work *
// * based  on  the Program)  you indicate  your  acceptance of  this *
// * statement, and all its terms.                                    *
// ********************************************************************
//
//
// BTSpline1D.hh
//
// Created: Mark Fishler (5/00)
//    

#ifndef BTSPLINE1D_H
#define BTSPLINE1D_H

// The BTSpline1D class represents a table-driven cubic spline in 1 dimension.
// The user supplies the table or the function to the constructor; thereafter, 
// the spline is invoked as if it were a simple function of the input value x, 
// as in 
//
//     double answer = mySpline ( x );
//
// The spline requires (or pre-computes) values of gradient at each point in
// the table.  For cases where the gradient is known analytically, these may be
// supplied directly.  Normally, the spline would be fed just the function or
// values at the grid points; the gradients are pre-computed from the condition
// that the function has a continuous second derivative.  

// A related class is BTSpline, for an N-dimensional cubic spline taking
// an array instead of a value for x.  The general BTSpline class is correct
// for 1 dimension, but involves a bit of extra overhead, and the inconvenience
// of requiring a pointer to the value x (rather than the value itself) because
// it will treat x[] as an array of dimension 1.  

// See BTSpline.h.

#ifdef BTSpline_DESIGN

The BTSpline1D class is an object representing the transformation between some
value x and a value phi, based on tables of values and gradients (derivatives).
The values and gradients are computed (or supplied) at a set of points 
(we call these node points) upon construction. These node points may be 
irregularly spaced. 

From then on, the user can invoke the () operator supplying the value of x;
the operator returns the value of the function phi, based on an interpolating 
function which exactly matches the values and slopes at every node point.

A given instance of a BTSpline is constructed from:

 (1) An integer extent of the array defining the node points.
 (2) An array of N numbers representing the coordinates of each node points.
 (3) The values and optionally the gradients of phi at those node points.  

For convenience, the value and gradient information can be supplied in
any of several ways:

* A pointer to a function returning a double which takes a double x.  If this 
  is supplied, then the constructor will call the function however many times 
  to fill in the tables of values at the node points.  It will then compute
  the gradients needed for continuity in the second derivative, using "natural"
  boundary conditions (second derivative zero at both ends).

* A single table containing the value for each point.  Again, derivatives are 
  comuted using "natural" boundary conditions.

* Either a pointer to a function or a table, as above, followed by two 
  additional arguments which represent the values  of slope at the beginnng 
  and end boundaries; 

* A table of values and a separate table of one gradients (derivative) per 
  point.  

* A pointer to a function returning a void, which takes a double x and
  two pointers to value and gradient.  If this is supplied, then the 
  constructor will call the function however many times to fill in the
  tables of values and gradients at the node points.

The tables are captured in the class instance data, and may be discarded after
construction.

The only user-relevant method other than the constructor is 
        double operator() ( double x ) const;
that is, supplying a x for the desired sample point and receiving a double 
value
of phi.  The value returned is a cubic function in each interval which will
match the values and the gradients at every node.

The class does NOT verify that x lies within the domain defined by the node
points; if it is outside, then the value obtained is still a valid
approximation, but one which will get worse as the distance from the nearest 
node grows large.

#endif

class BTSpline1D {

// The usage of the spline, and any functions provided, are based on doubles.  
// However, for space purposes, the class might be reconfigured to store (and 
// accept) tables in the float format.  

typedef double Data_t;          // In the future we MAY want to template off
                                // the type of table data; using Data_t for
                                // this purpose will make this easy.

public:

  // Invoke the spline to get a value:

  double operator() ( double x ) const;

  // (Deep) copy constructor

  BTSpline1D ( const BTSpline1D & s );
  BTSpline1D (  );
  
  

  // Constructors A -- the class accepts value info in two ways, and optionally
  //                   accepts boundary slope info (if that is not provided, 
  //                   then the second derivative is set to 0 at boundaries).

#ifdef FUTURE

  BTSpline1D (  
          const std::vector<Data_t> nodes, // Locations in x of nodes 
          const std::vector<Data_t> values // Values being approximated
  );

  BTSpline1D (  
          const std::vector<Data_t> nodes, // Locations in x of nodes 
          const std::vector<Data_t> values,// Values being approximated
          Data_t slope0, Data_t slopeN
  );

#endif // FUTURE

  BTSpline1D (  
          int extent,                      // Number of node points
          const Data_t* nodes,             // Locations in x of nodes 
          const Data_t* values             // Values being approximated
  );

  BTSpline1D (  
          int extent,                      // Number of node points
          const Data_t* nodes,             // Locations in x of nodes 
          double values_function (double x)// Function being approximated
  );

  BTSpline1D (  
          int extent,                      // Number of node points
          const Data_t* nodes,             // Locations in x of nodes 
          const Data_t* values,            // Values being approximated
          Data_t slope0, Data_t slopeN
  );

  BTSpline1D (  
          int extent,                      // Number of node points
          const Data_t* nodes,             // Locations in x of nodes 
          double values_function (double x), // Function being approximated
          Data_t slope0, Data_t slopeN
  );

  // Constructors B -- the class accepts value and gradient info in three ways:

#ifdef FUTURE

  BTSpline1D (  
          const std::vector<Data_t> nodes,    // Locations in x of nodes 
          const std::vector<Data_t> values,   // Values at each node point
          const std::vector<Data_t> gradients // derivatives at each node point
  );

  // And some appropriate form for passing a values/grads function.

#endif // FUTURE

  BTSpline1D (  
          int extent,                   // Number of node points
          const Data_t* nodes,          // Locations in x of nodes 
          const Data_t* values,         // values at each node point
          const Data_t* gradients       // derivatives at each node point
                                        // nodes, values, gradients are arrays
                                        // of extent Data_ts.
           );

  BTSpline1D (
          int extent,                   // Number of node points
          const Data_t* nodes,          // Locations in x of nodes 
          void values_grads_function (
                double x, 
                double* val, 
                double* grads)
                                        // Function filling value and 
                                        // gradient for input x
           );

  ~BTSpline1D();

protected:

  // member data:

  int     extent_;
  Data_t*  nodePoints_; 
  Data_t*  distances_;          // distances separating nodes
  Data_t*  values_;
  Data_t*  grads_;
  Data_t*  secondDerivs_;

  bool    naturalBoundaryConditions;
  Data_t  slope0_;
  Data_t  slopeN_;
    
  // internal methods:

  void captureGrid( int extent, const Data_t* nodes );
  void captureValues( int extent, const Data_t* values );
  void fillValues( int extent, double values_function(double x));
  void computeSecondDerivs();

}; // BTSpline

#endif // BTSPLINE1D_H