GPU-ready, differentiable vine copula modelling in pure PyTorch.
Drop-in replacement for pyvinecopulib — same API, but with autograd and CUDA support.
| torchvine | pyvinecopulib | |
|---|---|---|
| Backend | Pure PyTorch (GPU / CPU) | C++ with Python bindings |
| Differentiable | ✅ Autograd-compatible | ❌ |
| GPU acceleration | ✅ CUDA tensors | ❌ CPU only |
| API | Drop-in replacement | Reference |
| Copula families | 13 (full parity) | 13 |
Zero C/C++ dependencies — everything is implemented in pure PyTorch, making it easy to install, debug, and extend.
pip install torchvineFrom source:
git clone https://github.com/Bluerrror/torchvine.git
cd torchvine
pip install -e .Requirements: Python ≥ 3.9 | PyTorch ≥ 2.0 | matplotlib ≥ 3.5
import torch
import torchvine as tv
# Create a Gaussian copula with correlation 0.7
cop = tv.Bicop(tv.BicopFamily.gaussian, parameters=torch.tensor([0.7]))
print(cop.str()) # <torchvine.Bicop> family: gaussian, parameters: [0.7000]
print(cop.parameters_to_tau()) # Kendall's tau ≈ 0.494
# Evaluate density and simulate
u = torch.rand(1000, 2, dtype=torch.float64)
pdf_vals = cop.pdf(u)
samples = cop.simulate(1000)
# Fit from data (automatic family selection)
fitted = tv.Bicop()
fitted.select(samples)
print(fitted.str())# Fit a 5-dimensional vine copula
data = torch.rand(500, 5, dtype=torch.float64)
vine = tv.Vinecop.from_dimension(5)
vine.select(data, controls=tv.FitControlsVinecop(family_set=tv.parametric))
print(vine.str())
print(f"Log-likelihood: {vine.loglik(data):.2f}")
print(f"AIC: {vine.aic(data):.2f}")
# Simulate and transform
sim = vine.simulate(1000)
pit = vine.rosenblatt(data) # probability integral transformx = torch.randn(1000, dtype=torch.float64)
y = 0.6 * x + 0.8 * torch.randn(1000, dtype=torch.float64)
print(tv.kendall_tau(x, y)) # Kendall's tau
print(tv.spearman_rho(x, y)) # Spearman's rho
print(tv.pearson_cor(x, y)) # Pearson correlation
print(tv.blomqvist_beta(x, y)) # Blomqvist's beta
print(tv.hoeffding_d(x, y)) # Hoeffding's Ddevice = "cuda" if torch.cuda.is_available() else "cpu"
u_gpu = torch.rand(10000, 2, dtype=torch.float64, device=device)
cop = tv.Bicop(tv.BicopFamily.clayton, parameters=torch.tensor([3.0], device=device))
pdf_gpu = cop.pdf(u_gpu) # runs entirely on GPU| Family | Parameters | Type |
|---|---|---|
| Independence | 0 | — |
| Gaussian | 1 (ρ) | Elliptical |
| Student-t | 2 (ρ, ν) | Elliptical |
| Clayton | 1 (θ) | Archimedean |
| Gumbel | 1 (θ) | Archimedean / Extreme-value |
| Frank | 1 (θ) | Archimedean |
| Joe | 1 (θ) | Archimedean |
| BB1 | 2 (θ, δ) | Archimedean |
| BB6 | 2 (θ, δ) | Archimedean |
| BB7 | 2 (θ, δ) | Archimedean |
| BB8 | 2 (θ, δ) | Archimedean |
| Tawn | 3 (ψ₁, ψ₂, θ) | Extreme-value |
| TLL | nonparametric | Kernel-based |
All asymmetric families support rotations (0°, 90°, 180°, 270°).
| Class | Description |
|---|---|
tv.Bicop |
Bivariate copula — create, fit, evaluate, simulate |
tv.Vinecop |
Vine copula model — select, pdf, simulate, rosenblatt |
tv.Kde1d |
1-D kernel density estimation — fit, pdf, cdf, quantile |
tv.RVineStructure |
R-vine structure matrix |
tv.DVineStructure |
D-vine structure (convenience subclass) |
tv.CVineStructure |
C-vine structure (convenience subclass) |
tv.FitControlsBicop |
Fitting options for bivariate copulas |
tv.FitControlsVinecop |
Fitting options for vine copulas |
tv.BicopFamily |
Enum of all copula families |
| Function | Description |
|---|---|
tv.kendall_tau(x, y) |
Kendall's rank correlation |
tv.spearman_rho(x, y) |
Spearman's rank correlation |
tv.pearson_cor(x, y) |
Pearson linear correlation |
tv.blomqvist_beta(x, y) |
Blomqvist's beta (medial correlation) |
tv.hoeffding_d(x, y) |
Hoeffding's D statistic |
tv.wdm(x, y, method) |
Unified interface for all measures |
| Function | Description |
|---|---|
tv.to_pseudo_obs(data) |
Rank-transform to pseudo-observations |
tv.simulate_uniform(n, d) |
Uniform random / quasi-random samples |
tv.pairs_copula_data(data) |
Pairs plot with copula density contours |
See the examples/ directory for Jupyter notebooks:
| Notebook | Topics |
|---|---|
| 01 — Getting Started | Imports, copula basics, simulation, fitting |
| 02 — Bivariate Copulas | All families, rotations, Student-t, model selection |
| 03 — Vine Copulas | Vine fitting, structure, simulation, Rosenblatt transform |
| 04 — Kde1d & Statistics | KDE, dependence measures, pairs plot visualization |
- Fork the repo
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit changes:
git commit -m "Add amazing feature" - Push:
git push origin feature/amazing-feature - Open a Pull Request
MIT License — see LICENSE for details.
- API design follows vinecopulib / pyvinecopulib by Thomas Nagler and Thibault Vatter.