Een praktische gids voor TorchCurves, de PyTorch-library die B-spline- en Legendre-curves tot trainbare lagen maakt. U installeert de library, fit een curve, kiest een basis en een aantal knopen, bouwt een monotone kalibratiecurve en een additief model op tabeldata, vergelijkt ze met scikit-learn, SciPy, een KAN en een MLP, exporteert de coëfficiënten zodat ze zonder PyTorch kunnen worden geaudit, en test het geheel. Elke output hieronder komt uit onze eigen run.
torchcurves (0.3.4, Apache-2.0, Python 3.12+, PyTorch 2.9+) biedt BSplineCurve, LegendreCurve, BSplineBasis en Sum. Inputs met vorm (batch, curves) worden punten met vorm (batch, curves, dim), met gradiënten naar zowel de inputs als de coëfficiënten. Gebruik als standaard B-splines met 8 tot 12 coëfficiënten en een penalty op tweede differenties; dwing monotone vormen af via de constructie; standaardiseer inputs en kies de input map bewust; exporteer knopen, coëfficiënten en de map naar JSON en controleer ze tegen SciPy. Voor één losse curve is SciPy sneller en fit het beter; TorchCurves verdient zijn plaats wanneer de curve deel uitmaakt van een PyTorch-model.
Deze technote hoort bij onze blogpost Differentiable Curves in PyTorch: Small, Auditable Models with TorchCurves, die het waarom voor een breder publiek behandelt. API-details komen uit de broncode van torchcurves in versie 0.3.4 en uit het paper van de auteur, Alex Shtoff [1][2]. De feiten zijn bijgewerkt tot 16 november 2026.
Voor wie dit is, wat u gaat bouwen
Voor wie. Python-ontwikkelaars en datascientists die basiskennis van PyTorch hebben (modules, optimizers, backward()) en modellen willen waarvan het gedrag per input kan worden geplot, begrensd en beoordeeld. Er wordt geen splinetheorie verondersteld; we leggen onderweg uit wat u nodig hebt.
Wat u gaat bouwen, in zes korte scripts en één testbestand:
- Een hello world die de tensorvormen laat zien.
- Eén gefitte curve, waarbij aantallen knopen, B-spline tegenover Legendre, en de smoothing spline van SciPy worden vergeleken.
- Een monotone kalibratiecurve voor kansen, tegenover een onbegrensde spline en isotone regressie.
- Een additief model (één curve per feature) en een kleine KAN op tabeldata, tegenover lineaire regressie, een spline-GAM in scikit-learn, gradient boosting en een MLP.
- Een export van de getrainde curves naar JSON, opnieuw geëvalueerd in SciPy, plus een
torch.export-programma voor serving. - Een pytest-bestand dat vormen, gradiënten, overeenstemming met SciPy en monotonie controleert.
Vereisten. Python 3.12 of nieuwer, ongeveer 1 GB schijfruimte voor PyTorch, en een willekeurige recente laptop. Alles hier draait op de CPU in enkele seconden tot een paar minuten. Wij gebruikten Python 3.13, PyTorch 2.15.0, torchcurves 0.3.4, SciPy 1.18.1, scikit-learn 1.9.1 en NumPy 2.5.4 op een Mac met Apple silicon.
1. Installeren
Gebruik een nieuwe virtuele omgeving. Installeer op Linux eerst de CPU-only wheel van PyTorch, tenzij u CUDA nodig hebt; die is meerdere keren kleiner. Op macOS is de standaardwheel al voor de CPU (met de MPS-backend van Apple).
python3 -m venv .venv && source .venv/bin/activate
# Linux, CPU only (skip on macOS, or use the CUDA index for GPUs)
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install torchcurves scipy scikit-learn pytest
python -c "import torch, torchcurves; print(torch.__version__, torchcurves.__version__)"
torchcurves heeft één afhankelijkheid, torch>=2.9.0, en declareert requires_python >= 3.12 [3]. Als pip meldt dat er geen overeenkomende distributie is, controleer dan eerst uw Python-versie.
2. Hallo, curve: de vormen die u moet onthouden
Elke curvemodule neemt een 2D-input met vorm (B, C): B samples, één kolom per curve. Ze geeft (B, C, D) terug: één D-dimensionaal punt per sample per curve. De coëfficiënten van de curves staan in control_points met vorm (C, K, D), waarbij K het aantal coëfficiënten per curve is.
# s1_hello.py
import torch
import torchcurves as tc
torch.manual_seed(0)
u = torch.rand(4, 3) # (batch B, curves C)
curve = tc.BSplineCurve(num_curves=3, dim=2, knots_config=8)
y = curve(u) # (B, C, D)
print(u.shape, "->", y.shape)
print(curve)
print("control_points:", tuple(curve.control_points.shape))
print("knots:", [round(k, 3) for k in curve.knots.tolist()])
y.sum().backward()
print("grad on control points:", curve.control_points.grad is not None)
Output:
torch.Size([4, 3]) -> torch.Size([4, 3, 2])
BSplineCurve(num_curves=3, n_control_points_per_curve=8, dim=2, degree=3, knots_shape=torch.Size([12]))
control_points: (3, 8, 2)
knots: [-1.0, -1.0, -1.0, -1.0, -0.6, -0.2, 0.2, 0.6, 1.0, 1.0, 1.0, 1.0]
grad on control points: True
Drie dingen om op te letten. knots_config=8 betekent acht controlepunten (coëfficiënten) per curve, niet acht knopen: een kubische spline met acht coëfficiënten heeft 12 knopen, waarvan er aan elk uiteinde vier herhaald worden zodat de curve zich aan de randen goed gedraagt. De knopen lopen standaard van -1 tot 1. En gradiënten stromen via een gewone backward()-aanroep naar de coëfficiënten, omdat de library een eigen autograd-functie voor B-splines implementeert [2].
Als u BSplineCurve(num_control_points=8, degree=3, dim=1) in een blogpost hebt gezien (waaronder een eerdere versie van de onze), dan is dat voor elke gepubliceerde versie onjuist: er is geen argument num_control_points en num_curves is verplicht. De werkelijke signatuur is BSplineCurve(num_curves, dim, degree=3, knots_config=10, parameter_range=None, input_map="real.rational"). LegendreCurve(num_curves, dim, degree, input_map="real.rational", checkpoint_segments=None) neemt een graad in plaats van knopen; let op dat hij zijn coefficients opslaat als (K, C, D), met de coëfficiëntas eerst.
3. Eén curve fitten, en een basis en aantal knopen kiezen
De eerste echte taak: fit een ruisig 1D-signaal met een gladde trend en een scherpe hellingsverandering bij x = 0.7. We proberen B-splines met 6 tot 48 coëfficiënten, één sterk overgedimensioneerde spline met een ruwheidspenalty, Legendre-polynomen van vergelijkbare omvang, en make_smoothing_spline van SciPy, dat zijn eigen gladheidsniveau kiest via gegeneraliseerde kruisvalidatie [9].
# s2_fit.py
import numpy as np
import torch
import torchcurves as tc
from scipy.interpolate import make_smoothing_spline
torch.manual_seed(0)
rng = np.random.default_rng(0)
def truth(x):
# smooth trend plus a sharp change at x = 0.7
return np.sin(2 * np.pi * x) + 1.5 * (x > 0.7) * (x - 0.7) * 10
x = rng.uniform(0, 1, 600)
y = truth(x) + rng.normal(0, 0.2, x.size)
idx = rng.permutation(x.size)
tr, va = idx[:400], idx[400:]
grid = np.linspace(0, 1, 501)
def to_t(a):
return torch.as_tensor(a, dtype=torch.float32).reshape(-1, 1) # (B, 1 curve)
def make_curve(kind, size):
if kind == "bspline":
# knots spread uniformly over [0, 1]; "real.clamp" passes x through unchanged
return tc.BSplineCurve(1, 1, knots_config=size, parameter_range=(0, 1), input_map="real.clamp")
# Legendre lives on [-1, 1]; clamp(2x - 1) maps [0, 1] onto it
return tc.LegendreCurve(1, 1, degree=size, input_map="real.clamp")
def prep(kind, x):
return to_t(x) if kind == "bspline" else to_t(2 * x - 1)
def second_diff(c):
# roughness penalty on neighbouring coefficients (P-spline style)
return (c[:, 2:] - 2 * c[:, 1:-1] + c[:, :-2]).pow(2).sum()
def fit(kind, size, lam=0.0, steps=1500):
curve = make_curve(kind, size)
opt = torch.optim.Adam(curve.parameters(), lr=0.05)
xt, yt = prep(kind, x[tr]), to_t(y[tr])
for _ in range(steps):
opt.zero_grad()
pred = curve(xt).squeeze(-1)
loss = (pred - yt).pow(2).mean()
if kind == "bspline" and lam > 0:
loss = loss + lam * second_diff(curve.control_points)
loss.backward()
opt.step()
with torch.no_grad():
va_rmse = (curve(prep(kind, x[va])).squeeze(-1) - to_t(y[va])).pow(2).mean().sqrt().item()
g = curve(prep(kind, grid)).squeeze().numpy()
true_rmse = float(np.sqrt(np.mean((g - truth(grid)) ** 2)))
return curve, va_rmse, true_rmse
print(f"{'basis':9} {'size':>4} {'lambda':>7} {'params':>6} {'val RMSE':>9} {'vs truth':>9}")
for kind, size, lam in [("bspline", 6, 0), ("bspline", 12, 0), ("bspline", 24, 0),
("bspline", 48, 0), ("bspline", 48, 1e-3),
("legendre", 5, 0), ("legendre", 11, 0), ("legendre", 23, 0)]:
curve, va_rmse, true_rmse = fit(kind, size, lam)
n = sum(p.numel() for p in curve.parameters())
print(f"{kind:9} {size:>4} {lam:>7g} {n:>6} {va_rmse:>9.3f} {true_rmse:>9.3f}")
o = np.argsort(x[tr])
sp = make_smoothing_spline(x[tr][o], y[tr][o]) # GCV picks the smoothing level
print(f"{'scipy':9} {'':>4} {'GCV':>7} {'':>6} {np.sqrt(np.mean((sp(x[va]) - y[va])**2)):>9.3f} "
f"{np.sqrt(np.mean((sp(grid) - truth(grid))**2)):>9.3f}")
print("noise std (floor for val RMSE): 0.200")
Output (val RMSE is de fout ten opzichte van achtergehouden ruisige punten, dus 0.200 is de ondergrens; "vs truth" is de fout ten opzichte van de ruisvrije functie):
basis size lambda params val RMSE vs truth
bspline 6 0 6 0.226 0.110
bspline 12 0 12 0.207 0.046
bspline 24 0 24 0.209 0.044
bspline 48 0 48 0.218 0.071
bspline 48 0.001 48 0.208 0.044
legendre 5 0 6 0.228 0.110
legendre 11 0 12 0.211 0.047
legendre 23 0 24 0.209 0.047
scipy GCV 0.206 0.027
noise std (floor for val RMSE): 0.200
Zo leest u het:
- Te weinig coëfficiënten leiden tot underfitting (6 coëfficiënten, fout ten opzichte van de waarheid 0,110). Twaalf tot 24 is hier het optimum.
- Te veel leiden tot overfitting (48 coëfficiënten, 0,071), en een kleine penalty op de tweede differenties van naburige coëfficiënten lost dat op (48 met penalty, 0,044). Dit is het P-splinerecept van Eilers en Marx: gebruik ruim voldoende knopen en laat een penalty de gladheid regelen [4]. Daardoor wordt het aantal knopen veel minder kritisch.
- B-spline en Legendre liggen bij gelijke omvang dicht bij elkaar op dit signaal. Het verschil blijkt uit het gedrag, niet uit de score: een B-splinecoëfficiënt verplaatst de curve lokaal, een Legendre-coëfficiënt verplaatst hem overal (figuur hieronder), dus B-splines gaan beter om met knikken en beperkingen, en Legendre-reeksen zijn gladder en compacter voor werkelijk gladde functies.
- SciPy wint als losse smoother (0,027). Het lost het gepenaliseerde kleinste-kwadratenprobleem exact op en kiest de penalty automatisch; gradient descent met een vaste learning rate komt dichtbij, maar niet helemaal. Als één curve uw hele model is, gebruik dan SciPy. Gebruik TorchCurves wanneer de curve een laag is in iets groters.
Vuistregels die in onze runs standhielden: begin met kubische B-splines (de standaard degree=3) en 8 tot 12 coëfficiënten per input; ga u boven de 20, voeg dan een ruwheidspenalty toe; kies de uiteindelijke omvang op validatiedata. Kies Legendre wanneer de functie zeer glad is en u zo min mogelijk parameters wilt, en gebruik voor hoge graden checkpoint_segments om in de backward pass rekenwerk tegen geheugen uit te ruilen [2].
4. Input maps: waar uw knopen werkelijk terechtkomen
Curves leven op een begrensd interval (standaard -1 tot 1), maar features niet. Elke module past daarom eerst een input map toe. De ingebouwde opties zijn "real.rational" (de standaard van de module in 0.3.4, x / sqrt(s² + x²)), "real.arctan", "real.clamp" (x / s afkappen tot het interval), en "nonneg.rational" en "nonneg.arctan" voor niet-negatieve inputs. Gebruik voor een eigen schaal objecten zoals tc.maps.Real.clamp(scale=3.0), of geef een willekeurige callable f(x, out_min, out_max) door [2].
Praktische richtlijnen:
- Standaardiseer eerst, en kies dan. Voor ongeveer normaal verdeelde features geeft
tc.maps.Real.clamp(scale=3.0)gelijkmatige knopen over ±3 standaarddeviaties en een vlakke extrapolatie daarbuiten, wat gemakkelijk uit te leggen is. - Gebruik de rational- of arctan-maps voor zware staarten, waar u ook ver weg enige resolutie wilt en accepteert dat die grof is.
- Voor inputs die al in [0, 1] liggen, stelt u
parameter_range=(0, 1)in met"real.clamp", zodat de knopen precies op uw databereik liggen, zoals in de scripts hierboven. - De release 0.3.0 heeft de oude argumenten
normalize_fnennormalization_scalevervangen doorinput_map[2]. Code die voor 0.2.x is geschreven, faalt.
5. Een monotone kalibratiecurve
Een veelvoorkomende behoefte in productie: een ruwe modelscore omzetten in een kans die nooit daalt naarmate de score stijgt. B-splines maken dit eenvoudig, omdat een spline waarvan de coëfficiënten stijgen zelf ook stijgt [2]. We parametriseren de coëfficiënten als een eerste waarde plus een cumulatieve som van positieve stappen (softplus houdt ze positief), en geven ze door aan een BSplineBasis. De vergelijking is een onbegrensde spline van dezelfde omvang en de isotone regressie van scikit-learn.
# s3_monotone.py
import numpy as np
import torch
import torch.nn.functional as F
from torch import nn
import torchcurves as tc
from sklearn.isotonic import IsotonicRegression
from sklearn.metrics import log_loss
torch.manual_seed(0)
rng = np.random.default_rng(1)
# Synthetic calibration data: a raw score in [0, 1] and a 0/1 outcome whose
# true probability rises with the score (slowly, then steeply).
n = 3000
score = rng.beta(2, 2, n)
p_true = 1 / (1 + np.exp(-(8 * score**2 - 4)))
y = (rng.uniform(size=n) < p_true).astype(np.float32)
tr, te = np.arange(0, 2000), np.arange(2000, n)
class MonotoneCurve(nn.Module):
"""A 1-D cubic B-spline whose coefficients are forced to increase,
so the curve itself is non-decreasing (a property of B-splines)."""
def __init__(self, n_coef=10):
super().__init__()
self.basis = tc.BSplineBasis(degree=3, knots_config=n_coef,
parameter_range=(0, 1), input_map="real.clamp")
self.raw = nn.Parameter(torch.zeros(n_coef))
def coefficients(self):
first, rest = self.raw[:1], F.softplus(self.raw[1:]) # increments > 0
return torch.cumsum(torch.cat([first, rest]), 0)
def forward(self, x): # x: (B,)
c = self.coefficients().view(1, -1, 1) # (1 curve, C, D=1)
return self.basis(x.view(-1, 1), c).view(-1) # logits, (B,)
class FreeCurve(nn.Module):
"""The same spline with unconstrained coefficients."""
def __init__(self, n_coef=10):
super().__init__()
self.curve = tc.BSplineCurve(1, 1, knots_config=n_coef,
parameter_range=(0, 1), input_map="real.clamp")
def coefficients(self):
return self.curve.control_points.view(-1)
def forward(self, x):
return self.curve(x.view(-1, 1)).view(-1)
def roughness(c):
return (c[2:] - 2 * c[1:-1] + c[:-2]).pow(2).sum()
def train(model, steps=2000, lam=0.0):
opt = torch.optim.Adam(model.parameters(), lr=0.05)
xt = torch.as_tensor(score[tr], dtype=torch.float32)
yt = torch.as_tensor(y[tr])
for _ in range(steps):
opt.zero_grad()
loss = F.binary_cross_entropy_with_logits(model(xt), yt)
if lam > 0:
loss = loss + lam * roughness(model.coefficients())
loss.backward()
opt.step()
return model
grid = torch.linspace(0, 1, 1001)
for name, model, lam in [("free B-spline", FreeCurve(20), 0.0),
("monotone B-spline", MonotoneCurve(20), 0.0),
("monotone + smooth (1e-3)", MonotoneCurve(20), 1e-3)]:
train(model, lam=lam)
with torch.no_grad():
p_te = torch.sigmoid(model(torch.as_tensor(score[te], dtype=torch.float32))).numpy()
g = torch.sigmoid(model(grid)).numpy()
drops = int((np.diff(g) < -1e-6).sum())
print(f"{name:28} test log-loss {log_loss(y[te], p_te):.4f} grid points where curve falls: {drops}")
iso = IsotonicRegression(out_of_bounds="clip", y_min=1e-3, y_max=1 - 1e-3).fit(score[tr], y[tr])
print(f"{'isotonic regression (sklearn)':28} test log-loss {log_loss(y[te], iso.predict(score[te])):.4f}"
f" distinct output levels: {len(np.unique(iso.predict(grid.numpy())))}")
print(f"{'true probability':28} test log-loss {log_loss(y[te], p_true[te]):.4f}")
for lam in (0.0, 1e-3):
torch.manual_seed(0)
m = train(MonotoneCurve(20), lam=lam)
c = [round(float(v), 2) for v in m.coefficients().detach()]
print(f"lambda={lam:g} last 4 coefficients: {c[-4:]}")
Output:
free B-spline test log-loss 0.3318 grid points where curve falls: 140
monotone B-spline test log-loss 0.3295 grid points where curve falls: 0
monotone + smooth (1e-3) test log-loss 0.3296 grid points where curve falls: 0
isotonic regression (sklearn) test log-loss 0.3311 distinct output levels: 37
true probability test log-loss 0.3268
lambda=0 last 4 coefficients: [2.63, 2.89, 3.61, 32.61]
lambda=0.001 last 4 coefficients: [2.14, 3.1, 4.09, 5.09]
De onbegrensde spline golft: hij daalt in 140 van de 1.000 rasterstappen, en dat kunt u niet uitleveren als prijs- of risicocurve. De monotone daalt nooit, door de constructie, en is ook iets beter op achtergehouden data. Isotone regressie is ook monotoon, maar is hier een trapfunctie met 37 niveaus; de spline is glad en heeft 20 getallen die u kunt afdrukken.
De laatste twee regels tonen een valkuil die het kennen waard is. Zonder penalty dreef de laatste coëfficiënt af naar 32,6 op de logitschaal: er liggen weinig trainingspunten bij een score van 1, en niets houdt de randcoëfficiënt tegen. Een ruwheidspenalty van 0,001 bracht hem terug naar 5,1 zonder verlies aan nauwkeurigheid. Inspecteer altijd de randcoëfficiënten.
De README en het voorbeeldnotebook van de library gebruiken dezelfde truc in een rijkere vorm: een encodernetwerk zet veilingfeatures om in stijgende coëfficiënten, en elke sample krijgt een eigen curve van winkans tegenover bod [2]. Dat is het derde patroon in de figuur met tensorvormen.
6. Een additief model en een KAN op tabeldata
Nu een probleem met tabeldata. We genereren vijf gestandaardiseerde features met bekende effecten (een verzadigende tanh, een U-vorm, een stap, een golf, en één feature zonder effect) plus een verborgen interactie tussen de eerste twee, en Gaussische ruis met standaarddeviatie 0,3. Het additieve model is één BSplineCurve met vijf curves van elk 12 coëfficiënten, gevolgd door tc.Sum: voorspelling = bias + f0(x0) + ... + f4(x4). Dit is een gegeneraliseerd additief model (GAM), getraind met gradient descent; het neural additive model van Agarwal et al. is hetzelfde idee met kleine netwerken in plaats van splines [7].
De KAN stapelt twee curvelagen met na elke laag een som, zoals in de README van de library; Kolmogorov-Arnold-netwerken plaatsen een leerbare 1D-functie op elke rand van het netwerk [5].
# s4_additive.py
import numpy as np
import torch
from torch import nn
import torchcurves as tc
from sklearn.linear_model import LinearRegression, RidgeCV
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import SplineTransformer, StandardScaler
from sklearn.ensemble import HistGradientBoostingRegressor
torch.manual_seed(0)
rng = np.random.default_rng(0)
# --- synthetic tabular data with known shape functions -----------------
n, F_ = 6000, 5
X = rng.normal(size=(n, F_))
shapes = [
lambda v: np.tanh(2 * v), # saturating
lambda v: 0.5 * v**2, # U-shape
lambda v: np.where(v > 0.5, 1.0, 0.0), # threshold
lambda v: np.sin(2 * v), # wave
lambda v: 0 * v, # irrelevant feature
]
interaction = 0.5 * X[:, 0] * X[:, 1] # something an additive model cannot see
y = sum(f(X[:, j]) for j, f in enumerate(shapes)) + interaction + rng.normal(0, 0.3, n)
tr, va, te = np.split(rng.permutation(n), [4000, 5000])
scaler = StandardScaler().fit(X[tr])
Xs = scaler.transform(X).astype(np.float32)
y32 = y.astype(np.float32)
class AdditiveCurves(nn.Module):
"""y = bias + sum_j f_j(x_j); each f_j is one learnable B-spline."""
def __init__(self, n_features, n_coef=12):
super().__init__()
self.curves = tc.BSplineCurve(n_features, 1, knots_config=n_coef,
input_map=tc.maps.Real.clamp(scale=3.0)) # covers +/- 3 sd
self.sum = tc.Sum(dim=-2)
self.bias = nn.Parameter(torch.zeros(1))
def forward(self, x): # (B, F)
return self.sum(self.curves(x)).squeeze(-1) + self.bias # (B,)
def roughness(self):
c = self.curves.control_points # (F, C, 1)
return (c[:, 2:] - 2 * c[:, 1:-1] + c[:, :-2]).pow(2).sum()
def kan(n_features, hidden=8, n_coef=10):
m = tc.maps.Real.clamp(scale=3.0)
return nn.Sequential(
tc.BSplineCurve(n_features, hidden, knots_config=n_coef, input_map=m), tc.Sum(),
tc.BSplineCurve(hidden, 1, knots_config=n_coef, input_map=m), tc.Sum(),
nn.Flatten(0),
)
def mlp(n_features, hidden=64):
return nn.Sequential(nn.Linear(n_features, hidden), nn.ReLU(), nn.Linear(hidden, hidden),
nn.ReLU(), nn.Linear(hidden, 1), nn.Flatten(0))
def fit_torch(model, lam=0.0, epochs=200, lr=1e-2, batch=256):
opt = torch.optim.Adam(model.parameters(), lr=lr)
Xt, yt = torch.from_numpy(Xs[tr]), torch.from_numpy(y32[tr])
Xv, yv = torch.from_numpy(Xs[va]), torch.from_numpy(y32[va])
best, best_state = float("inf"), None
for _ in range(epochs):
perm = torch.randperm(len(Xt))
for i in range(0, len(Xt), batch):
b = perm[i:i + batch]
opt.zero_grad()
loss = (model(Xt[b]) - yt[b]).pow(2).mean()
if lam > 0:
loss = loss + lam * model.roughness()
loss.backward()
opt.step()
with torch.no_grad():
v = (model(Xv) - yv).pow(2).mean().item()
if v < best: # keep the best epoch on validation
best, best_state = v, {k: t.clone() for k, t in model.state_dict().items()}
model.load_state_dict(best_state)
return model
def rmse(pred):
return float(np.sqrt(np.mean((pred - y[te]) ** 2)))
def torch_pred(model):
with torch.no_grad():
return model(torch.from_numpy(Xs[te])).numpy()
rows = []
lin = LinearRegression().fit(Xs[tr], y[tr])
rows.append(("linear regression", F_ + 1, rmse(lin.predict(Xs[te]))))
gam = make_pipeline(SplineTransformer(n_knots=10, degree=3), RidgeCV(alphas=np.logspace(-3, 3, 13))).fit(Xs[tr], y[tr])
rows.append(("SplineTransformer + RidgeCV", gam[-1].coef_.size + 1, rmse(gam.predict(Xs[te]))))
add = fit_torch(AdditiveCurves(F_), lam=1e-3)
rows.append(("torchcurves additive", sum(p.numel() for p in add.parameters()), rmse(torch_pred(add))))
k = fit_torch(kan(F_))
rows.append(("torchcurves KAN (5-8-1)", sum(p.numel() for p in k.parameters()), rmse(torch_pred(k))))
torch.manual_seed(0)
m = fit_torch(mlp(F_), lr=3e-3)
rows.append(("MLP (64-64)", sum(p.numel() for p in m.parameters()), rmse(torch_pred(m))))
hgb = HistGradientBoostingRegressor(random_state=0).fit(Xs[tr], y[tr])
rows.append(("HistGradientBoosting", None, rmse(hgb.predict(Xs[te]))))
print(f"{'model':30} {'params':>7} {'test RMSE':>9}")
for name, p, r in rows:
print(f"{name:30} {p if p is not None else '-':>7} {r:>9.3f}")
print(f"{'noise floor':30} {'':>7} {0.3:>9.3f}")
# --- inspect the learned shape functions --------------------------------
torch.save(add.state_dict(), "additive.pt")
grid_raw = np.linspace(-2, 2, 5)
with torch.no_grad():
G = np.tile(scaler.mean_, (len(grid_raw), 1))
out = []
for j in range(F_):
Gj = G.copy(); Gj[:, j] = grid_raw
fj = add.curves(torch.from_numpy(scaler.transform(Gj).astype(np.float32)))[:, j, 0].numpy()
out.append(fj - fj[len(grid_raw) // 2]) # centre at x = 0 for reading
print("\nlearned f_j(x) - f_j(0) at x =", grid_raw.tolist())
names = ["tanh(2x)", "0.5x^2", "step>0.5", "sin(2x)", "none"]
for j in range(F_):
true = shapes[j](grid_raw) - shapes[j](0.0)
print(f" x{j} ({names[j]:9}) learned " + " ".join(f"{v:6.2f}" for v in out[j]))
print(f" {'':13} true " + " ".join(f"{v:6.2f}" for v in true))
Output:
model params test RMSE
linear regression 6 1.191
SplineTransformer + RidgeCV 61 0.603
torchcurves additive 61 0.600
torchcurves KAN (5-8-1) 480 0.471
MLP (64-64) 4609 0.341
HistGradientBoosting - 0.393
noise floor 0.300
learned f_j(x) - f_j(0) at x = [-2.0, -1.0, 0.0, 1.0, 2.0]
x0 (tanh(2x) ) learned -1.00 -1.01 0.00 0.97 1.01
true -1.00 -0.96 0.00 0.96 1.00
x1 (0.5x^2 ) learned 2.05 0.51 0.00 0.54 1.98
true 2.00 0.50 0.00 0.50 2.00
x2 (step>0.5 ) learned -0.01 0.01 0.00 1.06 0.89
true 0.00 0.00 0.00 1.00 1.00
x3 (sin(2x) ) learned 0.68 -0.88 0.00 0.95 -0.61
true 0.76 -0.91 0.00 0.91 -0.76
x4 (none ) learned 0.02 0.01 0.00 0.04 -0.01
true -0.00 -0.00 0.00 0.00 0.00
Wat de cijfers zeggen:
- Het additieve TorchCurves-model evenaart de spline-GAM van scikit-learn (0,600 tegenover 0,603, beide 61 parameters). Dezelfde modelklasse, een andere trainer. Als uw model puur additief is en op tabeldata werkt, is
SplineTransformervan scikit-learn plus een ridge-regressie eenvoudiger en sneller [8]. - Beide additieve modellen missen de interactie en blijven ruim boven de ruisvloer van 0,30. Dat is de eerlijke prijs van één leesbare curve per feature. Als de interactie ertoe doet, voeg haar dan expliciet toe (bijvoorbeeld een curve van het product, of een 2D-term) in plaats van de structuur los te laten.
- De KAN vindt een deel van de interactie (0,471) met 480 parameters verdeeld over 48 curves; hij is expressiever, maar laat zich niet meer lezen als één curve per feature.
- De MLP en gradient boosting winnen op nauwkeurigheid (0,341 en 0,393) en verliezen op leesbaarheid. Uw beslissing is aan welke kant van die lijn de use case moet zitten.
- De vormtabel reconstrueert de werkelijkheid: zo is f1 bij x = ±2 gelijk aan 2,05 en 1,98 tegenover een werkelijke 2,00, en blijft de irrelevante x4 binnen 0,04 van nul.
Waarom zou u een GAM überhaupt in PyTorch trainen? Omdat het dan een onderdeel van een groter model kan zijn: een additieve "verklaarbare" head naast een embeddingmodel, curves waarvan de coëfficiënten door een ander netwerk worden geproduceerd, een monotone curve in een prijsmodel, of continue embeddings van numerieke features binnen een transformer of factorisation machine, de use case waarop het eerdere onderzoek van de auteur zich richtte [6].
7. De coëfficiënten exporteren en inspecteren
Een auditeerbaar model is een model dat iemand anders opnieuw kan evalueren. Het onderstaande script bouwt de curvelaag opnieuw op, laadt de getrainde gewichten, schrijft knopen, graad, input map en coëfficiënten naar JSON, evalueert ze opnieuw met BSpline van SciPy op basis van alleen de JSON, en legt de laag vast met torch.export voor serving.
# s5_export.py
import json
import numpy as np
import torch
import torchcurves as tc
from scipy.interpolate import BSpline
# Rebuild the additive model's curve layer and load the trained weights.
curves = tc.BSplineCurve(5, 1, knots_config=12, input_map=tc.maps.Real.clamp(scale=3.0))
state = torch.load("additive.pt")
curves.load_state_dict({k.removeprefix("curves."): v for k, v in state.items()
if k.startswith("curves.")})
# 1. Export everything needed to re-evaluate the curves without PyTorch.
spec = {
"library": f"torchcurves {tc.__version__}",
"degree": curves.degree,
"knots": curves.knots.tolist(),
"input_map": {"type": "clamp", "scale": 3.0, "range": list(curves.parameter_range)},
"bias": state["bias"].item(),
"coefficients": curves.control_points[..., 0].detach().tolist(), # (features, C)
}
with open("curves.json", "w") as f:
json.dump(spec, f, indent=1)
print("exported", len(spec["coefficients"]), "curves x", len(spec["coefficients"][0]), "coefficients")
# 2. Re-evaluate with SciPy from the JSON alone and compare.
x = torch.linspace(-4, 4, 801).unsqueeze(1).repeat(1, 5) # includes out-of-range values
with torch.no_grad():
y_torch = curves(x)[..., 0].numpy()
lo, hi = spec["input_map"]["range"]
u = np.clip(x.numpy() / spec["input_map"]["scale"], lo, hi)
y_scipy = np.stack([BSpline(np.array(spec["knots"]), np.array(c), spec["degree"])(u[:, j])
for j, c in enumerate(spec["coefficients"])], axis=1)
print("max |torch - scipy| =", float(np.abs(y_torch - y_scipy).max()))
# 3. Can the layer be captured for serving?
try:
batch = torch.export.Dim("batch") # without this the batch size is fixed at 8
ep = torch.export.export(curves, (torch.zeros(8, 5),), dynamic_shapes={"u": {0: batch}})
print("torch.export: ok,", sum(1 for n in ep.graph.nodes if n.op == "call_function"), "ops")
except Exception as e:
print("torch.export failed:", type(e).__name__, str(e).splitlines()[0][:120])
with torch.no_grad():
diff = (ep.module()(x) - curves(x)).abs().max().item()
print("exported program matches eager:", diff == 0.0)
torch.export.save(ep, "curves.pt2") # load with torch.export.load(...).module()
Output:
exported 5 curves x 12 coefficients
max |torch - scipy| = 6.234304983365746e-07
torch.export: ok, 80 ops
exported program matches eager: True
De herevaluatie in SciPy komt overeen tot binnen 6,2 × 10-7 (afronding in float32), ook voor inputs voorbij ±3 standaarddeviaties, waar de clamp-map de curve vlak maakt. Dat JSON-bestand is nu het officiële model: klein genoeg om te beoordelen, te vergelijken in Git en bij te voegen aan een model-risk-document, en te evalueren in elke taal met een B-splineroutine.
Twee details over de export. Ten eerste specialiseert torch.export zich op de vormen van de voorbeeldinput: onze eerste poging zonder dynamic_shapes faalde tijdens runtime met Guard failed: u.size()[0] == 8 voor elke andere batchgrootte. Markeer de batchdimensie als dynamisch, zoals hierboven. Ten tweede werkt torch.jit.trace nog in PyTorch 2.15, maar toont het een deprecation-waarschuwing die torch.export aanbeveelt. ONNX-export hebben we niet getest.
8. Testen
Vier tests dekken af wat meestal misgaat: vormen en inputvalidatie, gradiënten (numeriek gecontroleerd met torch.autograd.gradcheck in float64), overeenstemming met SciPy, en de garantie van monotonie.
# test_curves.py
import numpy as np
import pytest
import torch
import torchcurves as tc
from scipy.interpolate import BSpline
def test_shapes():
c = tc.BSplineCurve(num_curves=3, dim=2, knots_config=8)
assert c(torch.rand(4, 3)).shape == (4, 3, 2)
with pytest.raises(ValueError):
c(torch.rand(4, 2)) # wrong number of curves
def test_gradients_bspline_and_legendre():
torch.manual_seed(0)
for curve in (tc.BSplineCurve(2, 1, knots_config=6),
tc.LegendreCurve(2, 1, degree=4)):
curve = curve.double()
u = (torch.rand(5, 2, dtype=torch.float64) * 1.8 - 0.9).requires_grad_()
assert torch.autograd.gradcheck(curve, (u,))
def test_matches_scipy():
c = tc.BSplineCurve(1, 1, knots_config=9, parameter_range=(0, 1), input_map="real.clamp")
x = torch.linspace(0, 1, 101).unsqueeze(1)
ref = BSpline(c.knots.numpy(), c.control_points[0, :, 0].detach().numpy(), c.degree)(x.numpy())
np.testing.assert_allclose(c(x).detach().numpy()[:, 0, 0], ref[:, 0], atol=1e-5)
def test_increasing_coefficients_give_increasing_curve():
basis = tc.BSplineBasis(knots_config=10, parameter_range=(0, 1), input_map="real.clamp")
coef = torch.cumsum(torch.rand(10), 0).view(1, 10, 1)
y = basis(torch.linspace(0, 1, 2001).unsqueeze(0), coef.expand(2001, -1, -1).contiguous())
assert torch.all(torch.diff(y.view(-1)) >= -1e-6)
.... [100%]
4 passed in 1.03s
Voeg daarbovenop tests voor uw eigen model toe: het verwachte teken of de verwachte richting van de curve van elke feature, grenzen aan randcoëfficiënten, en een golden JSON-export die niet zonder beoordeling mag veranderen.
9. In productie draaien
- Packaging. Pin
torchcurves,torchen Python in uw lockbestand; dit is een jonge 0.x-library en 0.3.0 had al breaking changes. Sla de libraryversie op in de geëxporteerde JSON, zoals ons script doet. - Containers. Een CPU-only wheel van PyTorch houdt images klein, en curvemodellen hebben voor inferentie zelden een GPU nodig. Voor het puur additieve geval kunt u PyTorch tijdens serving helemaal overslaan en de JSON evalueren met SciPy of een paar regels NumPy.
- CPU of GPU. De benchmarks van de auteur laten zien dat de library voor kleine batches en weinig curves trager is dan SciPy of NumPy, vanwege de overhead van Python, ruwweg gelijk aan EfficientKAN bij het trainen van een KAN, en sneller bij grotere batchgroottes en dimensies [1]. Meet op uw eigen vormen voordat u hardware kiest.
- Checkpoints. Gebruik
state_dict(). De knopenvector is een buffer en wordt dus samen met de gewichten opgeslagen; om knopen te wijzigen laadt u een state dict in plaats van de tensor te bewerken, zodat het gecachete parameterbereik wordt ververst [2]. - Monitoring. Bewaak de inputverdeling ten opzichte van het knopenbereik: het aandeel inputs voorbij de clamp-limieten is een directe maat voor hoe vaak het model vlak extrapoleert. Volg de kalibratie van monotone curves in de tijd, en alerteer als hertraining een randcoëfficiënt sterk verschuift.
- Beoordeling. Plot bij elke hertraining elke curve en vergelijk die met de vorige release. Een vormwijziging is een modelwijziging, ook als de nauwkeurigheidsmetric gelijk blijft.
Valkuilen en debuggen
ValueError: Input u must be a 2D tensor of shape (N, num_curves=...): u hebt een 1D-tensor of het verkeerde aantal kolommen doorgegeven. Gebruikx.view(-1, 1)voor één curve.TypeError: ... unexpected keyword argument 'num_control_points'of'normalize_fn': verzonnen argumenten of argumenten van vóór 0.3.0. Gebruikknots_configeninput_map.- Het aantal controlepunten moet groter zijn dan de graad: een kubische spline heeft minstens vier coëfficiënten nodig.
- Vlakke curve waar u detail verwachtte: uw data ligt buiten het knopenbereik, of de rational map heeft de knopen rond nul opeengehoopt. Plot de knopen in ruwe eenheden (sectie 4).
- Wilde waarden aan de randen: weinig datapunten bij de grens. Voeg een ruwheidspenalty toe of verklein het bereik.
- Verwarring over vormen bij
LegendreCurve.coefficients: die is (K, C, D), niet (C, K, D) zoalsBSplineCurve.control_points. - Traag trainen op zeer kleine batches: te verwachten door de overhead van Python; gebruik grotere batches of SciPy voor losse curves.
Hoe het zich verhoudt
| Tool | Wat het is | Trainbaar binnen PyTorch | Gebruik het wanneer |
|---|---|---|---|
| torchcurves | B-spline- en Legendre-curvelagen, basismodules, functionele API | Ja, inputs en coëfficiënten | Curves deel uitmaken van een groter PyTorch-model, of coëfficiënten uit een ander netwerk komen |
SciPy (make_smoothing_spline, BSpline) | Klassiek fitten en evalueren van splines | Nee | Eén curve, één keer gefit; referentie-evaluatie van geëxporteerde curves |
scikit-learn SplineTransformer + lineair model | Splinefeatures voor een model in GAM-stijl | Nee | Puur additieve modellen op tabeldata met standaardtools |
IsotonicRegression (scikit-learn) | Monotone fit met een trapfunctie | Nee | Snelle monotone kalibratie waar trappen acceptabel zijn |
| pykan, efficient-kan | KAN-implementaties | Ja | KAN-onderzoek; efficient-kan was de snelheidsbaseline van het paper [1][10] |
xitorch Interp1D, torch-interpol, torch-cubic-spline-grids | Differentieerbare interpolatie of splinerasters | Gedeeltelijk | Data interpoleren of dichte rasters leren, volgens de eigen vergelijking in de README van torchcurves |
| MLP, gradient boosting | Algemene learners | MLP ja | Nauwkeurigheid voorop staat, interacties ertoe doen, en uitleg achteraf mag |
De oorspronkelijke versie van onze blog vergeleek TorchCurves met NVIDIA Kaolin Wisp en Torch Lens Maker. Dat zijn differentieerbare libraries voor respectievelijk neural fields en geometrische optica, geen alternatieven voor het fitten van curves, dus die hebben we hier weggelaten.
Veelgestelde vragen
Is dit een vervanging voor gradient boosting? Nee. Op onze test met tabeldata waren boosting en een MLP nauwkeuriger. Curves zijn bedoeld voor situaties waarin leesbaarheid of een vormregel zwaarder weegt dan de laatste paar punten nauwkeurigheid, of waarin de curve een component van een neuraal model is.
Kan een curve een vector als output geven? Ja: dim bepaalt de outputdimensie. Een curve van een scalair naar een 16-dimensionale vector is een continue embedding van die scalair.
Kan ik mijn eigen knopen instellen? Ja: geef een 1D-tensor door als knots_config, dan wordt het aantal controlepunten afgeleid. U kunt dat niet combineren met parameter_range.
Draait het op een GPU? Ja, het is puur PyTorch, dus .to("cuda") werkt; de benchmarks in het paper omvatten het trainen van een KAN op een GPU [1]. Of het sneller is dan de CPU, hangt af van de batchgrootte en het aantal curves.
Hoeveel coëfficiënten moet ik gebruiken? Begin met 8 tot 12 per input met een kleine ruwheidspenalty en tune op validatiedata. Met een penalty kost ruimhartigheid weinig.
Is de API in het paper dezelfde als in het package? Grotendeels. Het paper (v1) noemt real.arctan als standaard input map en vermeldt een argument num_knots; de code in 0.3.4 gebruikt standaard "real.rational" en gebruikt knots_config. Vertrouw op de geïnstalleerde broncode en de documentatie voor uw versie [11].
Als u interpreteerbare modellen in een productiepipeline inbouwt en hulp wilt bij het versioneren, testen en monitoren ervan, zie dan onze MLOps-installatiedienst.
Referenties
- A. Shtoff, "TorchCurves: Differentiable Parametric Curves", arXiv:2611.14516v1, 10 november 2026
- alexshtf/torchcurves op GitHub: README, broncode (v0.3.4), voorbeeldnotebooks en releasenotes
- torchcurves op PyPI
- P. H. C. Eilers en B. D. Marx, "Flexible smoothing with B-splines and penalties", Statistical Science 11(2), 1996
- Z. Liu et al., "KAN: Kolmogorov-Arnold Networks", ICLR 2025
- A. Shtoff, E. Abboud, R. Stram, O. Somekh, "Function Basis Encoding of Numerical Features in Factorization Machines", TMLR 2024
- R. Agarwal et al., "Neural Additive Models: Interpretable Machine Learning with Neural Nets", NeurIPS 2021
- scikit-learn: SplineTransformer
- SciPy: make_smoothing_spline
- efficient-kan: een KAN-implementatie in puur PyTorch
- documentatie van torchcurves
PyTorch is een handelsmerk van The Linux Foundation. Andere namen zijn eigendom van hun respectieve eigenaars. Dit artikel is onafhankelijk en wordt niet onderschreven door de auteurs van de besproken libraries. De code in deze technote wordt als voorbeeld gegeven; controleer haar aan de hand van de actuele documentatie van de library voordat u erop vertrouwt.