kernels

import "github.com/umbralcalc/stochadex/pkg/kernels"

Package kernels provides integration kernels for time-weighted aggregation and state-distance weighting in stochadex simulations. These kernels define how historical data points are weighted when computing aggregated statistics over time or when measuring similarity between states.

Key Features:

Time-based weighting kernels (exponential, periodic, constant)
State-distance kernels (Gaussian, instantaneous)
Custom kernel implementations for specialized weighting schemes
Integration with aggregation functions for rolling statistics

Mathematical Background: Kernels define weighting functions K(t, s) that determine how much influence a data point at time s has on the aggregated value at time t. Common patterns:

Exponential kernels: K(t, s) = exp(-λ(t-s)) for time decay
Gaussian kernels: K(x, y) = exp(-||x-y||²/2σ²) for state similarity
Periodic kernels: K(t, s) = cos(2π(t-s)/T) for cyclical patterns

Usage Patterns:

Weight historical data for rolling window statistics
Define similarity measures between simulation states
Implement custom aggregation schemes with domain-specific weighting
Create time-decay functions for forgetting old information

type BinnedIntegrationKernel

BinnedIntegrationKernel outputs piecewise-constant weights in time.

Usage hints:

Provide “bin_values” and “bin_stepsize”; index is floor((t_now - t_past)/stepsize).

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

func (*BinnedIntegrationKernel) Configure

func (b *BinnedIntegrationKernel) Configure(partitionIndex int, settings *simulator.Settings)

func (*BinnedIntegrationKernel) Evaluate

func (b *BinnedIntegrationKernel) Evaluate(currentState []float64, pastState []float64, currentTime float64, pastTime float64) float64

func (*BinnedIntegrationKernel) SetParams

func (b *BinnedIntegrationKernel) SetParams(params *simulator.Params)

type ConstantIntegrationKernel

ConstantIntegrationKernel returns 1.0 for every sample.

Usage hints:

Use to compute simple (unweighted) sums or means.

type ConstantIntegrationKernel struct{}

func (*ConstantIntegrationKernel) Configure

func (c *ConstantIntegrationKernel) Configure(partitionIndex int, settings *simulator.Settings)

func (*ConstantIntegrationKernel) Evaluate

func (c *ConstantIntegrationKernel) Evaluate(currentState []float64, pastState []float64, currentTime float64, pastTime float64) float64

func (*ConstantIntegrationKernel) SetParams

func (c *ConstantIntegrationKernel) SetParams(params *simulator.Params)

type ExponentialIntegrationKernel

ExponentialIntegrationKernel applies exponential decay over time.

Usage hints:

Provide “exponential_weighting_timescale”; weight = exp((t_past - t_now)/tau).
Suitable for recency-weighted means.

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

func (*ExponentialIntegrationKernel) Configure

func (e *ExponentialIntegrationKernel) Configure(partitionIndex int, settings *simulator.Settings)

func (*ExponentialIntegrationKernel) Evaluate

func (e *ExponentialIntegrationKernel) Evaluate(currentState []float64, pastState []float64, currentTime float64, pastTime float64) float64

func (*ExponentialIntegrationKernel) SetParams

func (e *ExponentialIntegrationKernel) SetParams(params *simulator.Params)

type GaussianStateIntegrationKernel

GaussianStateIntegrationKernel implements a Gaussian state-distance kernel for weighting historical samples based on their distance from the current state.

This kernel computes weights using a multivariate Gaussian distribution, where the weight decreases exponentially with the Mahalanobis distance between the current and historical states. It’s particularly useful for state-space aggregation and similarity-based weighting.

Mathematical Background: The Gaussian kernel computes weights using the multivariate Gaussian density:

w(x_current, x_past) = exp(-0.5 * (x_current - x_past)^T * Σ^{-1} * (x_current - x_past)) / sqrt(det(Σ))

where Σ is the covariance matrix defining the shape and scale of the weighting.

Key Properties:

Mahalanobis distance: d² = (x_current - x_past)^T * Σ^{-1} * (x_current - x_past)
Weight range: w ∈ [0, 1/sqrt(det(Σ))]
Maximum weight: w_max = 1/sqrt(det(Σ)) when states are identical
Decay rate: Controlled by eigenvalues of Σ (larger eigenvalues = slower decay)

Applications:

State-space clustering and similarity weighting
Non-parametric density estimation
Adaptive aggregation based on state similarity
Anomaly detection through distance weighting
Multi-dimensional state space analysis

Configuration:

Provide “covariance_matrix” parameter as a flattened symmetric matrix (row-major order)
Matrix must be positive definite (all eigenvalues > 0)
Matrix dimension must match state vector dimension

Example:

// Configure kernel for 2D state space with covariance matrix
// Σ = [[1.0, 0.5], [0.5, 1.0]] (correlated dimensions)
covariance := []float64{1.0, 0.5, 0.5, 1.0} // row-major flattened
params.Set("covariance_matrix", covariance)

kernel := &GaussianStateIntegrationKernel{}
kernel.Configure(0, settings)
kernel.SetParams(params)

// Weight for similar states will be high, dissimilar states low
weight := kernel.Evaluate(currentState, pastState, currentTime, pastTime)

Performance:

O(d²) setup cost for Cholesky decomposition where d is state dimension
O(d²) evaluation cost for matrix-vector operations
Memory usage: O(d²) for storing Cholesky decomposition
Efficient for moderate dimensions (< 100)

Error Handling:

Panics if covariance matrix is not positive definite
Panics if matrix dimension doesn’t match state dimension
Panics if matrix is not square or symmetric

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

func (*GaussianStateIntegrationKernel) Configure

func (g *GaussianStateIntegrationKernel) Configure(partitionIndex int, settings *simulator.Settings)

func (*GaussianStateIntegrationKernel) Evaluate

func (g *GaussianStateIntegrationKernel) Evaluate(currentState []float64, pastState []float64, currentTime float64, pastTime float64) float64

func (*GaussianStateIntegrationKernel) SetParams

func (g *GaussianStateIntegrationKernel) SetParams(params *simulator.Params)

type InstantaneousIntegrationKernel

InstantaneousIntegrationKernel returns 1.0 for the most recent sample and 0.0 otherwise.

Usage hints:

Useful to select only the latest value when aggregating.

type InstantaneousIntegrationKernel struct{}

func (*InstantaneousIntegrationKernel) Configure

func (i *InstantaneousIntegrationKernel) Configure(partitionIndex int, settings *simulator.Settings)

func (*InstantaneousIntegrationKernel) Evaluate

func (i *InstantaneousIntegrationKernel) Evaluate(currentState []float64, pastState []float64, currentTime float64, pastTime float64) float64

func (*InstantaneousIntegrationKernel) SetParams

func (i *InstantaneousIntegrationKernel) SetParams(params *simulator.Params)

type IntegrationKernel

IntegrationKernel defines the interface for time/state weighting kernels used when aggregating over historical data in simulations.

Integration kernels provide a standardized way to weight historical data points when computing aggregated statistics. They enable flexible temporal and spatial weighting schemes that can be customized for specific aggregation needs.

Mathematical Concept: Integration kernels define weighting functions w(current, past) that determine how much influence a historical data point has on the current aggregation. Common patterns include:

Time-based weighting: w(t_current, t_past) = f(t_current - t_past)
State-based weighting: w(x_current, x_past) = f(||x_current - x_past||)
Hybrid weighting: w(current, past) = f(time_diff, state_diff)

Interface Methods:

Configure: Initialize kernel with simulation settings (called once per partition)
SetParams: Update kernel parameters from simulation context (called each step)
Evaluate: Compute weight for a historical sample (called for each aggregation)

Weight Properties:

Weights must be non-negative: w(current, past) ≥ 0
Weights should be normalized for consistent aggregation scales
Zero weights indicate no influence from that historical sample

Common Kernel Types:

ExponentialIntegrationKernel: Exponential time decay w(t) = exp(-λt)
GaussianStateIntegrationKernel: State distance weighting w(x,y) = exp(-||x-y||²/2σ²)
InstantaneousIntegrationKernel: No weighting, w = 1 for current, 0 for past
PeriodicIntegrationKernel: Periodic time weighting for seasonal patterns

Example Usage:

kernel := &ExponentialIntegrationKernel{}
kernel.Configure(0, settings)
kernel.SetParams(params) // params contains decay rate λ

// Evaluate weight for a sample from 1.0 time units ago
weight := kernel.Evaluate(currentState, pastState, 5.0, 4.0)
// weight = exp(-λ * 1.0)

Performance Considerations:

Evaluate is called frequently during aggregation
Implementations should be optimized for repeated calls
Consider caching expensive computations in SetParams
Avoid memory allocations in Evaluate method

Related Types:

See analysis.AppliedAggregation for usage in data aggregation
See ExponentialIntegrationKernel for exponential decay weighting
See GaussianStateIntegrationKernel for state-distance weighting

type IntegrationKernel interface {
    Configure(partitionIndex int, settings *simulator.Settings)
    SetParams(params *simulator.Params)
    Evaluate(
        currentState []float64,
        pastState []float64,
        currentTime float64,
        pastTime float64,
    ) float64
}

type PeriodicIntegrationKernel

PeriodicIntegrationKernel applies periodic (circular) time weighting.

Usage hints:

Provide “periodic_weighting_timescale”; weight = exp(-2 sin^2(dt/2)/tau2).
Useful for daily/weekly seasonality.

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

func (*PeriodicIntegrationKernel) Configure

func (p *PeriodicIntegrationKernel) Configure(partitionIndex int, settings *simulator.Settings)

func (*PeriodicIntegrationKernel) Evaluate

func (p *PeriodicIntegrationKernel) Evaluate(currentState []float64, pastState []float64, currentTime float64, pastTime float64) float64

func (*PeriodicIntegrationKernel) SetParams

func (p *PeriodicIntegrationKernel) SetParams(params *simulator.Params)

type ProductIntegrationKernel

ProductIntegrationKernel multiplies two kernels to form a composite weight.

Usage hints:

Configure and SetParams will be forwarded to both KernelA and KernelB.
Useful to combine, e.g., temporal and state-distance weightings.

type ProductIntegrationKernel struct {
    KernelA IntegrationKernel
    KernelB IntegrationKernel
}

func (*ProductIntegrationKernel) Configure

func (p *ProductIntegrationKernel) Configure(partitionIndex int, settings *simulator.Settings)

func (*ProductIntegrationKernel) Evaluate

func (p *ProductIntegrationKernel) Evaluate(currentState []float64, pastState []float64, currentTime float64, pastTime float64) float64

func (*ProductIntegrationKernel) SetParams

func (p *ProductIntegrationKernel) SetParams(params *simulator.Params)

type TDistributionStateIntegrationKernel

TDistributionStateIntegrationKernel applies a multivariate t kernel using an input scale matrix and degrees of freedom.

Usage hints:

Provide “scale_matrix” as a flattened symmetric matrix (row-major) and “degrees_of_freedom”.
Weights are proportional to (1 + (x-μ)^T S^{-1} (x-μ)/ν)^{-(d+ν)/2} / det(S).

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

func (*TDistributionStateIntegrationKernel) Configure

func (t *TDistributionStateIntegrationKernel) Configure(partitionIndex int, settings *simulator.Settings)

func (*TDistributionStateIntegrationKernel) Evaluate

func (t *TDistributionStateIntegrationKernel) Evaluate(currentState []float64, pastState []float64, currentTime float64, pastTime float64) float64

func (*TDistributionStateIntegrationKernel) SetParams

func (t *TDistributionStateIntegrationKernel) SetParams(params *simulator.Params)

Generated by gomarkdoc