Ein praxisorientierter Leitfaden zu TorchCurves, der PyTorch-Bibliothek, die B-Spline- und Legendre-Kurven zu trainierbaren Schichten macht. Sie installieren die Bibliothek, passen eine Kurve an, wählen Basis und Knotenzahl, bauen eine monotone Kalibrierungskurve und ein additives Modell auf tabellarischen Daten, vergleichen sie mit scikit-learn, SciPy, einem KAN und einem MLP, exportieren die Koeffizienten, damit sie ohne PyTorch geprüft werden können, und testen das Ganze. Jede Ausgabe unten stammt aus unserem eigenen Durchlauf.
torchcurves (0.3.4, Apache-2.0, Python 3.12+, PyTorch 2.9+) stellt Ihnen BSplineCurve, LegendreCurve, BSplineBasis und Sum bereit. Eingaben der Form (batch, curves) werden zu Punkten der Form (batch, curves, dim), mit Gradienten sowohl zu den Eingaben als auch zu den Koeffizienten. Verwenden Sie standardmäßig B-Splines mit 8 bis 12 Koeffizienten und einer Strafe auf zweite Differenzen; erzwingen Sie monotone Formen konstruktionsbedingt; standardisieren Sie Eingaben und wählen Sie die Eingabeabbildung bewusst; exportieren Sie Knoten, Koeffizienten und Abbildung nach JSON und prüfen Sie sie gegen SciPy. Für eine einzelne, eigenständige Kurve ist SciPy schneller und passt besser; TorchCurves lohnt sich, wenn die Kurve innerhalb eines PyTorch-Modells lebt.
Diese Technote begleitet unseren Blogbeitrag Differenzierbare Kurven in PyTorch: kleine, prüfbare Modelle mit TorchCurves, der das Warum für ein breiteres Publikum behandelt. Die API-Details stammen aus dem torchcurves-Quellcode in Version 0.3.4 und dem Paper seines Autors Alex Shtoff [1][2]. Stand der Fakten: 16. November 2026.
Für wen dies gedacht ist und was Sie bauen
Für wen. Python-Entwickler und Data Scientists, die grundlegendes PyTorch beherrschen (Module, Optimierer, backward()) und Modelle möchten, deren Verhalten pro Eingabe sich plotten, einschränken und prüfen lässt. Spline-Theorie wird nicht vorausgesetzt; wir erklären unterwegs, was Sie brauchen.
Was Sie bauen, in sechs kurzen Skripten und einer Testdatei:
- Ein Hello-World, das die Tensor-Formen zeigt.
- Eine einzelne angepasste Kurve, mit einem Vergleich von Knotenzahlen, B-Spline gegen Legendre und SciPys Glättungsspline.
- Eine monotone Kurve zur Wahrscheinlichkeitskalibrierung, verglichen mit einem unbeschränkten Spline und isotonischer Regression.
- Ein additives Modell (eine Kurve pro Merkmal) und ein kleines KAN auf tabellarischen Daten, verglichen mit linearer Regression, einem Spline-GAM aus scikit-learn, Gradient Boosting und einem MLP.
- Einen Export der trainierten Kurven nach JSON, neu ausgewertet in SciPy, sowie ein
torch.export-Programm für das Serving. - Eine pytest-Datei, die Formen, Gradienten, Übereinstimmung mit SciPy und Monotonie prüft.
Voraussetzungen. Python 3.12 oder neuer, etwa 1 GB Speicherplatz für PyTorch und ein beliebiger aktueller Laptop. Alles hier läuft auf der CPU in Sekunden bis wenigen Minuten. Wir haben Python 3.13, PyTorch 2.15.0, torchcurves 0.3.4, SciPy 1.18.1, scikit-learn 1.9.1 und NumPy 2.5.4 auf einem Mac mit Apple Silicon verwendet.
1. Installation
Verwenden Sie eine frische virtuelle Umgebung. Unter Linux installieren Sie zuerst das reine CPU-Wheel von PyTorch, sofern Sie kein CUDA benötigen; es ist um ein Mehrfaches kleiner. Unter macOS ist das Standard-Wheel bereits ein CPU-Wheel (mit Apples MPS-Backend).
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 hat eine einzige Abhängigkeit, torch>=2.9.0, und deklariert requires_python >= 3.12 [3]. Meldet pip, dass keine passende Distribution gefunden wurde, prüfen Sie zuerst Ihre Python-Version.
2. Hallo, Kurve: die Formen, die Sie sich merken müssen
Jedes Kurvenmodul nimmt eine 2-D-Eingabe der Form (B, C) entgegen: B Samples, eine Spalte pro Kurve. Es gibt (B, C, D) zurück: einen D-dimensionalen Punkt pro Sample und Kurve. Die Koeffizienten der Kurven liegen in control_points mit der Form (C, K, D), wobei K die Anzahl der Koeffizienten pro Kurve ist.
# 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)
Ausgabe:
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
Drei Dinge fallen auf. knots_config=8 bedeutet acht Kontrollpunkte (Koeffizienten) pro Kurve, nicht acht Knoten: Ein kubischer Spline mit acht Koeffizienten hat 12 Knoten, davon vier an jedem Ende wiederholt, damit sich die Kurve an den Rändern gutartig verhält. Die Knoten reichen standardmäßig von -1 bis 1. Und die Gradienten fließen über einen gewöhnlichen backward()-Aufruf zu den Koeffizienten, weil die Bibliothek für B-Splines eine eigene Autograd-Funktion implementiert [2].
Wenn Sie BSplineCurve(num_control_points=8, degree=3, dim=1) in einem Blogbeitrag gesehen haben (auch in einer früheren Version unseres eigenen), ist das für jede veröffentlichte Version falsch: Es gibt kein Argument num_control_points, und num_curves ist erforderlich. Die tatsächliche Signatur lautet 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) nimmt statt Knoten einen Grad entgegen; beachten Sie, dass es seine coefficients als (K, C, D) speichert, mit der Koeffizientenachse zuerst.
3. Eine Kurve anpassen sowie Basis und Knotenzahl wählen
Die erste echte Aufgabe: ein verrauschtes 1-D-Signal mit glattem Trend und einem scharfen Steigungswechsel bei x = 0,7 anpassen. Wir probieren B-Splines mit 6 bis 48 Koeffizienten, einen stark überdimensionierten Spline mit Rauheitsstrafe, Legendre-Polynome passender Größe und SciPys make_smoothing_spline, das sein Glättungsniveau per generalisierter Kreuzvalidierung selbst wählt [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")
Ausgabe (val RMSE ist der Fehler gegenüber zurückgehaltenen verrauschten Punkten, 0,200 ist also die Untergrenze; „vs truth“ ist der Fehler gegenüber der rauschfreien Funktion):
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
So lesen Sie das Ergebnis:
- Zu wenige Koeffizienten führen zu Underfitting (6 Koeffizienten, Fehler gegenüber der Wahrheit 0,110). Zwölf bis 24 sind hier der optimale Bereich.
- Zu viele führen zu Overfitting (48 Koeffizienten, 0,071), und eine kleine Strafe auf zweite Differenzen benachbarter Koeffizienten behebt das (48 mit Strafe, 0,044). Das ist das P-Spline-Rezept von Eilers und Marx: großzügig Knoten verwenden und die Glattheit über eine Strafe steuern [4]. Dadurch wird die Knotenzahl deutlich weniger kritisch.
- B-Spline und Legendre liegen bei gleicher Größe nah beieinander auf diesem Signal. Der Unterschied zeigt sich im Verhalten, nicht im Score: Ein B-Spline-Koeffizient verändert die Kurve lokal, ein Legendre-Koeffizient verändert sie überall (Abbildung unten). B-Splines kommen daher besser mit Knicken und Nebenbedingungen zurecht, Legendre-Reihen sind für wirklich glatte Funktionen glatter und kompakter.
- SciPy gewinnt als eigenständiger Glätter (0,027). Es löst das bestrafte Kleinste-Quadrate-Problem exakt und wählt die Strafe automatisch; Gradientenabstieg mit fester Lernrate kommt nah heran, aber nicht ganz. Ist eine Kurve Ihr gesamtes Modell, verwenden Sie SciPy. Verwenden Sie TorchCurves, wenn die Kurve eine Schicht in etwas Größerem ist.
Faustregeln, die sich in unseren Durchläufen bewährt haben: Beginnen Sie mit kubischen B-Splines (der Standard degree=3) und 8 bis 12 Koeffizienten pro Eingabe; gehen Sie über 20 hinaus, ergänzen Sie eine Rauheitsstrafe; wählen Sie die endgültige Größe anhand von Validierungsdaten. Greifen Sie zu Legendre, wenn die Funktion sehr glatt ist und Sie möglichst wenige Parameter wünschen, und verwenden Sie bei hohen Graden checkpoint_segments, um im Backward-Pass Rechenzeit gegen Speicher zu tauschen [2].
4. Eingabeabbildungen: wo Ihre Knoten tatsächlich landen
Kurven leben auf einem beschränkten Intervall (standardmäßig -1 bis 1), Merkmale dagegen nicht. Jedes Modul wendet daher zuerst eine Eingabeabbildung an. Die eingebauten Optionen sind "real.rational" (der Modulstandard in 0.3.4, x / sqrt(s² + x²)), "real.arctan", "real.clamp" (x / s auf das Intervall beschneiden) sowie "nonneg.rational" und "nonneg.arctan" für nicht-negative Eingaben. Für eine eigene Skalierung verwenden Sie Objekte wie tc.maps.Real.clamp(scale=3.0) oder übergeben ein beliebiges Callable f(x, out_min, out_max) [2].
Praktische Hinweise:
- Erst standardisieren, dann wählen. Für annähernd normalverteilte Merkmale liefert
tc.maps.Real.clamp(scale=3.0)gleichmäßige Knoten über ±3 Standardabweichungen und eine flache Extrapolation darüber hinaus, was leicht zu erklären ist. - Verwenden Sie bei schweren Rändern die rationale oder die Arkustangens-Abbildung, wenn Sie weit draußen etwas Auflösung wünschen und akzeptieren, dass diese grob ist.
- Für Eingaben, die bereits in [0, 1] liegen, setzen Sie
parameter_range=(0, 1)mit"real.clamp", damit die Knoten genau auf Ihrem Datenbereich liegen, wie in den Skripten oben. - Das Release 0.3.0 hat die alten Argumente
normalize_fnundnormalization_scaledurchinput_mapersetzt [2]. Für 0.2.x geschriebener Code schlägt fehl.
5. Eine monotone Kalibrierungskurve
Ein häufiger Bedarf in der Produktion: einen rohen Modell-Score in eine Wahrscheinlichkeit umwandeln, die mit steigendem Score niemals sinkt. B-Splines machen das einfach, denn ein Spline mit aufsteigenden Koeffizienten ist selbst steigend [2]. Wir parametrisieren die Koeffizienten als ersten Wert plus kumulative Summe positiver Schritte (softplus hält sie positiv) und übergeben sie an eine BSplineBasis. Zum Vergleich dienen ein unbeschränkter Spline gleicher Größe und die isotonische Regression von 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:]}")
Ausgabe:
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]
Der unbeschränkte Spline schwankt: Er fällt in 140 der 1.000 Gitterschritte, was Sie nicht als Preis- oder Risikokurve ausliefern können. Der monotone Spline fällt konstruktionsbedingt nie und ist auf zurückgehaltenen Daten sogar etwas besser. Die isotonische Regression ist ebenfalls monoton, aber hier eine Treppenfunktion mit 37 Stufen; der Spline ist glatt und hat 20 Zahlen, die Sie ausgeben können.
Die letzten beiden Zeilen zeigen eine Falle, die man kennen sollte. Ohne Strafe driftete der letzte Koeffizient auf der Logit-Skala auf 32,6: Nur wenige Trainingspunkte liegen nahe einem Score von 1, und nichts hindert den Randkoeffizienten daran, davonzulaufen. Eine Rauheitsstrafe von 0,001 brachte ihn ohne Genauigkeitsverlust auf 5,1. Prüfen Sie immer die Randkoeffizienten.
README und Beispiel-Notebook der Bibliothek nutzen denselben Trick in reichhaltigerer Form: Ein Encoder-Netz bildet Auktionsmerkmale auf steigende Koeffizienten ab, und jedes Sample erhält seine eigene Kurve der Gewinnwahrscheinlichkeit über dem Gebot [2]. Das ist das dritte Muster in der Abbildung zu den Tensor-Formen.
6. Ein additives Modell und ein KAN auf tabellarischen Daten
Nun ein tabellarisches Problem. Wir erzeugen fünf standardisierte Merkmale mit bekannten Effekten (ein sättigendes tanh, eine U-Form, eine Stufe, eine Welle und ein Merkmal ohne Effekt) plus eine verborgene Interaktion zwischen den ersten beiden sowie gaußsches Rauschen mit Standardabweichung 0,3. Das additive Modell ist eine BSplineCurve mit fünf Kurven und je 12 Koeffizienten, gefolgt von tc.Sum: Vorhersage = Bias + f0(x0) + ... + f4(x4). Das ist ein generalisiertes additives Modell (GAM), trainiert per Gradientenabstieg; das Neural Additive Model von Agarwal et al. folgt derselben Idee mit kleinen Netzen statt Splines [7].
Das KAN stapelt zwei Kurvenschichten mit jeweils einer Summe danach, wie im README der Bibliothek; Kolmogorov-Arnold-Netze setzen eine lernbare 1-D-Funktion auf jede Kante des Netzes [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))
Ausgabe:
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
Was die Zahlen sagen:
- Das additive TorchCurves-Modell entspricht dem Spline-GAM von scikit-learn (0,600 gegenüber 0,603, beide mit 61 Parametern). Gleiche Modellklasse, anderer Trainer. Ist Ihr Modell rein additiv und tabellarisch, ist
SplineTransformervon scikit-learn plus Ridge-Regression einfacher und schneller [8]. - Beide additiven Modelle verfehlen die Interaktion und liegen deutlich über der Rauschgrenze von 0,30. Das ist der ehrliche Preis einer lesbaren Kurve pro Merkmal. Ist die Interaktion wichtig, fügen Sie sie explizit hinzu (etwa eine Kurve des Produkts oder einen 2-D-Term), statt die Struktur aufzugeben.
- Das KAN findet einen Teil der Interaktion (0,471) mit 480 Parametern über 48 Kurven; es ist ausdrucksstärker, liest sich aber nicht mehr als eine Kurve pro Merkmal.
- MLP und Gradient Boosting gewinnen bei der Genauigkeit (0,341 und 0,393) und verlieren bei der Lesbarkeit. Sie entscheiden, auf welcher Seite dieser Linie der Anwendungsfall liegen muss.
- Die Formtabelle stellt die Wahrheit wieder her: So liegt f1 bei x = ±2 bei 2,05 und 1,98 gegenüber wahren 2,00, und das irrelevante x4 bleibt innerhalb von 0,04 um null.
Warum überhaupt ein GAM in PyTorch trainieren? Weil es dann Teil eines größeren Modells sein kann: ein additiver „erklärbarer“ Kopf neben einem Embedding-Modell, Kurven, deren Koeffizienten von einem anderen Netz erzeugt werden, eine monotone Kurve in einem Preismodell oder kontinuierliche Embeddings numerischer Merkmale innerhalb eines Transformers oder einer Factorization Machine, worauf die frühere Forschung des Autors abzielte [6].
7. Die Koeffizienten exportieren und prüfen
Ein prüfbares Modell ist eines, das jemand anderes neu auswerten kann. Das Skript unten baut die Kurvenschicht neu auf, lädt die trainierten Gewichte, schreibt Knoten, Grad, Eingabeabbildung und Koeffizienten nach JSON, wertet sie allein anhand des JSON mit SciPys BSpline neu aus und erfasst die Schicht mit torch.export für das 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()
Ausgabe:
exported 5 curves x 12 coefficients
max |torch - scipy| = 6.234304983365746e-07
torch.export: ok, 80 ops
exported program matches eager: True
Die Neuauswertung mit SciPy stimmt bis auf 6,2 × 10-7 überein (float32-Rundung), auch für Eingaben jenseits von ±3 Standardabweichungen, wo die Clamp-Abbildung die Kurve abflacht. Diese JSON-Datei ist nun das maßgebliche Modell: klein genug, um sie zu prüfen, in Git zu vergleichen und einem Modellrisiko-Dokument beizufügen, und in jeder Sprache mit einer B-Spline-Routine auswertbar.
Zwei Details zum Export. Erstens spezialisiert sich torch.export auf die Formen der Beispieleingabe: Unser erster Versuch ohne dynamic_shapes schlug zur Laufzeit für jede andere Batch-Größe mit Guard failed: u.size()[0] == 8 fehl. Markieren Sie die Batch-Dimension als dynamisch, wie oben. Zweitens funktioniert torch.jit.trace in PyTorch 2.15 noch, gibt aber eine Deprecation-Warnung aus, die torch.export empfiehlt. Den ONNX-Export haben wir nicht getestet.
8. Testen
Vier Tests decken ab, was üblicherweise schiefgeht: Formen und Eingabevalidierung, Gradienten (numerisch geprüft mit torch.autograd.gradcheck in float64), Übereinstimmung mit SciPy und die Monotoniegarantie.
# 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
Ergänzen Sie Tests für Ihr eigenes Modell: das erwartete Vorzeichen bzw. die erwartete Richtung der Kurve jedes Merkmals, Grenzen für Randkoeffizienten und einen Golden-JSON-Export, der sich nicht ohne Prüfung ändern darf.
9. Betrieb in der Produktion
- Paketierung. Pinnen Sie
torchcurves,torchund Python in Ihrer Lock-Datei; dies ist eine junge 0.x-Bibliothek, und 0.3.0 brachte bereits Breaking Changes. Speichern Sie die Bibliotheksversion im exportierten JSON, wie es unser Skript tut. - Container. Ein reines CPU-Wheel von PyTorch hält Images klein, und Kurvenmodelle benötigen für die Inferenz selten eine GPU. Im rein additiven Fall können Sie PyTorch beim Serving ganz weglassen und das JSON mit SciPy oder ein paar Zeilen NumPy auswerten.
- CPU oder GPU. Die Benchmarks des Autors zeigen, dass die Bibliothek bei kleinen Batches und wenigen Kurven wegen des Python-Overheads langsamer ist als SciPy oder NumPy, beim KAN-Training etwa gleichauf mit EfficientKAN liegt und bei größeren Batch-Größen und Dimensionen schneller ist [1]. Messen Sie mit Ihren eigenen Formen, bevor Sie Hardware wählen.
- Checkpoints. Verwenden Sie
state_dict(). Der Knotenvektor ist ein Buffer und wird daher mit den Gewichten gespeichert; um Knoten zu ändern, laden Sie ein State Dict, statt den Tensor zu bearbeiten, damit der zwischengespeicherte Parameterbereich aktualisiert wird [2]. - Monitoring. Beobachten Sie die Eingabeverteilung im Verhältnis zum Knotenbereich: Der Anteil der Eingaben jenseits der Clamp-Grenzen ist ein direktes Maß dafür, wie oft das Modell flach extrapoliert. Verfolgen Sie die Kalibrierung monotoner Kurven über die Zeit und lösen Sie einen Alarm aus, wenn ein erneutes Training einen Randkoeffizienten stark verschiebt.
- Review. Plotten Sie bei jedem erneuten Training jede Kurve und vergleichen Sie sie mit dem vorherigen Release. Eine Formänderung ist eine Modelländerung, auch wenn die Genauigkeitsmetrik unverändert bleibt.
Fallstricke und Fehlersuche
ValueError: Input u must be a 2D tensor of shape (N, num_curves=...): Sie haben einen 1-D-Tensor oder die falsche Spaltenzahl übergeben. Verwenden Siex.view(-1, 1)für eine einzelne Kurve.TypeError: ... unexpected keyword argument 'num_control_points'oder'normalize_fn': erfundene Argumente oder solche aus der Zeit vor 0.3.0. Verwenden Sieknots_configundinput_map.- Die Anzahl der Kontrollpunkte muss den Grad übersteigen: Ein kubischer Spline benötigt mindestens vier Koeffizienten.
- Flache Kurve, wo Sie Details erwartet haben: Ihre Daten liegen außerhalb des Knotenbereichs, oder die rationale Abbildung hat die Knoten nahe null gebündelt. Plotten Sie die Knoten in Roheinheiten (Abschnitt 4).
- Extreme Werte an den Rändern: wenige Datenpunkte nahe der Grenze. Ergänzen Sie eine Rauheitsstrafe oder verkleinern Sie den Bereich.
- Verwechslung der Formen bei
LegendreCurve.coefficients: Es ist (K, C, D), nicht (C, K, D) wie beiBSplineCurve.control_points. - Langsames Training bei winzigen Batches: wegen des Python-Overheads zu erwarten; verwenden Sie größere Batches oder SciPy für einzelne Kurven.
Wie es im Vergleich abschneidet
| Werkzeug | Was es ist | Innerhalb von PyTorch trainierbar | Verwenden, wenn |
|---|---|---|---|
| torchcurves | B-Spline- und Legendre-Kurvenschichten, Basismodule, funktionale API | Ja, Eingaben und Koeffizienten | Kurven Teil eines größeren PyTorch-Modells sind oder Koeffizienten aus einem anderen Netz stammen |
SciPy (make_smoothing_spline, BSpline) | Klassische Spline-Anpassung und -Auswertung | Nein | Eine Kurve, einmal angepasst; Referenzauswertung exportierter Kurven |
scikit-learn SplineTransformer + lineares Modell | Spline-Merkmale für ein Modell im GAM-Stil | Nein | Rein additive tabellarische Modelle mit Standardwerkzeugen |
IsotonicRegression (scikit-learn) | Monotone Anpassung mit Treppenfunktion | Nein | Schnelle monotone Kalibrierung, wenn Stufen akzeptabel sind |
| pykan, efficient-kan | KAN-Implementierungen | Ja | KAN-Forschung; efficient-kan war die Geschwindigkeits-Baseline des Papers [1][10] |
xitorch Interp1D, torch-interpol, torch-cubic-spline-grids | Differenzierbare Interpolation oder Spline-Gitter | Teilweise | Daten interpoliert oder dichte Gitter gelernt werden sollen, laut dem Vergleich im README von torchcurves selbst |
| MLP, Gradient Boosting | Universelle Lernverfahren | MLP ja | Genauigkeit an erster Stelle steht, Interaktionen wichtig sind und die Erklärung nachträglich erfolgen kann |
Die ursprüngliche Fassung unseres Blogbeitrags verglich TorchCurves mit NVIDIA Kaolin Wisp und Torch Lens Maker. Das sind differenzierbare Bibliotheken für Neural Fields bzw. geometrische Optik, keine Alternativen zur Kurvenanpassung; deshalb haben wir sie hier weggelassen.
FAQ
Ist das ein Ersatz für Gradient Boosting? Nein. In unserem tabellarischen Test waren Boosting und ein MLP genauer. Kurven sind für Fälle gedacht, in denen Lesbarkeit oder eine Formregel wichtiger ist als die letzten Prozentpunkte Genauigkeit, oder in denen die Kurve eine Komponente eines neuronalen Modells ist.
Kann eine Kurve einen Vektor ausgeben? Ja: dim legt die Ausgabedimension fest. Eine Kurve von einem Skalar auf einen 16-dimensionalen Vektor ist ein kontinuierliches Embedding dieses Skalars.
Kann ich meine eigenen Knoten festlegen? Ja: Übergeben Sie einen 1-D-Tensor als knots_config, dann wird die Anzahl der Kontrollpunkte abgeleitet. Mit parameter_range lässt sich das nicht kombinieren.
Läuft es auf der GPU? Ja, es ist reines PyTorch, daher funktioniert .to("cuda"); die Benchmarks des Papers umfassen KAN-Training auf der GPU [1]. Ob es schneller ist als die CPU, hängt von der Batch-Größe und der Anzahl der Kurven ab.
Wie viele Koeffizienten sollte ich verwenden? Beginnen Sie mit 8 bis 12 pro Eingabe und einer kleinen Rauheitsstrafe und optimieren Sie anhand von Validierungsdaten. Mit Strafe kostet Großzügigkeit wenig.
Ist die API im Paper dieselbe wie im Paket? Größtenteils. Das Paper (v1) nennt real.arctan als Standard-Eingabeabbildung und erwähnt ein Argument num_knots; der Code in 0.3.4 verwendet standardmäßig "real.rational" und nutzt knots_config. Verlassen Sie sich auf den installierten Quellcode und die Dokumentation Ihrer Version [11].
Wenn Sie interpretierbare Modelle in eine Produktionspipeline einbauen und Unterstützung bei Versionierung, Tests und Monitoring wünschen, sehen Sie sich unseren MLOps-Einrichtungsservice an.
Literatur
- A. Shtoff, „TorchCurves: Differentiable Parametric Curves“, arXiv:2611.14516v1, 10. November 2026
- alexshtf/torchcurves auf GitHub: README, Quellcode (v0.3.4), Beispiel-Notebooks und Release Notes
- torchcurves auf PyPI
- P. H. C. Eilers und 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: eine KAN-Implementierung in reinem PyTorch
- torchcurves-Dokumentation
PyTorch ist eine Marke der Linux Foundation. Andere Namen sind Eigentum ihrer jeweiligen Inhaber. Dieser Artikel ist unabhängig und wird von den Autoren der besprochenen Bibliotheken nicht unterstützt. Der Code in dieser Technote dient als Beispiel; prüfen Sie ihn anhand der aktuellen Bibliotheksdokumentation, bevor Sie sich darauf verlassen.