add maths documentation

README.md

@@ -47,6 +47,8 @@ This is identical to (must be called in that order):
     s.make_monotonic();
 ```
 
+![cubic C2 spline](https://kluge.in-chemnitz.de/opensource/spline/cubic_c2_spline_git.png)
+
 ### Spline types
 Splines are piecewise polynomial functions to interpolate points
 (x<sub>i</sub>, y<sub>i</sub>). In particular, cubic splines can

doc/Makefile

@@ -0,0 +1,19 @@
+all:		spline.pdf
+
+spline.pdf:	spline.tex interpolate_avg.pdf positive_criteria.pdf spline.bbl spline.blg
+		pdflatex spline.tex
+
+interpolate_avg.pdf:	interpolate_avg.gp
+		gnuplot interpolate_avg.gp
+
+positive_criteria.pdf:	positive_criteria.gp
+		gnuplot positive_criteria.gp
+
+spline.bbl:	literature.bib spline.tex
+		pdflatex spline; bibtex spline; pdflatex spline
+
+spline.blg:	literature.bib spline.tex
+		pdflatex spline; bibtex spline; pdflatex spline
+
+clean:
+		rm -f *.pdf *.aux *.dvi *.log *.ps *.bbl *.blg

doc/README.md

@@ -0,0 +1,12 @@
+## Spline documentation
+This contains the description of the mathematical background
+and is aimed at anyone who wants to understand the source code.
+
+### Prerequisites
+* [LaTex](https://www.latex-project.org/)
+* [Gnuplot](http://www.gnuplot.info/)
+
+### Building
+```
+$ make 		# builds spline.pdf
+```

doc/interpolate_avg.gp

@@ -0,0 +1,60 @@
+set term pdfcairo color solid size  12cm,8cm
+set output "interpolate_avg.pdf"
+
+# input points to interpolate (0,y1), (h,y2) with average avg
+h=1.0
+avg=1.0
+y1=4.0
+y2=2.0
+
+# calculate quadratic function: f(x) = a + b*x + c*x^2
+# which has the average avg and goes through both points
+a=y1
+b=2.0/h*(-2.0*y1-y2+3.0*avg)
+c=3.0/(h*h)*(y1+y2-2.0*avg)
+f(x) = a + b*x + c*x*x
+
+# make positive
+R=sqrt( (y1/avg)**2 + (y2/avg)**2 )
+if(R>3) {
+    z1=y1/R*3.0
+    z2=y2/R*3.0
+} else {
+    z1=y1
+    z2=y2
+}
+aa=z1
+bb=2.0/h*(-2.0*z1-z2+3.0*avg)
+cc=3.0/(h*h)*(z1+z2-2.0*avg)
+g(x) = aa + bb*x + cc*x*x
+
+#set size ratio -1
+set samples 300
+set colors classic
+set xzeroaxis
+set yzeroaxis
+set xrange [-0.05*h:1.05*h]
+
+set arrow from h, graph 0 to h,graph 1 nohead lt 0
+
+set arrow from 0,y1 to 0,z1 head lt 2 lw 1 
+set arrow from h,y2 to h,z2 head lt 2 lw 1
+set label " =h" at h,screen 0.05
+set label "  y_1" at 0,y1
+set label "  y_2" at h,y2
+
+
+plot	f(x) notitle with l lt 1 lw 1,\
+	g(x) notitle with l lt 2 lw 1 dt 2,\
+	avg  notitle with l lt 0 lw 1,\
+	"-" using 1:(f($1)) notitle with p pt 7 lt 1,\
+	"-" using 1:(g($1)) notitle with p pt 7 lt 2
+0.0
+1.0 
+e
+0.0
+1.0 
+e
+
+
+pause -1

doc/literature.bib

@@ -0,0 +1,11 @@
+@STRING{SIAJN   = {SIAM J. Numer.  Anal.}}
+
+@article{Fri:1980:monotone_spline,
+  title={Monotone piecewise cubic interpolation},
+  author={Fritsch, F.N. and Carlson, R.E.},
+  journal=SIAJN,
+  volume={17},
+  number={2},
+  pages={238--246},
+  year={1980}
+}

doc/positive_criteria.gp

@@ -0,0 +1,27 @@
+set term pdfcairo color solid size  8cm,8cm
+set output "positive_criteria.pdf"
+
+
+# implicit equation: x^2+y^2+xy-6(x+y)+9=0
+f(x) = -0.5*(x-6.0) + sqrt( (-0.75*x+3.0)*x )
+g(x) = -0.5*(x-6.0) - sqrt( (-0.75*x+3.0)*x )
+
+# sufficient criteria: x^2+y^2=9
+h(x) = sqrt(9.0-x*x)
+
+
+set size ratio -1
+set samples 500
+set colors classic
+set xlabel "y_1"
+set ylabel "y_2"
+set xrange [0:4]
+
+set arrow from 0,0 to 0,3 nohead lt 1 lw 2
+
+plot	f(x) title "exact" with l lt 1 lw 2,\
+	g(x)*(x>=3) notitle with l lt 1 lw 2,\
+	h(x)*(x<=3) title "sufficient" with l lt 2 dt 2
+
+
+pause -1