Generic kernel classes

All kernels in lsqfitgp are subclasses of CrossKernel. The user should almost exclusively deal with its subclass Kernel, as CrossKernel objects are produced behind the scenes by GP.

The generic classes can be used standalone. To ease subclassing, use the decorators.

Index

CrossKernel, Kernel, CrossStationaryKernel, StationaryKernel, CrossIsotropicKernel, IsotropicKernel

Classes

class lsqfitgp.CrossKernel(core, *, scale=None, loc=None, derivable=None, maxdim=None, dim=None, forcekron=False, batchbytes=None, **kw)

Base class to represent kernels, i.e., covariance functions.

A kernel is a two-argument function that computes the covariance between two functions at some points according to some probability distribution:

\[\mathrm{kernel}(x, y) = \mathrm{Cov}[f(x), g(y)].\]

CrossKernel objects are callable, the signature is obj(x, y), and they can be summed and multiplied between them and with scalars. They are immutable; all operations return new objects.

Parameters:

corecallable

A function with signature core(x, y), where x and y are two broadcastable numpy arrays, which computes the value of the kernel.

scale, loc, derivable, maxdim, dim

If specified, these arguments are passed as arguments to the correspondingly named operators, in the order listed here. See linop. Briefly: the kernel selects only fields dim in the input, checks the dimensionality against maxdim, checks there are not too many derivatives taken on the arguments, then transforms as (x - loc) / scale. If any argument is callable, it is passed **kw and must return the actual argument. If an argument is a tuple, it is interpreted as a pair of arguments.

forcekronbool, default False

If True, apply .transf('forcekron') to the kernel, before the operations above. Available only for Kernel.

batchbytesnumber, optional

If specified, apply .batch(batchbytes) to the kernel.

**kw

Additional keyword arguments are passed to core.

See also

Kernel

Notes

The predefined class hierarchy and the class logic of the transformations assume that each kernel class corresponds to a subalgebra, i.e., addition and multiplication preserve the class.

Methods

batch(maxnbytes)	Return a batched version of the kernel.
transf(transfname, *args, **kw)	Return a transformed kernel.
linop(transfname, *args)	Transform kernels to represent the application of a linear operator.
algop(transfname, *operands, **kw)	Return a nonnegative algebraic transformation of the input kernels.
register_transf(func[, transfname, doc, kind])	Register a transformation for use with transf.
register_linop(op[, transfname, doc, argparser])	Register a transformation for use with linop.
register_corelinop(corefunc[, transfname, ...])	Register a linear operator with a function that acts only on the core.
register_xtransf(xfunc[, transfname, doc])	Register a linear operator that acts only on the input.
register_algop(op[, transfname, doc])	Register a transformation for use with algop.
transf_help(transfname)	Return the documentation of a transformation.
has_transf(transfname)	Check if a transformation is registered.

class Transf(tcls, kind, func, doc)

Create new instance of Transf(tcls, kind, func, doc)

doc

Alias for field number 3

func

Alias for field number 2

kind

Alias for field number 1

tcls

Alias for field number 0

algop(transfname, *operands, **kw)

Return a nonnegative algebraic transformation of the input kernels.

\[\begin{split}\mathrm{newkernel}(x, y) &= f(\mathrm{kernel}_1(x, y), \mathrm{kernel}_2(x, y), \ldots), \\ f(z_1, z_2, \ldots) &= \sum_{k_1,k_2,\ldots=0}^\infty a_{k_1 k_2 \ldots} z_1^{k_1} z_2^{k_2} \ldots, \quad a_* \ge 0.\end{split}\]

Parameters:

transfnamehashable

A name identifying the transformation.

*operandsCrossKernel, scalar

Arguments to the transformation in addition to self.

**kw

Additional arguments to the transformation, not considered as operands.

Returns:

newkernelCrossKernel or NotImplemented

The transformed kernel, or NotImplemented if the operation is not supported.

See also

transf

Notes

The class of newkernel is the least common superclass of: the “natural” output of the operation, the class defining the transformation, and the classes of the operands.

For class determination, scalars in the input count as IsotropicKernel if nonnegative or traced by jax, else CrossIsotropicKernel.

batch(maxnbytes)

Return a batched version of the kernel.

The batched kernel processes its inputs in chunks to try to limit memory usage.

Parameters:

maxnbytesnumber

The maximum number of input bytes per chunk, counted after broadcasting the input shapes. Actual broadcasting may not occur if not induced by the operations in the kernel.

Returns:

batched_kernelCrossKernel

The same kernel but with batched computations.

classmethod has_transf(transfname)

Check if a transformation is registered.

Parameters:

transfnamehashable

The transformation name.

Returns:

has_transfbool

Whether the transformation is registered.

See also

transf

classmethod inherit_all_algops(intermediates=False)

Inherit all algebraic operations from superclasses.

This makes sense if the class represents a subalgebra, i.e., it should be preserved by addition and multiplication.

Parameters:

intermediatesbool, default False

If True, make all superclasses up to the one definining the transformation inherit it too.

Raises:

KeyError

An algebraic operation is already registered for one of the target classes.

See also

transf

classmethod inherit_transf(transfname, *, intermediates=False)

Inherit a transformation from a superclass.

Parameters:

transfnamehashable

The name of the transformation.

intermediatesbool, default False

If True, make all superclasses up to the one definining the transformation inherit it too.

Raises:

KeyError

The transformation was not found in any superclass, or the transformation is already registered on any of the target classes.

See also

transf

linop(transfname, *args)

Transform kernels to represent the application of a linear operator.

\[\begin{split}\text{kernel}_1(x, y) &= \mathrm{Cov}[f_1(x), g_1(y)], \\ \text{kernel}_2(x, y) &= \mathrm{Cov}[f_2(x), g_2(y)], \\ &\ldots \\ \text{newkernel}(x, y) &= \mathrm{Cov}[T_f(f_1, f_2, \ldots)(x), T_g(g_1, g_2, \ldots)(y)]\end{split}\]

Parameters:

transfnamehashable

The name of the transformation.

*args

A sequence of CrossKernel instances, representing the operands, followed by one or two non-kernel arguments, indicating how to act on each side of the kernels. If both arguments represent the identity, this is a no-op. If there is only one argument, it is intended that the two arguments are equal. None always represents the identity.

Returns:

newkernelCrossKernel

The transformed kernel.

Raises:

ValueError

The transformation exists but was not defined by register_linop.

See also

transf

Notes

The linear operator is defined on the function the kernel represents the distribution of, not in full generality on the kernel itself. When multiple kernels are involved, their distributions may be considered independent or not, depending on the specific operation.

If the result is a subclass of the class defining the transformation, the result is casted to the latter. Then, if the result and all the operands are instances of Kernel, but the two operator arguments differ, the result is casted to its first non-Kernel superclass.

classmethod list_transf(superclasses=True)

List all the available transformations.

Parameters:

superclassesbool, default True

Include transformations defined in superclasses.

Returns:

transfs: dict of Transf

The dictionary keys are the transformation names, the values are named tuples (tcls, kind, impl, doc) where tcls is the class defining the transformation, kind is the kind of transformation, impl is the implementation with signature impl(tcls, self, *args, **kw), doc is the docstring.

classmethod register_algop(op, transfname=None, doc=None)

Register a transformation for use with algop.

Parameters:

funccallable

A function func(*kernels, **kw) -> CrossKernel | NotImplemented that returns the new kernel. kernels may be scalars but for the first argument.

transfname, doc

See register_transf.

Returns:

funccallable

A transformation in the format of register_transf.

See also

transf

classmethod register_corelinop(corefunc, transfname=None, doc=None, argparser=None)

Register a linear operator with a function that acts only on the core.

Parameters:

corefunccallable

A function corefunc(core, arg1, arg2, *cores) -> newcore, where core is the function that implements the kernel passed at initialization, and cores for other operands.

transfname, doc, argparser

See register_linop.

Returns:

funccallable

A function in the format of register_transf that wraps corefunc.

See also

transf

classmethod register_linop(op, transfname=None, doc=None, argparser=None)

Register a transformation for use with linop.

Parameters:

opcallable

A method op(self, arg1, arg2, *operands) -> CrossKernel that returns the new kernel, where arg1 and arg2 represent the operators acting on each side of the kernels, and operands are the other kernels beyond self.

transfname, docoptional

See register_transf.

argparsercallable, optional

A function applied to arg1 and arg2. Not called if the argument is None. It should map the identity to None.

Returns:

funccallable

A function in the format required by register_transf, implementing the additional argument parsing and output class logic of linop.

See also

transf

Notes

The function op is called only if arg1 or arg2 is not None after potential conversion with argparser.

classmethod register_transf(func, transfname=None, doc=None, kind=None)

Register a transformation for use with transf.

The transformation will be accessible to subclasses.

Parameters:

funccallable

A function func(tcls, self, *args, **kw) -> object implementing the transformation, where tcls is the class that defines the transformation.

transfnamehashable, optional.

The transfname parameter to transf this transformation will be accessible under. If not specified, use the name of func.

docstr, optional

The documentation of the transformation for transf_help. If not specified, use the docstring of func.

kindobject, optional

An arbitrary marker.

Returns:

funccallable

The func argument as is.

Raises:

KeyError

The name is already in use for another transformation in the same class.

See also

transf

classmethod register_ufuncalgop(ufunc, transfname=None, doc=None)

Register an algebraic operation with a function that acts only on the kernel value.

Parameters:

corefunccallable

A function ufunc(*values, **kw) -> value, where values are the values yielded by the operands.

transfname, doc

See register_transf.

Returns:

funccallable

A function in the format of register_transf that wraps corefunc.

See also

transf

classmethod register_xtransf(xfunc, transfname=None, doc=None)

Register a linear operator that acts only on the input.

Parameters:

xfunccallable

A function xfunc(arg) -> (lambda x: newx) that takes in a linop argument and produces a function to transform the input. Not called if arg is None. To indicate the identity, return None.

transfname, doc

See register_linop. argparser is not provided because its functionality can be included in xfunc.

Returns:

funccallable

A function in the format of register_transf that wraps xfunc.

See also

transf

transf(transfname, *args, **kw)

Return a transformed kernel.

Parameters:

transfnamehashable

A name identifying the transformation.

*args, **kw

Arguments to the transformation.

Returns:

newkernelobject

The output of the transformation.

Raises:

KeyError

The transformation is not defined in this class or any superclass.

See also

linop, algop, transf_help, has_transf, register_transf, register_linop, register_corelinop, register_xtransf, register_algop, register_ufuncalgop

classmethod transf_help(transfname)

Return the documentation of a transformation.

Parameters:

transfnamehashable

The name of the transformation.

Returns:

docstr

The documentation of the transformation.

See also

transf

---

class lsqfitgp.Kernel(core, *, scale=None, loc=None, derivable=None, maxdim=None, dim=None, forcekron=False, batchbytes=None, **kw)

Subclass of CrossKernel to represent the kernel of a single function:

\[\mathrm{kernel}(x, y) = \mathrm{Cov}[f(x), f(y)].\]

---

class lsqfitgp.CrossStationaryKernel(core, *, input='signed', **kw)

Subclass of CrossKernel for stationary kernels.

A stationary kernel depends only on the difference, dimension by dimension, between its two arguments.

Parameters:

corecallable

A function taking one positional argument delta = x - y and optional keyword arguments.

input{‘signed’, ‘posabs’, ‘abs’}, default ‘signed’

If 'signed', kernel is passed the bare difference. If 'posabs', kernel is passed the absolute value of the difference, and the difference of equal points is a small number instead of zero. If 'abs', the absolute value.

**kw

Additional keyword arguments are passed to the CrossKernel constructor.

---

class lsqfitgp.StationaryKernel(core, *, input='signed', **kw)

---

class lsqfitgp.CrossIsotropicKernel(core, *, input='squared', **kw)

Subclass of CrossStationaryKernel for isotropic kernels.

An isotropic kernel depends only on the Euclidean distance between its two arguments.

Parameters:

corecallable

A function taking one argument r2 which is the squared distance between x and y, plus optionally keyword arguments.

input{‘squared’, ‘abs’, ‘posabs’, ‘raw’}, default ‘squared’

If 'squared', core is passed the squared distance. If 'abs', it is passed the distance (not squared). If 'posabs', it is passed the distance, and the distance of equal points is a small number instead of zero. If 'raw', core is passed both points separately like non-stationary kernels.

**kw

Additional keyword arguments are passed to the CrossKernel constructor.

Notes

The input='posabs' option will cause problems with second derivatives in more than one dimension.

---

class lsqfitgp.IsotropicKernel(core, *, input='squared', **kw)