Metadata-Version: 2.4
Name: monspline
Version: 0.1.3
Summary: Python wrapper for C++ numerical algorithms using CFFI for monotone splines
Home-page: 
Author: Gleb Beliakov, Rithik Nair
Author-email: gleb.beliakov@deakin.edu.au
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Requires-Dist: numpy
Requires-Dist: cffi
Dynamic: author-email
Dynamic: license-file

monspline

=========



Python package for efficient spline interpolation using C++ (via CFFI),

with a strong focus on **shape preservation**.



--------------



Overview

--------



This project implements and evaluates spline interpolation methods,

including:



- Cubic spline interpolation

- Monotone-preserving spline interpolation

- Taut exponential spline interpolation

- Tensor-product splines (multivariate, monotone)



--------------



Motivation

----------



Spline interpolation is widely used in numerical analysis and machine

learning. However:



- Cubic splines may introduce **oscillations**

- Monotone splines improve **stability**

- Real-world datasets often contain **noise and discontinuities**



--------------

[Methods and examples](https://gleb.cgps.ch/Assets/Documents/Shape_preserving_approximation_using_least_squares_splines.pdf, https://gleb.cgps.ch/Assets/Documents/Monotone_approximation_of_aggregation_operators_using_least_squares_splines.pdf)



Architecture

------------



Python - CFFI - C wrapper - C++ classes



- Python: User API and plotting

- CFFI: Interface layer

- C wrapper: Object management using handles

- C++: Core spline algorithms



--------------



Features

--------



Cubic Spline

~~~~~~~~~~~~



- Smooth interpolation (C^2 continuity)

- Efficient C++ implementation



Monotone Spline

~~~~~~~~~~~~~~~



- Preserves monotonicity

- Prevents overshooting

- Better for noisy / real-world data

- Taut spline remove unnecessary inflection points



Tensor (Multivariate) Spline

~~~~~~~~~~~~~~~~~~~~~~~~~~~~



- Supports higher-dimensional approximation

- Used for 3D surface modelling

- Support monotonicity preservation



--------------






Build

-----



.. code:: bash



   python build.py

    Run Tests

   python tests/testcs.py

   python tests/test_tensor_spline.py



Observation: Cubic splines introduce oscillations, while monotone

splines preserve structure.



Observation: Cubic splines overshoot near discontinuities. Monotone

splines provide stable approximation.



3D Tensor Spline



Observation: Tensor splines approximate smooth surfaces effectively in

2D.



Key Insights

------------



Cubic splines - smooth but unstable near discontinuities



Monotone splines - stable and shape-preserving



Taut splines - remove extraneous inflection points, no monotonicity

assumed



Tensor splines - extend interpolation to higher dimensions



References

----------



C. de Boor, A Practical Guide to Splines



Fritsch & Carlson, Monotone Piecewise Cubic Interpolation



G.Beliakov, (2000) Shape preserving approximation using least squares

splines. Analysis in theory and applications, 16(4), 80-98



G.Beliakov, (2002) Monotone approximation of aggregation operators using

least squares splines. International journal of uncertainty, fuzziness,

and knowledge-based systems, 10(6), 659-676.



Installation

------------



To install type:



.. code:: python



   $ pip install monspline



Usage of monspline

------------------



.. code:: python



   from monspline import TensorSpline

   from monspline import CubicSpline

    generate/read data tables

   x = [0,1,2,3,4,5]

   y = [0,0.1,0.2,0.3,0.4,0.5]

   s = CubicSpline(x, y, type=1)

   y=s.value(0.5)

   s1= = TensorSpline(kind=0, dim=2, knots=knots, data=data, exactdata=exactdata) 

   y = s1.value([0.5, 0.5])



Usage of CubicSpline(x,y type, tau=0)

-------------------------------------



Construction of a cubic/monotone/taut univariate spline



Parameters

~~~~~~~~~~



Input parameters:

^^^^^^^^^^^^^^^^^



x[]: NumPy array of size n, float



w[]: NumPy array of size n, float



type: int, can be 1 (cubic),2 (taut exponential, required tau>0.01) , 3

monotone increasing



tau: float, tension parameter in taut splines to straighten inflection

points



Output parameters

^^^^^^^^^^^^^^^^^



s: spline object



Usage of value(x)

-----------------



Calculation of a cubic/monotone/taut spline value



.. _parameters-1:



Parameters

~~~~~~~~~~



.. _input-parameters-1:



Input parameters:

^^^^^^^^^^^^^^^^^



t: float, the query point



Output

^^^^^^



y: float, spline value at t



Usage of TensorSpline(kind, dim, knots, data, exactdata)

--------------------------------------------------------



Construction of a tensor product spline of dimension dim



.. _parameters-2:



Parameters

~~~~~~~~~~



.. _input-parameters-2:



Input parameters:

^^^^^^^^^^^^^^^^^



kind: int, type of spline, see below



dim: int, dimension



knots: array of size(dim,knotN), float, contains spline knots for each

variable



data[]: NumPy array of size (n,dim+1), float, contains n data (x and y)

to approximate



exactdata[]: NumPy array of size (m,dim+1), float, contains m data (x

and y) to interpolate (exact fit)



.. _output-parameters-1:



Output parameters

^^^^^^^^^^^^^^^^^



s: spline object



Interpretation of kind

^^^^^^^^^^^^^^^^^^^^^^



For each variable: 0: dim-dimensional tensor product spline of order 2

(linear), no constraints



1: monotone increasing



2: monotone decreasing



When dim >1, concatenate the values for each variable starting from the

right.



Example: dim=2



12: means increasing in the second variable (1) and decreasing in the

first variable (2)



dim=3



110: increasing in the third and second variable unrestricted in the

first variable



When dim==1:



kind=11,12,... means spline of order 3,4,... (order 4 means cubic spline),

i.e., kind-8 = spline order otherwise order is forced to be 2



.. _usage-of-valuex-1:



Usage of value(x)

-----------------



Calculation of tensor spline value at x



.. _parameters-3:



Parameters

~~~~~~~~~~



.. _input-parameters-3:



Input parameters:

^^^^^^^^^^^^^^^^^



x: float, when dim==1 and array of size dim otherwise, the query point



.. _output-1:



Output

^^^^^^



y: float, spline value at x



Usage of value_der(x,var)

-------------------------



Calculation of tensor spline derivative value at x



.. _parameters-4:



Parameters

~~~~~~~~~~



.. _input-parameters-4:



Input parameters:

^^^^^^^^^^^^^^^^^



x: float, when dim==1 and array of size dim otherwise, the query point



var: int, with respect to which variable, starting from 0 to dim-1



.. _output-2:



Output

^^^^^^



y: float, spline partial derivative value at x


