superstats.transition.stochastic.kernel#

Kernel implementations for Gaussian-process transitions.

class superstats.transition.stochastic.kernel.CompositeKernel(left, right, op)[source]#

Bases: Kernel

Elementwise sum or product of two kernels’ covariance matrices.

Not constructed directly in normal use — created by + / * on Kernel instances, e.g. RBFKernel() + LinearKernel().

Parameters:

left, rightKernel: Kernels to combine. Must have disjoint hyperparam_names — combining two kernels of the same type requires giving at least one of them an explicit name.
op{“add”, “mul”}

Parameters:

left (Kernel)
right (Kernel)
op (str)

build(num_steps, **hyperparams)[source]#

Construct the (batch_size, num_steps, num_steps) kernel matrix.

Parameters:

num_stepsint
**hyperparamsnp.ndarray: Must contain every name in self.hyperparam_names, each of shape (batch_size,). Extra keys (from sibling kernels in a composite) are ignored.

Returns:

kernel_matnp.ndarray of shape (batch_size, num_steps, num_steps)

Parameters:

num_steps (int)
hyperparams (ndarray)

Return type:

ndarray

class superstats.transition.stochastic.kernel.Kernel(name=None)[source]#

Bases: ABC

Interface a kernel must satisfy to be used by GaussianProcess.

Subclasses set _local_hyperparam_names (the hyperparameter names they need) and implement build. Use self.local_hyperparams(…) inside build to strip this kernel’s name prefix off the incoming hyperparams dict before passing values to the underlying kernel math.

By default (name=None), hyperparam_names are unprefixed, e.g. RBFKernel() exposes (“length_scale”, “amplitude”) — matching DEFAULT_HYPER_PRIORS directly, same as RandomWalk’s sigma/ delta. Pass name= to prefix them (“trend_length_scale”), which is required when combining two kernels that would otherwise expose the same hyperparameter names.

Kernels combine with + (sum) and * (elementwise product) into a CompositeKernel — both operations preserve positive-semidefiniteness, so any combination is itself a valid kernel.

Parameters:

namestr, optional: Prefix for this kernel’s hyperparameter names. Leave unset for a single kernel, or when combining kernels of different types. Required (and must be unique) when combining two kernels that share hyperparameter names, e.g. RBFKernel(name=”trend”) + RBFKernel(name=”local”).

Attributes:

hyperparam_namestuple of str: Hyperparameter names this kernel expects in build, e.g. (“length_scale”, “amplitude”) when unnamed, or (“trend_length_scale”, “trend_amplitude”) when name=”trend”. These become Transition.hyper_specs entries.

Parameters:

name (str | None)

abstract build(num_steps, **hyperparams)[source]#

Construct the (batch_size, num_steps, num_steps) kernel matrix.

Parameters:

num_stepsint
**hyperparamsnp.ndarray: Must contain every name in self.hyperparam_names, each of shape (batch_size,). Extra keys (from sibling kernels in a composite) are ignored.

Returns:

kernel_matnp.ndarray of shape (batch_size, num_steps, num_steps)

Parameters:

num_steps (int)
hyperparams (ndarray)

Return type:

ndarray

local_hyperparams(**hyperparams)[source]#

Strip this kernel’s name prefix off hyperparams.

Parameters:

**hyperparamsnp.ndarray: Must contain every name in self.hyperparam_names. Extra keys (from sibling kernels in a composite) are ignored.

Returns:

localdict - hyperparams re-keyed by the unprefixed names: in self._local_hyperparam_names

Parameters:

hyperparams (ndarray)

Return type:

Dict[str, ndarray]

class superstats.transition.stochastic.kernel.LinearKernel(name=None)[source]#

Bases: Kernel

Linear kernel. Requires hyperparameter variance.

Parameters:

namestr, optional: Prefix for this kernel’s hyperparameter name. Leave unset for a single linear kernel, or when combining with a kernel of a different type. Required when combining two linear kernels.

Parameters:

name (str | None)

build(num_steps, **hyperparams)[source]#

Construct the (batch_size, num_steps, num_steps) kernel matrix.

Parameters:

num_stepsint
**hyperparamsnp.ndarray: Must contain every name in self.hyperparam_names, each of shape (batch_size,). Extra keys (from sibling kernels in a composite) are ignored.

Returns:

kernel_matnp.ndarray of shape (batch_size, num_steps, num_steps)

Parameters:

num_steps (int)
hyperparams (ndarray)

Return type:

ndarray

class superstats.transition.stochastic.kernel.PeriodicKernel(name=None)[source]#

Bases: Kernel

Periodic kernel. Requires hyperparameters length_scale, period, amplitude.

Models functions that repeat themselves exactly. period sets the distance between repetitions; length_scale controls smoothness of the repeated shape, same interpretation as in RBFKernel.

Parameters:

namestr, optional: Prefix for this kernel’s hyperparameter names. Leave unset for a single periodic kernel, or when combining with a kernel of a different type. Required when combining two periodic kernels.

Parameters:

name (str | None)

build(num_steps, **hyperparams)[source]#

Construct the (batch_size, num_steps, num_steps) kernel matrix.

Parameters:

num_stepsint
**hyperparamsnp.ndarray: Must contain every name in self.hyperparam_names, each of shape (batch_size,). Extra keys (from sibling kernels in a composite) are ignored.

Returns:

kernel_matnp.ndarray of shape (batch_size, num_steps, num_steps)

Parameters:

num_steps (int)
hyperparams (ndarray)

Return type:

ndarray

class superstats.transition.stochastic.kernel.RBFKernel(name=None)[source]#

Bases: Kernel

RBF kernel. Requires hyperparameters length_scale, amplitude.

Parameters:

namestr, optional: Prefix for this kernel’s hyperparameter names. Leave unset for a single RBF kernel, or when combining with a kernel of a different type. Required when combining two RBF kernels, e.g. RBFKernel(name=”short”) + RBFKernel(name=”long”).

Parameters:

name (str | None)

build(num_steps, **hyperparams)[source]#

Construct the (batch_size, num_steps, num_steps) kernel matrix.

Parameters:

num_stepsint
**hyperparamsnp.ndarray: Must contain every name in self.hyperparam_names, each of shape (batch_size,). Extra keys (from sibling kernels in a composite) are ignored.

Returns:

kernel_matnp.ndarray of shape (batch_size, num_steps, num_steps)

Parameters:

num_steps (int)
hyperparams (ndarray)

Return type:

ndarray

superstats.transition.stochastic.kernel.build_abs_dist_mat(num_steps)[source]#

Absolute pairwise distances for num_steps evenly spaced points on [0, 1].

Parameters:

num_stepsint: Number of points in the 1D grid.

Returns:

abs_distnp.ndarray of shape (num_steps, num_steps): Absolute distance between point i and point j at [i, j].

Parameters:

num_steps (int)

Return type:

ndarray

superstats.transition.stochastic.kernel.build_sq_dist_mat(num_steps)[source]#

Squared pairwise distances for num_steps evenly spaced points on [0, 1].

Parameters:

num_stepsint: Number of points in the 1D grid.

Returns:

sq_distnp.ndarray of shape (num_steps, num_steps): Squared distance between point i and point j at [i, j].

Parameters:

num_steps (int)

Return type:

ndarray

superstats.transition.stochastic.kernel.get_linear_kernel(num_steps, variance)[source]#

Batched linear kernel construction.

Parameters:

num_stepsint: Number of points in the 1D grid.
variancenp.ndarray of shape (batch_size,): Scale of the kernel per trajectory.

Returns:

kernel_matnp.ndarray of shape (batch_size, num_steps, num_steps)

Parameters:

num_steps (int)
variance (ndarray)

Return type:

ndarray

superstats.transition.stochastic.kernel.get_periodic_kernel(num_steps, length_scale, period, amplitude)[source]#

Batched periodic kernel construction.

k(x, x_prime) = amplitude^2 * exp(-2 * sin^2(pi * |x - x_prime| / period) / length_scale^2)

Parameters:

num_stepsint: Number of points in the 1D grid.
length_scalenp.ndarray of shape (batch_size,): Smoothness of the repeated shape; smaller values mean a more wiggly repeating pattern, larger values a smoother one.
periodnp.ndarray of shape (batch_size,): Distance between repetitions, on the [0, 1] grid.
amplitudenp.ndarray of shape (batch_size,): Kernel variance / overall scale per trajectory.

Returns:

kernel_matnp.ndarray of shape (batch_size, num_steps, num_steps)

Parameters:

num_steps (int)
length_scale (ndarray)
period (ndarray)
amplitude (ndarray)

Return type:

ndarray

superstats.transition.stochastic.kernel.get_rbf_kernel(num_steps, length_scale, amplitude)[source]#

Batched RBF kernel construction.

Parameters:

num_stepsint: Number of points in the 1D grid.
length_scalenp.ndarray of shape (batch_size,): Kernel width per trajectory; larger values mean smoother, slower-varying draws.
amplitudenp.ndarray of shape (batch_size,): Kernel variance / overall scale per trajectory.

Returns:

kernel_matnp.ndarray of shape (batch_size, num_steps, num_steps)

Parameters:

num_steps (int)
length_scale (ndarray)
amplitude (ndarray)

Return type:

ndarray

superstats.transition.stochastic.kernel.resolve_kernel(kernel)[source]#

Resolve a kernel name or instance to a Kernel.

Parameters:

kernelstr or Kernel: Either a registered name (currently “rbf”, “linear”, or “periodic”) or a Kernel instance, including composites built via +/*.

Returns:

kernelKernel

Parameters:

kernel (str | Kernel)

Return type:

Kernel

Modules

`kernel`	Kernel base classes and composition helpers.
`linear`	Linear covariance kernels.
`periodic`	Periodic covariance kernels.
`rbf`	Radial basis function covariance kernels.
`registry`	Kernel name registry and resolution.