Skip to content
Skills Library
Science & research · Building & coding

kernel-designer

/kernel-designer

Use when designing or composing custom kernel (covariance) functions for gpCAM — smoothness, periodicity, symmetry, anisotropy, non-stationary amplitude/length-scale kernels (`non_stat_kernel`, Gibbs), non-Euclidean inputs, or neural-network-warped deep kernels (`Network`).

Repository
gpcam ↗
Licence
GPL-3.0
Last repository change
03.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 03.11.2026, without references to retired models or APIs.

Licence

GPL-3.0, otwarta.

What it does and when to use it

Use when designing or composing custom kernel (covariance) functions for gpCAM — smoothness, periodicity, symmetry, anisotropy, non-stationary amplitude/length-scale kernels (`non_stat_kernel`, Gibbs), non-Euclidean inputs, or neural-network-warped deep kernels (`Network`).

Original author description

Use when designing or composing custom kernel (covariance) functions for gpCAM — smoothness, periodicity, symmetry, anisotropy, non-stationary amplitude/length-scale kernels (`non_stat_kernel`, Gibbs), non-Euclidean inputs, or neural-network-warped deep kernels (`Network`).

How it works

  1. When to Use
  2. Kernel Function Contract
  3. Building Blocks
  4. Kernel Recipes
  5. Smoothness Guide
  6. Hyperparameter Coordination
  7. Common Pitfalls
  8. Reference
Original SKILL.md headings · 381 lines, 2,288 words
SKILL.md preview
---
name: kernel-designer
description: Use when designing or composing custom kernel (covariance) functions for gpCAM — smoothness, periodicity, symmetry, anisotropy, non-stationary amplitude/length-scale kernels (`non_stat_kernel`, Gibbs), non-Euclidean inputs, or neural-network-warped deep kernels (`Network`).
gpcam_version: "8.7.x"
fvgp_version: "4.11.x"
last_verified: "2026-10-28 (gpCAM 8.7.0, a21385a)"
---

# Skill: gpCAM Kernel Designer

*Verified against gpCAM 8.7.0 / fvgp 4.11.1 — last checked 2026-10-28 (gpCAM a21385a).*

Design custom kernel (covariance) functions for gpCAM that encode domain knowledge about the experiment.

## When to Use

When a user needs a kernel that goes beyond the default ARD Matérn-3/2:
- Known periodicity in the data
- Symmetry constraints (mirror, rotational)
- Different smoothness in different dimensions
- Combining multiple correlation structures (sum/product kernels)
- Non-Euclidean input spaces (strings, graphs, categorical)
- Non-stationary behavior (varying length scales)

## Kernel Function Contract

Every gpCAM kernel must satisfy:

```python
def my_kernel(x1, x2, hyperparameters):
    """
    Parameters
    ----------
    x1 : np.ndarray, shape (N1, D)
    x2 : np.ndarray, shape (N2, D)
    hyperparameters : np.ndarray, 1D
    
    Returns
    -------
    K : np.ndarray, shape (N1, N2)
        Must be symmetric positive semi-definite.
    """
```

- `x1` and `x2` are 2D arrays even for 1D inputs (for `multi_task_mode="cartesian"`, `x1` and `x2` have shape `(N, D + 1)` with the task index in the last column — see `multi-task-advanced`)
- Declare a 4th positional parameter `my_kernel(x1, x2, hyperparameters, args)` to receive `GPOptimizer(..., args=...)` (`gp_optimizer.py:113-114`; see `experiment-designer` for the full `args` dispatch table)
- The output must be an `(N1, N2)` symmetric positive semi-definite matrix (`k(x1, x2) = k(x2, x1).T`)
- Use vectorized numpy operations — avoid Python loops over data points

## Building Blocks

Import from `gpcam.kernels` (or define locally):

```python
from gpcam.kernels import (
    matern_kernel_diff1,      # Matérn ν=3/2: once differentiable
    matern_kernel_diff2,      # Matérn ν=5/2: twice differentiable
    squared_exponential_kernel,  # RBF/SE: infinitely smooth
    wendland_kernel,           # Compact support (for gp2Scale)
    get_distance_matrix,       # Euclidean distance
    get_anisotropic_distance_matrix,  # ARD distance
)
```

These base kernels operate on **distance matrices**, not raw points. The pattern is:
1. Compute a distance matrix from points
2. Apply a base kernel to the distance matrix

## Kernel Recipes

### Standard Anisotropic (ARD) Kernel
```python
def anisotropic_matern(x1, x2, hps):
    """
    hps[0]: signal variance
    hps[1:D+1]: per-dimension length scales
    """
    d = get_anisotropic_distance_matrix(x1, x2, hps[1:])
    return hps[0] * matern_kernel_diff1(d, 1.0)
```

### Periodic Kernel
For data with known periodicity (e.g., angular measurements, crystal lattice):
```python
def periodic_kernel_1d(x1, x2, hps):
    """
    1-D INPUTS ONLY. Reads x[:, 0] and ignores every other column, so on
    D > 1 inputs the covariance is constant along the remaining axes — the
    matrix becomes rank-deficient and Cholesky will fail or the posterior
    will be degenerate. For D > 1, use `periodic_plus_smooth` below, which
    multiplies the periodic factor by a Matérn factor over the other dims.

    hps[0]: signal variance
    hps[1]: length scale
    hps[2]: period
    """
    d = np.abs(np.subtract.outer(x1[:, 0], x2[:, 0]))
    return hps[0] * np.exp(-2.0 * np.sin(np.pi * d / hps[2])**2 / hps[1]**2)
```

### Periodic + Smooth (Product Kernel)
Periodic in one dimension, smooth Matérn in others:
```python
def periodic_plus_smooth(x1, x2, hps):
    """
    hps[0]: signal variance
    hps[1]: periodic length scale
    hps[2]: period
    hps[3:]: Matérn length scales for remaining dims
    """
    # Periodic in dim 0
    d_periodic = np.abs(np.subtract.outer(x1[:, 0], x2[:, 0]))
    k_periodic = np.exp(-2.0 * np.sin(np.pi * d_periodic / hps[2])**2 / hps[1]**2)
    
    # Matérn in remaining dims
    d_other = get_anisotropic_distance_matrix(x1[:, 1:], x2[:, 1:], hps[3:])
    k_other = matern_kernel_diff1(d_other, 1.0)
    
    return hps[0] * k_periodic * k_other
```

### Sum Kernel (Multiple Scales)
Captures both coarse and fine structure:
```python
def multi_scale_kernel(x1, x2, hps):
    """
    ISOTROPIC — uses a single Euclidean distance, so all input dimensions share
    the same length scale. For per-dimension length scales, build each component
    with `get_anisotropic_distance_matrix` as in `anisotropic_matern` above.

    hps[0]: variance of coarse component
    hps[1]: length scale of coarse component
    hps[2]: variance of fine component
    hps[3]: length scale of fine component
    """
    d = get_distance_matrix(x1, x2)
    k_coarse = hps[0] * matern_kernel_diff2(d, hps[1])  # smooth, long-range
    k_fine = hps[2] * matern_kernel_diff1(d, hps[3])     # rougher, short-range
    return k_coarse + k_fine
```

### Symmetry-Enforcing Kernel
For data known to be symmetric about an axis:
```python
def symmetric_kernel_x(x1, x2, hps):
    """Mirror symmetry about x=0 in the first dimension."""
    x1_flip = x1.copy()
    x1_flip[:, 0] = -x1_flip[:, 0]
    x2_flip = x2.copy()
    x2_flip[:, 0] = -x2_flip[:, 0]
    
    d = get_anisotropic_distance_matrix
    k = lambda a, b: hps[0] * matern_kernel_diff1(d(a, b, hps[1:]), 1.0)
    
    return 0.25 * (k(x1, x2) + k(x1_flip, x2) + k(x1, x2_flip) + k(x1_flip, x2_flip))
```

### L1 (Manhattan) Distance Kernel
Separable per dimension — each dimension contributes independently:
```python
def l1_kernel(x1, x2, hps):
    """
    SEPARABLE and ANISOTROPIC — a product of independent per-dimension
    exponential kernels, so dimension i has its own length scale hps[1 + i].
    Requires D + 1 hyperparameters. Rougher than Matérn-3/2 in every direction.
    """
    k = hps[0] * np.ones((len(x1), len(x2)))
    for i in range(x1.shape[1]):
        d_i = np.abs(np.subtract.outer(x1[:, i], x2[:, i]))
        k *= np.exp(-d_i / hps[1 + i])
    return k
```

### Non-Stationary Kernels (varying amplitude or length scale)

A stationary kernel assumes the covariance depends only on `x1 - x2`, so the signal
amplitude and smoothness are the same everywhere. Real experiments often violate
this — a sample is featureless in one corner and structured in another. Two
practical constructions:

**(a) Varying amplitude.** `non_stat_kernel(x1, x2, x0, w, l)` builds `g(x1) g(x2)ᵀ`
from radial basis functions at locations `x0` with weights `w` (one per basis
location) and scalar width `l`. On its own it is low-rank and degenerate — and when
the learned amplitude `g(x)` passes through zero at some points, those rows of the
covariance vanish and Cholesky fails with `array must not contain infs or NaNs`. Two
things are therefore mandatory: **multiply by a stationary kernel**, and **add a
small constant floor** so the amplitude never collapses the matrix:

```python
from gpcam.kernels import non_stat_kernel, get_anisotropic_distance_matrix, matern_kernel_diff1

# Basis-function locations: a coarse grid over the input space. Fixed, not learned.
X0 = np.array([[2.0], [5.0], [8.0]])
NB = len(X0)

def varying_amplitude_kernel(x1, x2, hps):
    """
    Amplitude varies over the input space; smoothness does not.

    hps[0]          = basis width l (scalar, > 0)
    hps[1:1+NB]     = basis weights w, one per basis location (may be negative)
    hps[1+NB:]      = D stationary length scales
    Total: 1 + NB + D hyperparameters
    """
    floor = 1e-2      # keeps the amplitude term full-rank when g(x) crosses zero
    # NOTE the argument order: non_stat_kernel(x1, x2, x0, w, l) — weights, then width.
    k_amp = non_stat_kernel(x1, x2, X0, hps[1:1 + NB], hps[0]) + floor
    d = get_anisotropic_distance_matrix(x1, x2, hps[1 + NB:])
    return k_amp * matern_kernel_diff1(d, 1.0)
```

Watch the argument order — `non_stat_kernel(x1, x2, x0, w, l)` takes the **weight
vector before the scalar width**, which is easy to reverse. The `floor` term is not
cosmetic: without it, training wanders into weight vectors that zero out `g(x)` at a
data point and the run dies mid-optimization. More basis functions means more
flexibility and more hyperparameters — start with 3-5 and only add more if the fit
demands it.

**(b) Varying length scale (Gibbs kernel).** Smoothness itself changes across the
space — sharp features in one region, smooth background in another. The prefactor
below is what keeps it PSD; do not drop it:

```python
def gibbs_kernel_1d(x1, x2, hps):
    """
    1-D Gibbs kernel with a linearly varying length scale l(x) = a + b*|x|.

    hps[0] = a, base length scale     (> 0)
    hps[1] = b, growth rate           (>= 0; b = 0 recovers a stationary SE kernel)
    hps[2] = signal variance
    Total: 3 hyperparameters
    """
    a, b, sv = hps[0], hps[1], hps[2]
    l1 = a + b * np.abs(x1[:, 0])
    l2 = a + b * np.abs(x2[:, 0])
    L1, L2 = np.meshgrid(l1, l2, indexing="ij")
    prefactor = np.sqrt(2.0 * L1 * L2 / (L1**2 + L2**2))   # required for PSD
    d2 = np.subtract.outer(x1[:, 0], x2[:, 0])**2
    return sv * prefactor * np.exp(-d2 / (L1**2 + L2**2))
```

Keep `a` bounded away from zero (e.g. `[0.05, 5.0]`) — a length scale that collapses
toward zero is the most common cause of singular covariance matrices in
non-stationary models. Any `l(x)` that stays strictly positive works in place of the
linear form; for D > 1 use a per-dimension `l_i(x)` and take the product.

### Non-Euclidean Input Spaces (strings, graphs, categorical)

gpCAM accepts arbitrary Python objects as inputs — `x_data` can be a list of strings, graphs, molecules, etc. The only requirement is that your kernel computes a valid covariance between any two objects.

```python
from gpcam import GPOptimizer
from gpcam.kernels import matern_kernel_diff1

def string_distance(s1, s2):
    diff = abs(len(s1) - len(s2))
    common = min(len(s1), len(s2))
    return diff + sum(a != b for a, b in zip(s1[:common], s2[:common]))

def string_kernel(x1, x2, hps):
    """x1, x2 are lists/sequences of strings; hps = [signal_var, length_scale]."""
    d = np.array([[string_distance(a, b) for b in x2] for a in x1])
    return hps[0] * matern_kernel_diff1(d, hps[1])

x_data = ["hello", "world", "this", "is", "gpcam"]
y_data = np.array([2.0, 1.9, 1.8, 3.0, 5.0])

gp = GPOptimizer(x_data, y_data,
                 init_hyperparameters=np.ones(2),
                 kernel_function=string_kernel)
gp.train(hyperparameter_bounds=np.array([[1e-3, 100.], [1e-3, 100.]]))

# Predict on new objects:
gp.posterior_mean(["full"])["m(x)"]

# Ask which of a candidate set to measure next.
# Keep n well below len(candidates) — asking for as many points as the set
# contains just returns the whole set and selects nothing.
candidates = ["who", "could", "it", "be", "hello", "there", "gpcam", "rules"]
gp.ask(candidates, n=2)
```

Notes:
- A Python `for` loop over objects is fine here (you're bottlenecked by the distance function, not numpy).
- If the distance function is symmetric, the resulting kernel is automatically symmetric; you still need the base kernel (Matérn/SE) to make it PSD.
- For multi-task on non-Euclidean inputs: `GPOptimizer(x_strings, y_multi, kernel_function=..., multi_task_mode="cartesian")` works the same way; the kernel then receives `[x, task]` pairs (`p[0]` the object, `p[1]` the task).

### Deep Kernel (NN-warped input space)

For hard multi-task structure or learned metrics, warp the input through a small neural net and then apply a stationary kernel in the warped space. `gpcam.deep_kernel_network.Network` gives you an MLP whose weights you read out of `hps`.

**You must call `set_weights` / `set_biases` inside the kernel.** If you skip that step the network keeps its randomly initialized weights, `hps[2:]` have no effect on the covariance, and training silently optimizes over a flat likelihood — you get a fixed random feature map that looks trained but is not.

`Network(dim, layer_width)` has three `nn.Linear` layers, so the parameter block is:

| Slice | Shape | Count |
|---|---|---|
| `w1` (layer1 weight) | `(layer_width, dim)` | `layer_width * dim` |
| `w2` (layer2 weight) | `(layer_width, layer_width)` | `layer_width ** 2` |
| `w3` (layer3 weight) | `(dim, layer_width)` | `dim * layer_width` |
| `b1`, `b2` (biases) | `(layer_width,)` each | `2 * layer_width` |
| `b3` (layer3 bias) | `(dim,)` | `dim` |

which sums to `n.number_of_hps == 2*dim*layer_width + layer_width**2 + 2*layer_width + dim`.

```python
import numpy as np
from gpcam import GPOptimizer
from gpcam.deep_kernel_network import Network
from gpcam.kernels import get_distance_matrix, matern_kernel_diff1

ISET_DIM = 3
LAYER_WIDTH = 5
n = Network(ISET_DIM, LAYER_WIDTH)
N_NN = n.number_of_hps        # number of NN hyperparameters to reserve

def _load_network(nn_hps, dim=ISET_DIM, w=LAYER_WIDTH):
    """Unpack a flat hyperparameter slice into the network's weights and biases."""
    i = 0
    w1 = nn_hps[i:i + w * dim].reshape(w, dim);   i += w * dim
    w2 = nn_hps[i:i + w * w].reshape(w, w);       i += w * w
    w3 = nn_hps[i:i + dim * w].reshape(dim, w);   i += dim * w
    b1 = nn_hps[i:i + w];                         i += w
    b2 = nn_hps[i:i + w];                         i += w
    b3 = nn_hps[i:i + dim];                       i += dim
    assert i == len(nn_hps), f"expected {len(nn_hps)} NN hps, consumed {i}"
    n.set_weights(w1, w2, w3)
    n.set_biases(b1, b2, b3)

def deep_kernel(x1, x2, hps):
    """
    hps[0]  = signal variance
    hps[1]  = length scale (in the warped space)
    hps[2:] = NN weights and biases (length n.number_of_hps)
    """
    _load_network(hps[2:])            # <-- REQUIRED; without it hps[2:] do nothing
    d = get_distance_matrix(n.forward(x1), n.forward(x2))
    return hps[0] * matern_kernel_diff1(d, hps[1])

# Total hyperparameters: 2 + N_NN
init_hps = np.concatenate([[1.0, 1.0], np.random.randn(N_NN) * 0.5])
hp_bounds = np.array([[0.01, 10.0], [0.01, 10.0]] + [[-2.0, 2.0]] * N_NN)

gp = GPOptimizer(x_data, y_data, init_hyperparameters=init_hps,
                 kernel_function=deep_kernel)
gp.train(hyperparameter_bounds=hp_bounds, method="adam", max_iter=100)
```

Sanity check that the unpacking is live — evaluate the kernel at two different NN hyperparameter draws and confirm the matrices differ:

```python
a = np.concatenate([[1., 1.], np.random.randn(N_NN)])
b = np.concatenate([[1., 1.], np.random.randn(N_NN)])
assert not np.allclose(deep_kernel(x1, x2, a), deep_kernel(x1, x2, b)), \
    "NN hyperparameters are not reaching the kernel"
```

Training notes: `method="mcmc"` or `method="adam"` scale better than `global`/`local` to NN-sized hyperparameter vectors. Bounds on NN weights should be symmetric around zero (e.g. `[-2, 2]`) — weights are not scale parameters and must be allowed to go negative.

## Smoothness Guide

| Kernel | Smoothness | When to Use |
|--------|-----------|-------------|
| Matérn-1/2 (exponential) | Rough, continuous but not differentiable | Sharp peaks, discontinuities |
| Matérn-3/2 | Once differentiable | **Default choice** — most physical data |
| Matérn-5/2 | Twice differentiable | Smoother physical signals |
| Squared Exponential (RBF) | Infinitely smooth | Very smooth data; tends to oversmooth |

## Hyperparameter Coordination

Kernel hyperparameters occupy the leading slice `hps[:K]`, followed by prior-mean (`hps[K : K + M]`) and noise (`hps[K + M :]`) parameters — see `experiment-designer` ("Hyperparameter Coordination") for the canonical index convention.

- **Signal variance**: initialize near `np.var(y_data)` (or `1.0`), bounds `[0.001, 10 * np.var(y_data)]`
- **Length scales**: initialize near `0.1 * range(x_dim)`, bounds `[0.01 * range(x_dim), 10 * range(x_dim)]`
- **Period**: initialize near the expected period, bounds `[0.5 * expected, 2 * expected]`

## Common Pitfalls

1. **Non-PSD kernel**: Sums and products of valid kernels are valid. Differences are NOT guaranteed PSD.
2. **Python loops over data**: Use `np.subtract.outer` and vectorized ops. A double for-loop over N points is O(N²) in Python — unusable for >100 points.
3. **Forgetting signal variance**: Always include a leading amplitude hyperparameter (`hps[0] * ...`).
4. **Length scale = 0**: Causes division by zero. Set lower bounds > 0 (e.g., 0.001).
5. **Mismatched hyperparameter count**: The bounds array rows must equal the total hyperparameter vector length.

## Reference

See `gpcam/kernels.py` (re-exports the fvGP kernel library) for the full library of kernel building blocks and the [gpCAM documentation](https://gpcam.readthedocs.io) for mathematical details.

Versions

The database has no other skills named kernel-designer.

Database snapshot: 13.11.2026 · package version 290c3e1e72a4 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100experiment-designer
    Use for end-to-end autonomous experiment design with gpCAM. Translates a scientist's description of their measurement into a complete, runnable gpCAM script — useful for replacing raster scans with adaptive sampling, peak-finding, or parameter optimization.
  • 100gp2scale-advanced
    Use for large-scale gpCAM experiments (>10k points up to millions) using sparse compactly-supported kernels and Dask distributed computing for exact GP computation at scale.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.