Un guide pratique de TorchCurves, la bibliothèque PyTorch qui transforme les courbes B-spline et de Legendre en couches entraînables. Vous allez l’installer, ajuster une courbe, choisir une base et un nombre de nœuds, construire une courbe de calibration monotone et un modèle additif sur des données tabulaires, les comparer avec scikit-learn, SciPy, un KAN et un MLP, exporter les coefficients pour qu’ils puissent être audités sans PyTorch, et tester l’ensemble. Toutes les sorties ci-dessous proviennent de notre propre exécution.
torchcurves (0.3.4, Apache-2.0, Python 3.12+, PyTorch 2.9+) vous fournit BSplineCurve, LegendreCurve, BSplineBasis et Sum. Des entrées de forme (batch, curves) deviennent des points de forme (batch, curves, dim), avec des gradients vers les entrées comme vers les coefficients. Utilisez par défaut des B-splines avec 8 à 12 coefficients et une pénalité sur les différences secondes ; imposez les formes monotones par construction ; standardisez les entrées et choisissez délibérément l’application d’entrée ; exportez les nœuds, les coefficients et l’application d’entrée en JSON et vérifiez-les avec SciPy. Pour une courbe unique et autonome, SciPy est plus rapide et ajuste mieux ; TorchCurves trouve sa place lorsque la courbe fait partie d’un modèle PyTorch.
Cette note technique accompagne notre article de blog Differentiable Curves in PyTorch: Small, Auditable Models with TorchCurves, qui explique le « pourquoi » à un public plus large. Les détails de l’API proviennent du code source de torchcurves en version 0.3.4 et de l’article de son auteur, Alex Shtoff [1][2]. Les faits sont à jour au 16 novembre 2026.
À qui s’adresse ce guide, ce que vous allez construire
À qui. Aux développeurs Python et data scientists qui connaissent les bases de PyTorch (modules, optimiseurs, backward()) et qui veulent des modèles dont le comportement pour chaque entrée peut être tracé, contraint et relu. Aucune connaissance de la théorie des splines n’est supposée ; nous expliquons ce dont vous avez besoin au fur et à mesure.
Ce que vous allez construire, en six courts scripts et un fichier de test :
- Un « hello world » qui montre les formes des tenseurs.
- Une courbe ajustée, en comparant les nombres de nœuds, B-spline face à Legendre, et la spline de lissage de SciPy.
- Une courbe monotone de calibration de probabilités, face à une spline non contrainte et à la régression isotonique.
- Un modèle additif (une courbe par variable) et un petit KAN sur des données tabulaires, face à la régression linéaire, un GAM à splines de scikit-learn, le gradient boosting et un MLP.
- Un export des courbes entraînées en JSON, réévaluées dans SciPy, plus un programme
torch.exportpour le service en production. - Un fichier pytest qui vérifie les formes, les gradients, la concordance avec SciPy et la monotonie.
Prérequis. Python 3.12 ou plus récent, environ 1 GB d’espace disque pour PyTorch, et n’importe quel ordinateur portable récent. Tout ce qui suit s’exécute sur CPU en quelques secondes à quelques minutes. Nous avons utilisé Python 3.13, PyTorch 2.15.0, torchcurves 0.3.4, SciPy 1.18.1, scikit-learn 1.9.1 et NumPy 2.5.4 sur un Mac Apple silicon.
1. Installation
Utilisez un environnement virtuel neuf. Sous Linux, installez d’abord la wheel PyTorch CPU uniquement, sauf si vous avez besoin de CUDA ; elle est plusieurs fois plus petite. Sous macOS, la wheel par défaut est déjà en version CPU (avec le backend MPS d’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 a une seule dépendance, torch>=2.9.0, et déclare requires_python >= 3.12 [3]. Si pip indique qu’aucune distribution ne correspond, vérifiez d’abord votre version de Python.
2. Hello, curve : les formes à retenir
Chaque module de courbe prend une entrée 2-D de forme (B, C) : B échantillons, une colonne par courbe. Il renvoie (B, C, D) : un point de dimension D par échantillon et par courbe. Les coefficients des courbes se trouvent dans control_points avec la forme (C, K, D), où K est le nombre de coefficients par courbe.
# 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)
Sortie :
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
Trois points à remarquer. knots_config=8 signifie huit points de contrôle (coefficients) par courbe, et non huit nœuds : une spline cubique à huit coefficients a 12 nœuds, dont quatre répétés à chaque extrémité pour que la courbe se comporte bien aux bornes. Les nœuds couvrent par défaut l’intervalle de -1 à 1. Enfin, les gradients remontent jusqu’aux coefficients par un simple appel à backward(), car la bibliothèque implémente une fonction autograd personnalisée pour les B-splines [2].
Si vous avez vu BSplineCurve(num_control_points=8, degree=3, dim=1) dans un article de blog (y compris une version antérieure du nôtre), c’est faux pour toutes les versions publiées : il n’existe pas d’argument num_control_points et num_curves est obligatoire. La véritable signature est 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) prend un degré au lieu de nœuds ; notez qu’il stocke ses coefficients sous la forme (K, C, D), avec l’axe des coefficients en premier.
3. Ajuster une courbe, choisir une base et un nombre de nœuds
Le premier vrai travail : ajuster un signal 1-D bruité présentant une tendance lisse et un brusque changement de pente en x = 0.7. Nous essayons des B-splines de 6 à 48 coefficients, une spline fortement surdimensionnée avec une pénalité de rugosité, des polynômes de Legendre de taille équivalente, et la fonction make_smoothing_spline de SciPy, qui choisit elle-même son niveau de lissage par validation croisée généralisée [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")
Sortie (val RMSE est l’erreur sur des points bruités mis de côté, donc 0.200 est le plancher ; « vs truth » est l’erreur par rapport à la fonction sans bruit) :
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
Comment la lire :
- Trop peu de coefficients sous-ajustent (6 coefficients, erreur par rapport à la vérité de 0.110). Entre 12 et 24 est l’optimum ici.
- Trop de coefficients surajustent (48 coefficients, 0.071), et une petite pénalité sur les différences secondes des coefficients voisins corrige le problème (48 avec pénalité, 0.044). C’est la recette des P-splines d’Eilers et Marx : utiliser des nœuds en nombre généreux et laisser une pénalité contrôler le lissage [4]. Le nombre de nœuds devient ainsi beaucoup moins critique.
- B-spline et Legendre sont proches à taille égale sur ce signal. La différence apparaît dans le comportement, pas dans le score : un coefficient de B-spline déplace la courbe localement, un coefficient de Legendre la déplace partout (figure ci-dessous) ; les B-splines gèrent donc mieux les cassures et les contraintes, et les séries de Legendre sont plus lisses et plus compactes pour les fonctions véritablement lisses.
- SciPy l’emporte comme lisseur autonome (0.027). Il résout exactement le problème des moindres carrés pénalisés et choisit automatiquement la pénalité ; la descente de gradient à taux d’apprentissage fixe s’en approche sans l’atteindre. Si une seule courbe constitue tout votre modèle, utilisez SciPy. Utilisez TorchCurves lorsque la courbe est une couche d’un ensemble plus vaste.
Règles empiriques qui se sont vérifiées lors de nos exécutions : commencez par des B-splines cubiques (la valeur par défaut degree=3) et 8 à 12 coefficients par entrée ; au-delà de 20, ajoutez une pénalité de rugosité ; choisissez la taille finale sur des données de validation. Optez pour Legendre lorsque la fonction est très lisse et que vous voulez le moins de paramètres possible, et pour les degrés élevés, utilisez checkpoint_segments pour échanger du calcul contre de la mémoire lors de la rétropropagation [2].
4. Applications d’entrée : où vos nœuds tombent réellement
Les courbes vivent sur un intervalle borné (par défaut de -1 à 1), mais pas les variables. Chaque module applique donc d’abord une application d’entrée. Les options intégrées sont "real.rational" (la valeur par défaut du module en 0.3.4, x / sqrt(s² + x²)), "real.arctan", "real.clamp" (écrête x / s à l’intervalle), ainsi que "nonneg.rational" et "nonneg.arctan" pour les entrées non négatives. Pour une échelle personnalisée, utilisez des objets comme tc.maps.Real.clamp(scale=3.0), ou passez n’importe quel appelable f(x, out_min, out_max) [2].
Conseils pratiques :
- Standardisez d’abord, puis choisissez. Pour des variables à peu près normales,
tc.maps.Real.clamp(scale=3.0)donne des nœuds réguliers sur ±3 écarts-types et une extrapolation plate au-delà, ce qui est facile à expliquer. - Utilisez les applications rational ou arctan pour les distributions à queue lourde, lorsque vous voulez une certaine résolution loin du centre et acceptez qu’elle soit grossière.
- Pour des entrées déjà dans [0, 1], définissez
parameter_range=(0, 1)avec"real.clamp"afin que les nœuds couvrent exactement la plage de vos données, comme dans les scripts ci-dessus. - La version 0.3.0 a remplacé les anciens arguments
normalize_fnetnormalization_scaleparinput_map[2]. Du code écrit pour 0.2.x échouera.
5. Une courbe de calibration monotone
Un besoin courant en production : transformer un score brut de modèle en une probabilité qui ne diminue jamais lorsque le score augmente. Les B-splines rendent cela simple, car une spline dont les coefficients sont croissants est elle-même croissante [2]. Nous paramétrons les coefficients comme une première valeur plus une somme cumulée de pas positifs (softplus les maintient positifs), et nous les passons à un BSplineBasis. La comparaison porte sur une spline non contrainte de même taille et sur la régression isotonique de 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:]}")
Sortie :
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]
La spline non contrainte ondule : elle décroît sur 140 des 1 000 pas de la grille, ce que vous ne pouvez pas livrer comme courbe de prix ou de risque. La spline monotone ne décroît jamais, par construction, et elle est en outre légèrement meilleure sur les données mises de côté. La régression isotonique est elle aussi monotone, mais c’est ici une fonction en escalier à 37 niveaux ; la spline est lisse et compte 20 nombres que vous pouvez afficher.
Les deux dernières lignes montrent un piège à connaître. Sans pénalité, le dernier coefficient a dérivé jusqu’à 32.6 sur l’échelle logit : peu de points d’entraînement se trouvent près d’un score de 1, et rien n’empêche le coefficient de bord de s’emballer. Une pénalité de rugosité de 0.001 l’a ramené à 5.1 sans perte de précision. Inspectez toujours les coefficients de bord.
Le README et le notebook d’exemple de la bibliothèque utilisent la même astuce sous une forme plus riche : un réseau encodeur transforme les caractéristiques d’enchères en coefficients croissants, et chaque échantillon reçoit sa propre courbe de probabilité de gain en fonction de l’enchère [2]. C’est le troisième schéma de la figure sur les formes de tenseurs.
6. Un modèle additif et un KAN sur des données tabulaires
Passons à un problème tabulaire. Nous générons cinq variables standardisées aux effets connus (une tanh saturante, une forme en U, une marche, une onde, et une variable sans effet), plus une interaction cachée entre les deux premières, et un bruit gaussien d’écart-type 0.3. Le modèle additif est un BSplineCurve à cinq courbes de 12 coefficients chacune, suivi de tc.Sum : prédiction = biais + f0(x0) + ... + f4(x4). Il s’agit d’un modèle additif généralisé (GAM), entraîné par descente de gradient ; le modèle additif neuronal d’Agarwal et al. repose sur la même idée avec de petits réseaux au lieu de splines [7].
Le KAN empile deux couches de courbes, chacune suivie d’une somme, comme dans le README de la bibliothèque ; les réseaux de Kolmogorov-Arnold placent une fonction 1-D apprenable sur chaque arête du réseau [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))
Sortie :
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
Ce que disent les chiffres :
- Le modèle additif TorchCurves égale le GAM à splines de scikit-learn (0.600 contre 0.603, 61 paramètres pour les deux). Même classe de modèle, entraîneur différent. Si votre modèle est purement additif et tabulaire, la combinaison
SplineTransformerde scikit-learn et d’une régression ridge est plus simple et plus rapide [8]. - Les deux modèles additifs manquent l’interaction et restent nettement au-dessus du plancher de bruit de 0.30. C’est le coût honnête d’une courbe lisible par variable. Si l’interaction compte, ajoutez-la explicitement (par exemple une courbe du produit, ou un terme 2-D) plutôt que d’abandonner la structure.
- Le KAN capte une partie de l’interaction (0.471) avec 480 paramètres répartis sur 48 courbes ; il est plus expressif mais ne se lit plus comme une courbe par variable.
- Le MLP et le gradient boosting l’emportent en précision (0.341 et 0.393) et perdent en lisibilité. À vous de décider de quel côté de cette ligne se situe votre cas d’usage.
- Le tableau des formes retrouve la réalité : par exemple f1 en x = ±2 vaut 2.05 et 1.98 pour une valeur réelle de 2.00, et la variable non pertinente x4 reste à moins de 0.04 de zéro.
Pourquoi entraîner un GAM dans PyTorch ? Parce qu’il peut alors constituer une partie d’un modèle plus vaste : une tête additive « explicable » à côté d’un modèle d’embeddings, des courbes dont les coefficients sont produits par un autre réseau, une courbe monotone dans un modèle de tarification, ou des embeddings continus de variables numériques au sein d’un transformer ou d’une machine de factorisation, ce qui est le cas d’usage visé par les travaux de recherche antérieurs de l’auteur [6].
7. Exporter et inspecter les coefficients
Un modèle auditable est un modèle que quelqu’un d’autre peut réévaluer. Le script ci-dessous reconstruit la couche de courbes, charge les poids entraînés, écrit les nœuds, le degré, l’application d’entrée et les coefficients en JSON, les réévalue avec BSpline de SciPy à partir du seul JSON, et capture la couche avec torch.export pour le service en production.
# 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()
Sortie :
exported 5 curves x 12 coefficients
max |torch - scipy| = 6.234304983365746e-07
torch.export: ok, 80 ops
exported program matches eager: True
La réévaluation SciPy concorde à 6.2 × 10-7 près (arrondi float32), y compris pour des entrées au-delà de ±3 écarts-types, où l’application clamp aplatit la courbe. Ce fichier JSON est désormais le modèle de référence : assez petit pour être relu, comparé dans Git et joint à un dossier de risque de modèle, et évaluable dans n’importe quel langage disposant d’une routine B-spline.
Deux détails sur l’export. D’abord, torch.export se spécialise sur les formes de l’entrée d’exemple : notre première tentative sans dynamic_shapes a échoué à l’exécution avec Guard failed: u.size()[0] == 8 pour toute autre taille de lot. Marquez la dimension de lot comme dynamique, comme ci-dessus. Ensuite, torch.jit.trace fonctionne toujours dans PyTorch 2.15 mais affiche un avertissement d’obsolescence recommandant torch.export. Nous n’avons pas testé l’export ONNX.
8. Le tester
Quatre tests couvrent ce qui pose généralement problème : les formes et la validation des entrées, les gradients (vérifiés numériquement avec torch.autograd.gradcheck en float64), la concordance avec SciPy et la garantie de 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
Ajoutez par-dessus des tests propres à votre modèle : le signe ou le sens attendu de la courbe de chaque variable, des bornes sur les coefficients de bord, et un export JSON de référence qui ne doit pas changer sans relecture.
9. L’exploiter en production
- Packaging. Épinglez
torchcurves,torchet Python dans votre fichier de verrouillage ; c’est une jeune bibliothèque 0.x et la version 0.3.0 a déjà introduit des changements incompatibles. Stockez la version de la bibliothèque dans le JSON exporté, comme le fait notre script. - Conteneurs. Une wheel PyTorch CPU uniquement garde des images légères, et les modèles de courbes ont rarement besoin d’un GPU pour l’inférence. Dans le cas purement additif, vous pouvez même vous passer entièrement de PyTorch en production et évaluer le JSON avec SciPy ou quelques lignes de NumPy.
- CPU ou GPU. Les benchmarks de l’auteur montrent que la bibliothèque est plus lente que SciPy ou NumPy pour de petits lots et peu de courbes, à cause de la surcharge Python, à peu près au niveau d’EfficientKAN pour l’entraînement de KAN, et plus rapide pour des tailles de lot et des dimensions plus importantes [1]. Mesurez sur vos propres formes avant de choisir le matériel.
- Checkpoints. Utilisez
state_dict(). Le vecteur de nœuds est un buffer, il est donc sauvegardé avec les poids ; pour changer les nœuds, chargez un state dict plutôt que de modifier le tenseur, afin que la plage de paramètres en cache soit actualisée [2]. - Supervision. Surveillez la distribution des entrées par rapport à la plage des nœuds : la part des entrées au-delà des limites de clamp mesure directement la fréquence à laquelle le modèle extrapole à plat. Suivez la calibration des courbes monotones dans le temps, et déclenchez une alerte si un réentraînement déplace fortement un coefficient de bord.
- Relecture. Tracez chaque courbe à chaque réentraînement et comparez-la à la version précédente. Un changement de forme est un changement de modèle, même si la métrique de précision ne bouge pas.
Pièges et débogage
ValueError: Input u must be a 2D tensor of shape (N, num_curves=...): vous avez passé un tenseur 1-D ou un mauvais nombre de colonnes. Utilisezx.view(-1, 1)pour une seule courbe.TypeError: ... unexpected keyword argument 'num_control_points'ou'normalize_fn': arguments inventés ou antérieurs à 0.3.0. Utilisezknots_configetinput_map.- Le nombre de points de contrôle doit dépasser le degré : une cubique nécessite au moins quatre coefficients.
- Courbe plate là où vous attendiez du détail : vos données sont hors de la plage des nœuds, ou l’application rational a resserré les nœuds près de zéro. Tracez les nœuds en unités brutes (section 4).
- Valeurs aberrantes aux bords : peu de points de données près de la frontière. Ajoutez une pénalité de rugosité ou resserrez la plage.
- Confusions de formes avec
LegendreCurve.coefficients: c’est (K, C, D), et non (C, K, D) commeBSplineCurve.control_points. - Entraînement lent sur de tout petits lots : attendu en raison de la surcharge Python ; utilisez des lots plus grands, ou SciPy pour les courbes uniques.
Comparaison
| Outil | Nature | Entraînable dans PyTorch | À utiliser lorsque |
|---|---|---|---|
| torchcurves | Couches de courbes B-spline et de Legendre, modules de base, API fonctionnelle | Oui, entrées et coefficients | Les courbes font partie d’un modèle PyTorch plus vaste, ou les coefficients proviennent d’un autre réseau |
SciPy (make_smoothing_spline, BSpline) | Ajustement et évaluation classiques de splines | Non | Une courbe, ajustée une fois ; évaluation de référence des courbes exportées |
scikit-learn SplineTransformer + modèle linéaire | Variables spline pour un modèle de type GAM | Non | Modèles tabulaires purement additifs avec un outillage standard |
IsotonicRegression (scikit-learn) | Ajustement monotone en escalier | Non | Calibration monotone rapide lorsque des paliers sont acceptables |
| pykan, efficient-kan | Implémentations de KAN | Oui | Recherche sur les KAN ; efficient-kan était la référence de vitesse de l’article [1][10] |
xitorch Interp1D, torch-interpol, torch-cubic-spline-grids | Interpolation différentiable ou grilles de splines | En partie | Interpolation de données ou apprentissage de grilles denses, selon la comparaison du README de torchcurves lui-même |
| MLP, gradient boosting | Algorithmes d’apprentissage généralistes | MLP oui | La précision prime, les interactions comptent, l’explication peut venir a posteriori |
La version originale de notre blog comparait TorchCurves avec NVIDIA Kaolin Wisp et Torch Lens Maker. Ce sont respectivement des bibliothèques différentiables pour les champs neuronaux et l’optique géométrique, et non des alternatives d’ajustement de courbes ; nous les avons donc écartées ici.
FAQ
Est-ce un remplacement du gradient boosting ? Non. Sur notre test tabulaire, le boosting et un MLP étaient plus précis. Les courbes sont destinées aux cas où la lisibilité ou une règle de forme compte davantage que les derniers points de précision, ou lorsque la courbe est un composant d’un modèle neuronal.
Une courbe peut-elle produire un vecteur ? Oui : dim fixe la dimension de sortie. Une courbe d’un scalaire vers un vecteur de dimension 16 est un embedding continu de ce scalaire.
Puis-je définir mes propres nœuds ? Oui : passez un tenseur 1-D comme knots_config et le nombre de points de contrôle est déduit. Vous ne pouvez pas le combiner avec parameter_range.
Fonctionne-t-elle sur GPU ? Oui, c’est du PyTorch pur, donc .to("cuda") fonctionne ; les benchmarks de l’article incluent l’entraînement de KAN sur GPU [1]. Qu’elle soit plus rapide que sur CPU dépend de la taille de lot et du nombre de courbes.
Combien de coefficients dois-je utiliser ? Commencez par 8 à 12 par entrée avec une petite pénalité de rugosité et ajustez sur les données de validation. Avec une pénalité, être généreux coûte peu.
L’API de l’article est-elle la même que celle du paquet ? Pour l’essentiel. L’article (v1) désigne real.arctan comme application d’entrée par défaut et mentionne un argument num_knots ; le code 0.3.4 utilise par défaut "real.rational" et emploie knots_config. Fiez-vous au code source installé et à la documentation de votre version [11].
Si vous intégrez des modèles interprétables dans un pipeline de production et souhaitez de l’aide pour leur versionnage, leurs tests et leur supervision, consultez notre service de mise en place MLOps.
Références
- A. Shtoff, « TorchCurves: Differentiable Parametric Curves », arXiv:2611.14516v1, 10 novembre 2026
- alexshtf/torchcurves sur GitHub : README, code source (v0.3.4), notebooks d’exemple et notes de version
- torchcurves sur PyPI
- P. H. C. Eilers et 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 : une implémentation de KAN en PyTorch pur
- Documentation de torchcurves
PyTorch est une marque commerciale de The Linux Foundation. Les autres noms appartiennent à leurs propriétaires respectifs. Cet article est indépendant et n’est pas approuvé par les auteurs des bibliothèques présentées. Le code de cette note technique est fourni à titre d’exemple ; vérifiez-le par rapport à la documentation actuelle de la bibliothèque avant de vous y fier.