bsplines

README

B-Spline function support for Go

Example With Plots

This library provides 2 implementations of B-Spline using the same API: one that evaluates fully in Go (CPU, slower) and one using GoMLX for ML and/or accelerators.

Highlights:

• Support for zero, constant or linear extrapolation beyond the region defined by the knots.
• Derivative B-spline.
• GoMLX "vector" version in github.com/gomlx/gomlx/ml/layers/kan
  • Building block to build KAN: Kolmogorov–Arnold Networks
  • Batch evaluation.
  • Multiple control points -- for various different B-splines to be applied to the same input points. They share the same basis function calculation for improved efficiency.
• Plotting using GoNB Jupyter Notebook.
• See demo notebook with some plot samples.

Changes Log

v0.2.0

• Moved GoMLX code to github.com/gomlx/gomlx/ml/layers/kan, to avoid circular dependency across repositories.

Documentation

Overview

Package bsplines provides a CPU implementation of [B-spline](https://en.wikipedia.org/wiki/B-spline).

It also provides configuration that can be used by github.com/gomlx/bsplines/gomlx package to calculate B-splines efficiently using GoMLX.

For plotting, checkout the sub-package github.com/gomlx/bsplines/plotly that will plot the B-spline, its basis functions and the same curve using GoMLX using the Plotly library and GoNB notebook. It's provided with the demo notebook [bsplines.ipynb].

Index

• type BSpline
  • func New(degree int, knots []float64) *BSpline
  • func NewRegular(degree, numControlPoints int) *BSpline
  • func (b *BSpline) BasisFunction(controlPointIdx, degree int, x float64) float64
  • func (b *BSpline) ControlPoints() []float64
  • func (b *BSpline) ControlPointsX() []float64
  • func (b *BSpline) Degree() int
  • func (b *BSpline) Derivative() *BSpline
  • func (b *BSpline) Evaluate(x float64) float64
  • func (b *BSpline) ExpandedKnots() []float64
  • func (b *BSpline) Extrapolation() ExtrapolationType
  • func (b *BSpline) Knots() []float64
  • func (b *BSpline) LinearExtrapolationKnotRatios() (low, high float64)
  • func (b *BSpline) NumControlPoints() int
  • func (b *BSpline) WithControlPoints(controlPoints []float64) *BSpline
  • func (b *BSpline) WithExtrapolation(e ExtrapolationType) *BSpline
• type ExtrapolationType
  • func (i ExtrapolationType) String() string

Types

type BSpline

type BSpline struct {
	// contains filtered or unexported fields
}

BSpline contains the basic configuration of a B-spline. Notice the control points are not part of the configuration: they are given during evaluation.

It can be used to evaluate points, or with the package github.com/gomlx/bsplines/plotly to plot a 1D B-spline or, with the package github.com/gomlx/bsplines/gomlx to create an evaluator for batch of inputs.

func New

func New(degree int, knots []float64) *BSpline

New create a new B-spline with the given [degree] (`order == degree+1`). To use it for evaluation, the control points must be given with [WithControlPoints].

The [knots] must be sorted and not be repeated. Internally, [degree] extra values are inserted on the start and end of the knots vector, to clamp the endings.

func NewRegular

func NewRegular(degree, numControlPoints int) *BSpline

NewRegular creates a new B-spline that is defined with enough knots for [numControlPoints]. The knots are created evenly spaced from 0.0 to 1.0.

[numControlPoints] must be at least `degree + 1`.

func (*BSpline) BasisFunction

func (b *BSpline) BasisFunction(controlPointIdx, degree int, x float64) float64

BasisFunction calculates the B-spline basis function arbitrary degree at parameter x. This usually is not used directly, but can be interesting to plot to understand how it is calculated.

func (*BSpline) ControlPoints

func (b *BSpline) ControlPoints() []float64

ControlPoints returns the control points. at creation time it may be nil. To change them, use WithControlPoints instead.

func (*BSpline) ControlPointsX

func (b *BSpline) ControlPointsX() []float64

ControlPointsX calculates the x values for each one of the control points. These values are not something used in the evaluation, but are handy to plot the control points, since they are at the center of its area of influence.

func (*BSpline) Degree

func (b *BSpline) Degree() int

Degree of the B-spline.

func (*BSpline) Derivative

func (b *BSpline) Derivative() *BSpline

Derivative creates the derivative BSpline of the given BSpline. Notice the control points must have been set with WithControlPoints.

The returned BSpline have the same knots, and the degree will be one less than the original. The control points are updated.

func (*BSpline) Evaluate

func (b *BSpline) Evaluate(x float64) float64

Evaluate 1D B-spline on the value of x (some text call this the parameter value, also referred as `t`). This function is the simplest version, but not very fast, and run on CPU.

One must set the control points using WithControlPoints before calling this function.

func (*BSpline) ExpandedKnots

func (b *BSpline) ExpandedKnots() []float64

ExpandedKnots return the knots with the clamps (degree repeated values from the beginning and end of the vector).

func (*BSpline) Extrapolation

func (b *BSpline) Extrapolation() ExtrapolationType

Extrapolation returns the extrapolation currently configured.

func (*BSpline) Knots

func (b *BSpline) Knots() []float64

Knots of the B-spline. Values must not be changed -- if one needs to change the knots, create a new B-Spline.

func (*BSpline) LinearExtrapolationKnotRatios

func (b *BSpline) LinearExtrapolationKnotRatios() (low, high float64)

LinearExtrapolationKnotRatios is used internally for doing linear extrapolation. Exposed only so it can be used by the bsplines/gomlx package.

func (*BSpline) NumControlPoints

func (b *BSpline) NumControlPoints() int

NumControlPoints returns the expected number of control points for the current knots.

func (*BSpline) WithControlPoints

func (b *BSpline) WithControlPoints(controlPoints []float64) *BSpline

WithControlPoints associate the given control points to this B-spline. There must be exactly `len(knots)+degree-1` control points.

It must be set before evaluation. It can also be switched each time before an evaluation, it's a very cheap operation. Notice the knots themselves cannot change -- create another B-spline if different knots are needed.

It returns itself so configuration calls can be cascaded.

func (*BSpline) WithExtrapolation

func (b *BSpline) WithExtrapolation(e ExtrapolationType) *BSpline

WithExtrapolation defines how the evaluation should extrapolate for values before the first knot or after the last knot.

The default value is ExtrapolateConstant.

It returns itself so configuration calls can be cascaded.

type ExtrapolationType

type ExtrapolationType int

ExtrapolationType defines how a B-spline should behave outside the knots (for x < knots[0] or x > knots[-1]).

const (
	// ExtrapolateZero configures a B-spline to take value of 0 outside the knots.
	ExtrapolateZero ExtrapolationType = iota

	// ExtrapolateConstant configures a B-spline to take the constant value of the first/last control point outside the knots.
	ExtrapolateConstant

	// ExtrapolateLinear configures a B-spline to extrapolate linearly outside the first/last control point outside the knots.
	ExtrapolateLinear
)

func (ExtrapolationType) String

func (i ExtrapolationType) String() string