torchvinecopulib

For optimal dependency management, it is recommended to use uv. After cloning the repository, navigate to the project root and follow these steps to set up a virtual environment and sync dependencies based on your hardware requirements.

Note on CUDA support:

• Use --extra cpu for default CPU support.
• Use --extra cu126 for CUDA 12.6 support.
• Use --extra cu128 for CUDA 12.8 support.
• Use --extra examples to install additional dependencies required for the Jupyter notebooks in the ./examples/ folder.

# From inside the project root folder
# Create and activate local virtual environment
uv venv .venv
source .venv/bin/activate

# Sync dependencies with CPU support (default)
uv sync --extra cpu

# Or for CUDA 12.6 or 12.8 support (depends on your CUDA version)
uv sync --extra cu126

# Additionally, to install additional dependencies for the examples
uv sync --extra examples

If you have a fitted model from pyvinecopulib (pvc), you can transfer its structure (the vine matrix) to a torchvinecopulib (tvc) model. This is useful for leveraging GPU acceleration or integrating with PyTorch.

Workflow:

1. Convert data to pseudo-observations using pvc.to_pseudo_obs().
2. Fit a pvc.Vinecop using pvc.Vinecop.from_data().
3. Extract the matrix from the pvc.Vinecop object.
4. Initialize a tvc.VineCop and pass the matrix to the .fit() method.

import pyvinecopulib as pvc
import torchvinecopulib as tvc

# 1. Fit PVC model
controls = pvc.FitControlsVinecop(family_set=[pvc.BicopFamily.tll])
vine_pvc = pvc.Vinecop.from_data(u_cls, controls=controls)

# 2. Extract matrix and convert to torch format
# Subtract 1 because PVC uses 1-based indexing for the matrix
tvc_mat = torch.tensor(
    np.array(vine_pvc.matrix, dtype=np.int32),
    dtype=torch.int32,
    device=DEVICE
).rot90(k=3) - 1

# 3. Fit TVC model using the PVC structure
vine_tvc = tvc.VineCop(
    num_dim=u_cls.shape[1],
    is_cop_scale=True,
    num_step_grid=30,
).to(DEVICE)

vine_tvc.fit(
    obs=u_cls_tensor,
    matrix=tvc_mat,
    is_dissmann=False,
    mtd_kde="tll",
)

You can use torchvinecopulib.VineCop within a pytorch_lightning.LightningModule to regularize the latent space of an autoencoder. By adding the log-likelihood of the latent representations (calculated via the vine copula) to the loss function, you can encourage the latent space to follow a specific dependency structure.

Key steps:

1. Define a set_vine method to inject a fitted tvc.VineCop into your module.
2. In training_step, calculate the loss as: MSE_loss(reconstruction, original) - vine.log_pdf(latent).mean().
3. Ensure the vine_type matches the object type (e.g., tvc.VineCop for tvc type).

import torchvinecopulib as tvc
import pytorch_lightning as pl

class LitAutoencoder(pl.LightningModule):
    def __init__(self, use_vine=False, vine_type="tvc", ...):
        super().__init__()
        self.use_vine = use_vine
        self.vine_type = vine_type
        self.vine = None

    def set_vine(self, vine):
        if self.vine_type == "tvc":
            if not isinstance(vine, tvc.VineCop):
                raise ValueError("Vine must be of type tvc.VineCop for tvc.")
        self.vine = vine

    def training_step(self, batch, batch_idx):
        x, _ = batch
        z = self.encoder(x)
        x_hat = self.decoder(z)
        
        if self.use_vine:
            # Regularize latent space using the vine copula log-pdf
            loss = F.mse_loss(x_hat, x) - self.vine.log_pdf(z).mean()
        else:
            loss = F.mse_loss(x_hat, x)
        return loss