.TH CSPLINE 1carl
.SH NAME
cspline \- smooth curve interpolater for cmusic
.SH SYNOPSIS
.B cspline
len_flag x0 y0 x1 y1... xN yN
.sp
where len_flag is e.g.: -L1024.
.SH DESCRIPTION
.B cspline
is an implementation of a ``gen'' function call for 
.I cmusic(carl).
.B cspline
is similar in behavior to 
.I spline(1g)
except that it
takes pairs of numbers from the command line (rather than the
standard input) as abcissas and ordinates of a function.
It produces a similar set, which
is approximately equally spaced and
includes the input set, on the standard output.
The output format is binary floating point, suitable for input to
cmusic.  If the standard output is a terminal, the decimal values of
the function are printed instead.
The cubic cspline output
(R. W. Hamming,
.ft I
Numerical Methods for Scientists and Engineers,
.ft R
2nd ed., 349ff)
has two continuous derivatives,
and sufficiently many points to look smooth when plotted, for
example by
.IR  graph (1).  
It is similar to 
.I cmusic's
.I gen4
smooth function generator, except that whereas for 
.I gen4 
you must supply
transition parameters to create a smooth function,
.B cspline
accomplishes this for you automatically.
.PP
Here is a sample call from a shell:
.sp
% cspline -L1024 0 0 .1 .1 .2 1 .3 0
.sp
and a sample statement in a cmusic score:
.sp
gen 0 cspline f1 0 0 .1 .1 .2 1 .3 0;
.PP
In addition, the same options are available as for
.B spline,
but the syntax is different:  
.sp
.B cspline
[flags] x0 y0 x1 y1... xN yN
.sp
where a flag is -xO, x is a character, O is an argument to the flag,
concatenated to it, e.g.: -l1.4.
.TP 5
.B  \-k
The constant
.IR k ""
used in the boundary value computation
.IP
By default
.IR k ""
= 0.
.TP 5
.B  -p or -c
Make output periodic ("cyclic"), i.e. match
derivatives at ends.
First and last input values should normally agree.
Note: for cspline this usually doesn't work because of the rescaling
done by the linear interpolation stage.
.SH Other Considerations
Whereas
for 
.I spline
the number of output points is only approximate, for 
.B cspline
the number of output points is constrained to be 
.I exactly
the number specified.
In those cases where the spline algorithm supplies fewer or more points
than specified, this is accomplished by linear interpolation to stretch
or shrink the function to fit.
.PP
Whereas \fIspline\fR
produces as its output function the 
\fIretrograde\fR of its input function, \fBcspline\fR
produces the function in its prime form, which is how you want it
for cmusic and most other applications.
.PP
Given the differences, and the automatic nature of the smoothing
process, it is wise to preview the function generated by
\fBcspline\fR with \fIgraph(1)\fR or \fIshow(carl)\fR
before using it in a score.
.SH SEE ALSO
cmusic(carl)
.SH DIAGNOSTICS
When data is not strictly monotone in
.I x,
.B cspline
throws up, (unlike 
.I spline, 
which simply returns the function you sent it).
.SH BUGS
A limit of 1024 input points is enforced silently (upped from 1000 points
silently enforced in 
.I spline).
.PP
The result of the spline function may not entirely lie in the signed
unit interval [-1,+1].  Stuff it through gen0 to normalize it.
.SH BUGS
.I cmusic
gen functions must accept -c and -o flags for "closed" and "open" mode.
.B cspline
only usefully produces -o format functions.  If you supply a -c flag,
chances are the function it produces will be slightly more periodic,
but because the functions are modified to fit exactly the number of
output points requested, the periodicity will usually be lost.
