Spline Documentation
--------------------

By Ruben Rostamian

---------------------------------------------------------------------------
This is version 2.0 of SPLINE.  SPLINE generates a piecewise cubic and twice
continuously differentiable interpolation y(x) of a set of points (x_i,y_i),
i=1,2,...,n.  It is assumed throughout that x_1 < x_2 < ... < x_n.

SPLINE's default action is to generate a _natural_ cubic spline, i.e., the
second derivative y'' vanishes at the end points x_1 and x_n.  The default
action of SPLINE may be modified by specifying optional switches which are
described later.

------- INPUT --------------------------------------------------------
SPLINE reads its input from the stack.  The n coordinate points may be
specified in two different formats:

THE COORDINATE-PAIRS INPUT FORMAT:
n+1: (x_1,y_1)
n:   (x_2,y_2)
     ...
2:   (x_n,y_n)
1:           n

THE ARRAY INPUT FORMAT:
2:   [ y_1 y_2 ... y_n ]
1:           [ x_1 x_n ]

In the ARRAY input format the interval [x_1 x_n] is automatically divided
into n equally spaced nodes.  The COORDINATE-PAIRS format is useful if
the nodes are not equally spaced.

----------- OUTPUT ----------------------------------------------------
The output of SPLINE is a *program* which can be used as a user-defined
function.  The program, which is placed on level 1 of the stack, has the 
following general format:

1: << -> X 
      << 
          Description of the spline curve here
      >>
   >>

This program may be stored in a variable, say TRY, and may be
evaluated as "TRY(X)" (algebraic mode) or as "X TRY" (RPL mode.)
TRY(X) may be plotted with the usual plotting commands.

-------- OPTIONAL SWITCHES ---------------------------------------------
o  SPLINE by default imposes the natural boundary conditions
y''(x_1) = y''(x_n) = 0.  It is possible to specify instead the first
derivatives a := y'(x_1) and b := y'(x_n) as boundary conditions.
For this, enter the data in one of the two formats described
before, then push the list { a b } into the level 1 of stack.

o  SPLINE can also return the first derivative y'(x) and the second
derivative y''(x) of the cubic spline interpolant.  To get these, enter 
data as before, optionally enter the list { a b } from the
previous paragraph, then push the characters 'D1' into level 1
to compute y'(x), or 'D2' to compute y''(x).

---------- EXAMPLES --------------------------------------------------
Example 1:
    5:  (0,0)
    4:  (1,1)
    3:  (2,4)
    2: (4,16)
    1:     4

SPLINE returns the program:

1: << -> X
  <<
    CASE 'X' 2 >=
      THEN '2.60869565217*(4-X)^3/2/6+6.86956521739*(X-2)+2.26086956522'
      END 'X' 1 >=
      THEN '(2.34782608696*(2-X)^3+2.60869565217*(X-1)^3)/6
	                 +2.95652173913*(X-1)+.608695652173'
      END  '2.34782608696X^3/6+.608695652173*X'
    END EVAL
  >>
>>

Example 2a:
    2: [ 0 1 0 1 0 1 0 ]
    1:           [ 0 9 ]

The second derivative is zero at the end points.

Example 2b:
    3: [ 0 1 0 1 0 1 0 ]
    2:           [ 0 9 ]
    1:           { 0 0 }

The first derivative is  zero at the ends.   Replacing { 0 0 } by { 1 -1 }
makes the first derivative equal 1 and -1 at the ends.

Example 2c:
    4: [ 0 1 0 1 0 1 0 ]
    3:           [ 0 9 ]
    2:           { 0 0 }
    1:              'D1'

Computes the first derivative y'(x) of the spline y(x) of example 2b.
Replacing 'D1' with 'D2' will computes the second derivative.   It is
instructive to save y(x), y'(x), and y''(x) into variables Y0, Y1, and Y2,
and PLOT { 'Y2(X)' 'Y1(X)' Y0(X)' } with XRANGE set to 0,9 and AUTO.

-------- REFERENCE -----------------------------------------------------
Stoer and Bulirsch, Numerical Analysis

-------- REMARKS -------------------------------------------------------
SPLINE does not use, change, create or modify any global variables.
It does not modify parts of the stack it does not own and does not
alter any system flags, although the calculator has to be in the
symbolic mode for SPLINE to operate.   It clears _user_ flags 6,7,8,9.

-------- NOTES ---------------------------------------------------------
SPLINE V2.0 is completely different from an earlier version (no version
number).  This new version generates code which executes about 4 times
faster than the previous version. It also has many additional features.
I will not describe the differences here because because I consider
the previous version obsolete.

-------- PROGRAM OBJECT CHECKSUMS --------------------------------------
Checksum: #3B69h
Bytes:      2212
