Neural kernels API

The neural-kernel scaffold lives in motac.models.neural_kernels.

This module establishes a stable import path and a minimal kernel interface that nonparametric or learned variants can build on.

Contract validation helper

The validate_kernel_fn helper exists to fail fast if a kernel implementation violates the minimal (v1) contract:

• input: a nonnegative numpy.ndarray of distances / travel-times d

• output: a numpy.ndarray of the same shape with finite, nonnegative weights

Typical use is in downstream modules (or your own experiments) at import-time or construction-time:

from motac.models.neural_kernels import ExpDecayKernel, validate_kernel_fn

kernel = ExpDecayKernel(lengthscale=1.5)
validate_kernel_fn(kernel)

Neural / learned kernel scaffolding.

This module intentionally starts small: it establishes a stable import path and a minimal kernel interface for future nonparametric / neural Hawkes variants.

The goal is to make downstream code able to depend on a simple, documented call signature and shape contract.

class motac.models.neural_kernels.KernelFn(*args, **kwargs)

Bases: Protocol

A minimal kernel function interface.

Contract (v1 scaffold): kernels map a nonnegative distance / travel-time tensor to a same-shaped, nonnegative weight tensor.

Implementations should be pure and deterministic.

__init__(*args, **kwargs)

motac.models.neural_kernels.validate_kernel_fn(kernel, *, name='kernel')

Validate that a kernel satisfies the minimal (v1) shape/value contract.

This is intentionally small and opinionated: it exists to catch accidental contract drift early (e.g. returning negative weights or wrong shapes).

Parameters:

• kernel (KernelFn) – Callable to validate.

• name (str) – Used in raised error messages.

Return type:

None

class motac.models.neural_kernels.ExpDecayKernel(lengthscale=1.0)

Bases: object

A tiny, deterministic kernel implementation for unit tests.

Computes w = exp(-d / lengthscale) elementwise.

Parameters:

lengthscale (float) – Positive scale parameter controlling the rate of decay.

lengthscale: float = 1.0

__init__(lengthscale=1.0)

class motac.models.neural_kernels.SoftplusQuadraticKernel(a0=0.0, a1=-0.001, a2=0.0)

Bases: object

A tiny nonlinear kernel for ablation studies.

Computes w = softplus(a0 + a1 * d + a2 * d^2) elementwise to allow departures from a pure exponential decay while preserving nonnegativity.

a0: float = 0.0

a1: float = -0.001

a2: float = 0.0

__init__(a0=0.0, a1=-0.001, a2=0.0)