### Install via pip

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/README.md

Standard installation commands for the library and its dependencies.

```bash
pip install torchvinecopulib torch
```

```bash
# inside project root folder
pip install ./dist/torchvinecopulib-1.1.0-py3-none-any.whl
# or
pip install ./dist/torchvinecopulib-1.1.0.tar.gz
```

--------------------------------

### Run Benchmark Example

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/benchmark/readme.md

Navigate to the project root folder and execute the benchmark script located at ./examples/benchmark/__init__.py using uv run.

```bash
uv run ./examples/benchmark/__init__.py
```

--------------------------------

### Install Dependencies (CPU Only)

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/benchmark/readme.md

Run this command in the project root folder to synchronize and install CPU-only dependencies using uv.

```bash
uv sync --extra cpu -U
```

--------------------------------

### Install project dependencies

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/pred_intvl/readme.md

Use uv to sync dependencies based on hardware requirements.

```bash
# cpu only
uv sync --extra cpu -U
# or with cuda
uv sync --extra cu126 -U
```

--------------------------------

### Install Dependencies (with CUDA)

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/benchmark/readme.md

Run this command in the project root folder to synchronize and install dependencies with CUDA support (version 12.6) using uv.

```bash
uv sync --extra cu126 -U
```

--------------------------------

### Import Libraries and Setup

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/3_bicop_tll.ipynb

Imports necessary libraries and sets up the device (CPU or CUDA) for PyTorch operations. Prints system and library versions.

```python
import sys
import platform
import torch
import torchvinecopulib as tvc
from torchvinecopulib.util import _EPS
import pyvinecopulib as pv
import numpy as np
import warnings

warnings.filterwarnings("ignore", category=RuntimeWarning)
DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
# DEVICE = "cpu"
print("Python:", sys.version.replace("\n", " "))
print("Platform:", platform.platform())
print("PyTorch:", torch.__version__)
print("CUDA available:", torch.cuda.is_available())
```

--------------------------------

### Install torchvinecopulib

Source: https://context7.com/ty-cheng/torchvinecopulib/llms.txt

Install the torchvinecopulib library using pip. For CUDA support, specify the PyTorch version with the appropriate index URL and force reinstallation.

```bash
pip install torchvinecopulib torch
```

```bash
pip install torch --index-url https://download.pytorch.org/whl/cu126 --force-reinstall
```

--------------------------------

### Setup IPython Environment

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/vcae/vcae_analyze.ipynb

Loads IPython extensions for autoreload, sets matplotlib backend, and configures inline figure format. Ensure IPython is available.

```python
# add autoreload and other ipython magic
import glob
import os

import numpy as np
import pandas as pd
from IPython import get_ipython

ipython = get_ipython()
ipython.run_line_magic("load_ext", "autoreload")
ipython.run_line_magic("autoreload", "2")
ipython.run_line_magic("matplotlib", "inline")
ipython.run_line_magic("config", 'InlineBackend.figure_format = "retina"')
```

--------------------------------

### Configure PyTorch for CUDA

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/README.md

Installation command for PyTorch with CUDA support and a verification check.

```bash
pip install torch --index-url https://download.pytorch.org/whl/cu126 --force-reinstall
# check cuda availability
python -c "import torch; print(torch.cuda.is_available())"
```

--------------------------------

### Initialize Environment and Dependencies

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/0_bicop.ipynb

Sets up the environment by importing necessary libraries and checking system information.

```python
import sys
import platform
import matplotlib.pyplot as plt
import torch
import warnings
import math
import torchvinecopulib as tvc

from torch.special import ndtr
from torchvinecopulib.util import _EPS

warnings.filterwarnings("ignore", category=RuntimeWarning)
DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
DEVICE = "cpu"
print("Python:", sys.version.replace("\n", " "))
print("Platform:", platform.platform())
print("PyTorch:", torch.__version__)
print("CUDA available:", torch.cuda.is_available())
```

--------------------------------

### Initialize and Prepare Data for VineCop

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/1_vinecop.ipynb

Sets up the environment and generates multivariate observations for copula modeling.

```python
import sys
import platform
import math
import torch
from torch.special import ndtr, ndtri
import torchvinecopulib as tvc
from torchvinecopulib.util import _EPS

DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
# DEVICE = "cpu"
print("Python:", sys.version.replace("\n", " "))
print("Platform:", platform.platform())
print("PyTorch:", torch.__version__)
print("CUDA available:", torch.cuda.is_available())
torch.random.manual_seed(42)
num_dim = 6
rho = 0.95
V = torch.randn(size=(10000, 2), dtype=torch.float64)
V[:, 1] = rho * V[:, 0] + math.sqrt(1 - rho**2) * V[:, 1]
VV = torch.randn(size=(5000, 2), dtype=torch.float64)
VV[:, 1] = -rho * VV[:, 0] + math.sqrt(1 - rho**2) * VV[:, 1]
V = ndtr(torch.vstack([V, VV])).clamp(_EPS, 1 - _EPS)
obs_mvcp = V
for _ in range(1 + num_dim // 2):
    idx = torch.randperm(obs_mvcp.shape[0])
    obs_mvcp = torch.hstack(
        [
            obs_mvcp,
            torch.hstack(
                [
                    torch.vstack(
                        [
                            obs_mvcp[torch.randperm(1000), [0]].reshape(-1, 1),
                            obs_mvcp[idx[1000:], [0]].reshape(-1, 1),
                        ]
                    ),
                    obs_mvcp[idx, [1]].reshape(-1, 1),
                ]
            ),
        ]
    )
obs_mvcp = obs_mvcp[torch.randperm(obs_mvcp.shape[0])[:10000], :num_dim].to(DEVICE)
obs = ndtri(obs_mvcp)
# obs = obs_mvcp
is_cop_scale = False
del V, VV, obs_mvcp, rho
```

--------------------------------

### Manage dependencies with uv

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/README.md

Commands for setting up a virtual environment and syncing dependencies with specific hardware support.

```bash
# 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
```

--------------------------------

### Build documentation

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/README.md

Commands to generate documentation using Sphinx.

```bash
# inside project root folder
sphinx-apidoc -o ./docs ./torchvinecopulib && cd ./docs && make html && cd ..
# if using uv
uv run sphinx-apidoc -o docs torchvinecopulib/ --separate
uv run sphinx-build docs docs/_build/html
```

--------------------------------

### Initialize Vine Copula Sampling Environment

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/2_num_hfunc.ipynb

Imports necessary libraries and configures the compute device for torchvinecopulib operations.

```python
import sys
import platform
import pandas as pd
import torch
import torchvinecopulib as tvc
import matplotlib.pyplot as plt

DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
```

--------------------------------

### Configure and Train Model

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/4_mnist.ipynb

Instantiates the autoencoder, sets up checkpointing, and runs the trainer.

```python
# Instantiate the LitMNISTAutoencoder
model = LitMNISTAutoencoder()

# Instantiate a checkpoint callback
checkpoint_callback = ModelCheckpoint(
    monitor="val_loss",  # metric to monitor
    mode="min",  # "min" for val_loss, "max" for accuracy
    save_top_k=1,  # only save the best model
    save_last=True,  # also save the last epoch
    dirpath=config.save_dir,  # where to save
    filename="{epoch:02d}-{val_loss:.4f}",  # optional: filename format
)

# Instantiate a PyTorch Lightning trainer with the specified configuration
trainer = pl.Trainer(
    accelerator=config.accelerator,
    devices=config.devices,
    max_epochs=config.max_epochs,
    logger=CSVLogger(save_dir=config.save_dir),
    callbacks=[checkpoint_callback],
)

# Train the model using the trainer
trainer.fit(model)
```

--------------------------------

### Prepare Model for Inference

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/4_mnist.ipynb

Loads the best checkpoint and prepares the data loader for evaluation.

```python
# last_path = os.path.join(config.save_dir, "last.ckpt")  # default naming
# Load best checkpoint
inference_model = LitMNISTAutoencoder.load_from_checkpoint(
    checkpoint_path=checkpoint_callback.best_model_path
)
inference_model.eval()
inference_model.freeze()

inference_model.prepare_data()
inference_model.setup(stage="fit")  # sets model.mnist_train, model.mnist_val
train_loader = model.train_dataloader()
```

--------------------------------

### Execute experiment script

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/pred_intvl/readme.md

Run the experiment script from the project root directory.

```bash
uv run ./examples/pred_intvl/experiments.py
```

--------------------------------

### Import necessary libraries and configure device

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/4_mnist.ipynb

Imports required libraries for data manipulation, deep learning, and vine copulas. Sets the computation device to CUDA if available, otherwise CPU.

```python
import os
from dataclasses import dataclass

import numpy as np
import pandas as pd
import pytorch_lightning as pl
import pyvinecopulib as pvc
import seaborn as sns
import torch
from pytorch_lightning.callbacks import ModelCheckpoint
from pytorch_lightning.loggers import CSVLogger
from torch import nn
from torch.nn import functional as F
from torch.utils.data import DataLoader, random_split
from torchvision import transforms
from torchvision.datasets import MNIST

import torchvinecopulib as tvc

DEVICE = "cuda" if torch.cuda.is_available() else "cpu"


@dataclass
class Config:
    data_dir: str = os.environ.get("PATH_DATASETS", ".")
    save_dir: str = "logs/"
    batch_size: int = 1024 if torch.cuda.is_available() else 64
    max_epochs: int = 10
    accelerator: str = "auto"
    devices: int = 1


config = Config()
```

--------------------------------

### Specify project root directory

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/pred_intvl/readme.md

Define the project root location by creating a .env file in the root folder.

```bash
DIR_WORK='~/path/to/project/root/folder'
```

--------------------------------

### Train and Refit LitMNISTAutoencoder

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/vcae/vcae_debug.ipynb

Demonstrates the training process using PyTorch Lightning and the subsequent refitting of the model.

```python
# # Instantiate the LitMNISTAutoencoder
# model = LitMNISTAutoencoder()

# # Instantiate a trainer with the specified configuration
# trainer = pl.Trainer(
#     accelerator=config.accelerator,
#     devices=config.devices,
#     max_epochs=config.max_epochs,
#     logger=CSVLogger(save_dir=config.save_dir),
# )

# # Train the model using the trainer
# trainer.fit(model)

# # Train the vine
# model.learn_vine(n_samples=5000)
# # # Read in the training metrics from the CSV file generated by the logger
# # metrics = pd.read_csv(f"{trainer.logger.log_dir}/metrics.csv")

# # # Remove the "step" column, which is not needed for our analysis
# # del metrics["step"]

# # # Set the epoch column as the index, for easier plotting
# # metrics.set_index("epoch", inplace=True)

# # # Create a line plot of the training metrics using Seaborn
# # sns.relplot(data=metrics, kind="line")

# # Train the vine
# model.learn_vine(n_samples=5000)

# # Copy the model for refitting
# model_refit = copy.deepcopy(model)

# # Instantiate a new trainer
# trainer_refit = pl.Trainer(
#     accelerator=config.accelerator,
#     devices=config.devices,
#     max_epochs=config.max_epochs,
#     logger=CSVLogger(save_dir=config.save_dir),
# )

# # Refit the model
```

--------------------------------

### Instantiate and Plot BiCop Model

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/0_bicop.ipynb

Creates a BiCop model instance with a specified grid size and displays its structure.

```python
mdl_bcp = tvc.BiCop(
    # ! num_step_grid has to be a power of 2 !
    num_step_grid=64,
).to(DEVICE)
mdl_bcp.plot()
print(type(mdl_bcp).__mro__)
```

--------------------------------

### VineCop.fit - Fitting Vine Copula Models

Source: https://context7.com/ty-cheng/torchvinecopulib/llms.txt

Demonstrates fitting various vine copula structures (R-vine, D-vine, C-vine) to observational data using Dissmann's algorithm or Kendall's tau for dependence measure.

```APIDOC
## VineCop.fit - Fitting Vine Copula Models

Fit a vine copula to observational data using various algorithms and dependence measures.

### Method

`VineCop.fit(
    obs: torch.Tensor,
    is_dissmann: bool = False,
    mtd_vine: str = "rvine",
    mtd_bidep: str = "chatterjee_xi",
    thresh_trunc: float = 0.01,
    mtd_kde: str = "tll",
    first_tree_vertex: tuple = (0, 1)
)`

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

- **obs** (torch.Tensor) - Required - Observational data of shape (n_samples, num_dim).
- **is_dissmann** (bool) - Optional - If True, use Dissmann's algorithm for structure learning. Defaults to False.
- **mtd_vine** (str) - Optional - Type of vine structure to fit. Options: "cvine", "dvine", "rvine". Defaults to "rvine".
- **mtd_bidep** (str) - Optional - Dependence measure for bivariate copulas. Options: "chatterjee_xi", "kendall_tau", "mutual_info", "ferreira_tail_dep_coeff". Defaults to "chatterjee_xi".
- **thresh_trunc** (float) - Optional - Truncation threshold based on Kendall's tau p-value. Defaults to 0.01.
- **mtd_kde** (str) - Optional - KDE method for bicops. Options: "tll", "fastKDE". Defaults to "tll".
- **first_tree_vertex** (tuple) - Optional - Priority vertices for conditional simulation. Defaults to (0, 1).

### Request Example

```python
import torch
import torchvinecopulib as tvc

device = "cpu"

torch.manual_seed(42)
num_dim = 6
n_samples = 10000
data = torch.randn(size=(n_samples, num_dim), dtype=torch.float64)
rho = 0.9
for i in range(1, num_dim):
    data[:, i] = rho * data[:, i-1] + (1 - rho**2)**0.5 * data[:, i]

vinecop = tvc.VineCop(num_dim=num_dim, is_cop_scale=False, num_step_grid=128).to(device)
vinecop.fit(
    obs=data,
    is_dissmann=True,
    mtd_vine="rvine",
    mtd_bidep="chatterjee_xi",
    thresh_trunc=0.01,
    mtd_kde="tll",
    first_tree_vertex=(0, 1),
)

print(f"Sample order: {vinecop.sample_order}")
print(f"Vine matrix:\n{vinecop.matrix}")
```

### Response

#### Success Response (200)

- **sample_order** (list) - The order in which samples are generated.
- **matrix** (torch.Tensor) - The vine matrix representing the fitted structure.

#### Response Example

```json
{
  "sample_order": [0, 1, 2, 3, 4, 5],
  "matrix": [[...]]
}
```
```

--------------------------------

### Run Coverage Report

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/README.md

Use these commands to run coverage reports for your tests. The first command generates an HTML report, while the second provides a text-based report.

```bash
coverage run -m pytest ./tests && coverage html
```

```bash
uv run coverage run --source=torchvinecopulib -m pytest ./tests
```

```bash
uv run coverage report -m
```

--------------------------------

### Refit Model Execution

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/vcae/vcae_debug.ipynb

Initiates the refitting process for a specified model.

```python
trainer_refit.fit(model_refit)
```

--------------------------------

### Fit Multivariate Vine Copula

Source: https://context7.com/ty-cheng/torchvinecopulib/llms.txt

Initializes and fits a multivariate vine copula (C-vine, D-vine, or R-vine). Can automatically handle marginal distributions if data is not on copula scale.

```python
import torch
import torchvinecopulib as tvc
from torch.special import ndtr, ndtri

device = "cuda" if torch.cuda.is_available() else "cpu"

# Generate multivariate data
torch.manual_seed(42)
num_dim = 5
n_samples = 5000

# Create correlated data
rho = 0.8
data = torch.randn(size=(n_samples, num_dim), dtype=torch.float64)
for i in range(1, num_dim):
    data[:, i] = rho * data[:, i-1] + (1 - rho**2)**0.5 * data[:, i]

# Initialize and fit vine copula (on original scale, not copula scale)
vinecop = tvc.VineCop(
    num_dim=num_dim,
    is_cop_scale=False,      # Data is NOT in [0,1], fit marginals automatically
    num_step_grid=128
).to(device)

vinecop.fit(
    obs=data,
    mtd_vine="rvine",        # "cvine", "dvine", or "rvine"
    mtd_bidep="kendall_tau"  # Dependence measure for structure learning
)

print(vinecop)
```

--------------------------------

### Define project dependencies

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/README.md

Configuration snippet for the pyproject.toml file defining library requirements.

```toml
# inside the `./pyproject.toml` file;
fastkde = "*"
numpy = "*"
pyvinecopulib = "*"
python = ">=3.11"
scipy = "*"
# optional to facilitate customization
torch = [
    { index = "torch-cpu", extra = "cpu" },
    { index = "torch-cu126", extra = "cu126" },
    { index = "torch-cu128", extra = "cu128" },
]
```

--------------------------------

### Fit with priority vertices for conditional simulation

Source: https://context7.com/ty-cheng/torchvinecopulib/llms.txt

Demonstrates fitting a vine copula with specific conditioning variables and performing conditional simulation.

```python
vinecop = tvc.VineCop(num_dim=num_dim, is_cop_scale=False, num_step_grid=128).to(device)
vinecop.fit(
    obs=data,
    mtd_vine="rvine",
    mtd_bidep="kendall_tau",
    first_tree_vertex=(0, 1)  # Variables 0 and 1 will be conditioned on
)

print(f"Sample order: {vinecop.sample_order}")

# Conditional simulation: fix variables 0 and 1, sample the rest
num_cond_samples = 1000
fixed_v0 = torch.ones(size=(num_cond_samples, 1), dtype=torch.float64, device=device)   # X0 = 1.0
fixed_v1 = torch.zeros(size=(num_cond_samples, 1), dtype=torch.float64, device=device)  # X1 = 0.0

# Provide observations for conditioning variables
# Keys are tuples: (variable_index,) for marginals
conditional_samples = vinecop.sample(
    num_sample=num_cond_samples,
    is_sobol=True,
    sample_order=vinecop.sample_order[:-2],  # Exclude last 2 (conditioned variables)
    dct_v_s_obs={
        (vinecop.sample_order[-1],): fixed_v0,
        (vinecop.sample_order[-2],): fixed_v1,
    }
)

print(f"Conditional samples shape: {conditional_samples.shape}")
print(f"First 3 conditional samples:\n{conditional_samples[:3]}")
# Columns 0 and 1 should be fixed at the specified values
```

--------------------------------

### Model Persistence with torch.save/load

Source: https://context7.com/ty-cheng/torchvinecopulib/llms.txt

Demonstrates saving and loading fitted vine copula models using PyTorch's serialization capabilities. Ensures the model architecture is recreated before loading state_dict.

```python
import torch
import torchvinecopulib as tvc

device = "cpu"

# Fit a model
torch.manual_seed(42)
num_dim = 4
data = torch.randn(size=(5000, num_dim), dtype=torch.float64)
for i in range(1, num_dim):
    data[:, i] = 0.8 * data[:, i-1] + 0.6 * data[:, i]

vinecop = tvc.VineCop(num_dim=num_dim, is_cop_scale=False, num_step_grid=128).to(device)
vinecop.fit(obs=data, mtd_vine="rvine", mtd_bidep="kendall_tau")

# Save the model
torch.save(vinecop.state_dict(), "vinecop_model.pt")

# Load the model
vinecop_loaded = tvc.VineCop(num_dim=num_dim, is_cop_scale=False, num_step_grid=128).to(device)
vinecop_loaded.load_state_dict(torch.load("vinecop_model.pt"))
vinecop_loaded.eval()

# Verify loaded model works
samples = vinecop_loaded.sample(num_sample=100)
print(f"Samples from loaded model: {samples.shape}")
```

--------------------------------

### Model Performance Comparison

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/vcae/vcae_debug.ipynb

Retrieves test data and computes comparative metrics including log-likelihood, MMD, and FID scores for original and refitted models.

```python
# Test the model
representation, labels, data, decoded, samples = model.get_data(stage="test")
representation_refit, labels_refit, data_refit, decoded_refit, samples_refit = model_refit.get_data(
    stage="test"
)

sigmas = [1e-3, 1e-2, 1e-1, 1, 10, 100]
score_model = compute_score(data, samples, DEVICE, sigmas=sigmas)
score_refit_model = compute_score(refit_data, refit_samples, DEVICE, sigmas=sigmas)
loglik_model = model.vine.log_pdf(representation).mean()
loglik_refit_model = model_refit.vine.log_pdf(representation_refit).mean()
print("Log-likelihood (original vs refit):")
print(
    f"Log-likelihood: {loglik_model} vs {loglik_refit_model} => original is {loglik_model / loglik_refit_model} x worse"
)
print("Model scores (original vs refit):")
print(
    f"MMD: {score_model.mmd} vs {score_refit_model.mmd} => original is {score_model.mmd / score_refit_model.mmd} x worse"
)
print(
    f"FID: {score_model.fid} vs {score_refit_model.fid} => original is {score_model.fid / score_refit_model.fid} x worse"
)
```

--------------------------------

### Initialize and Fit VineCop Model

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/2_num_hfunc.ipynb

Initializes a VineCop model and fits it to observational data. Ensure data is in copula scale if `is_cop_scale` is True. The `thresh_trunc` parameter controls truncation.

```python
mdl_vcp = tvc.VineCop(
    num_dim=obs.shape[1],
    # ! indicates whether the data is in the copula scale !
    is_cop_scale=is_cop_scale,
)
mdl_vcp.fit(
    obs=obs,
    mtd_vine="dvine",
    thresh_trunc=-1,
)
print(mdl_vcp)
mdl_vcp.draw_lv()
```

--------------------------------

### Compare Sample Order Costs

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/2_num_hfunc.ipynb

Compares the cost of the automatically determined sample order with the worst possible sample order. This helps in understanding the efficiency of the model's ordering.

```python
print(
    f"sample order: {sample_order}, cost: {
        mdl_vcp.ref_count_hfunc(
            num_dim=mdl_vcp.num_dim,
            struct_obs=mdl_vcp.struct_obs,
            sample_order=sample_order,
        )[2]
    }"
)
print(
    f"sample order: {mdl_vcp.sample_order}, cost: {
        mdl_vcp.ref_count_hfunc(
            num_dim=mdl_vcp.num_dim,
            struct_obs=mdl_vcp.struct_obs,
            sample_order=mdl_vcp.sample_order,
        )[2]
    }"
)
```

--------------------------------

### Generate Multivariate Samples with VineCop.sample

Source: https://context7.com/ty-cheng/torchvinecopulib/llms.txt

Draws random samples from a fitted vine copula using the inverse Rosenblatt transform. Can generate unconditional samples or perform conditional simulation. The `seed` parameter ensures reproducibility.

```python
import torch
import torchvinecopulib as tvc

device = "cpu"

# Generate and fit
torch.manual_seed(42)
num_dim = 5
data = torch.randn(size=(5000, num_dim), dtype=torch.float64)
for i in range(1, num_dim):
    data[:, i] = 0.85 * data[:, i-1] + (1 - 0.85**2)**0.5 * data[:, i]

vinecop = tvc.VineCop(num_dim=num_dim, is_cop_scale=False, num_step_grid=128).to(device)
vinecop.fit(obs=data, mtd_vine="rvine", mtd_bidep="kendall_tau")

# Generate unconditional samples
samples = vinecop.sample(num_sample=1000, seed=42, is_sobol=True)
print(f"Samples shape: {samples.shape}")
print(f"First 3 samples:\n{samples[:3]}")
# Samples shape: torch.Size([1000, 5])
# First 3 samples:
# tensor([[-0.8234,  0.1234, -0.5678,  0.3456, -0.9012],
#         [ 1.2345, -0.4567,  0.7890, -0.1234,  0.5678],
#         ...])
```

```python
import torch
import torchvinecopulib as tvc

device = "cpu"

# Generate data with dependencies
torch.manual_seed(42)
num_dim = 6
data = torch.randn(size=(10000, num_dim), dtype=torch.float64)
for i in range(1, num_dim):
    data[:, i] = 0.9 * data[:, i-1] + (1 - 0.9**2)**0.5 * data[:, i]


```

--------------------------------

### BiCop - Bivariate Copula Initialization and Fitting

Source: https://context7.com/ty-cheng/torchvinecopulib/llms.txt

Initialize and fit a BiCop object for nonparametric bivariate copula estimation. The fitting process uses kernel density estimation (TLL or fastKDE) and can optionally estimate Kendall's tau.

```python
import torch
import torchvinecopulib as tvc
from torch.special import ndtr

# Set device
device = "cuda" if torch.cuda.is_available() else "cpu"

# Generate correlated bivariate data in copula scale [0,1]
torch.manual_seed(42)
rho = 0.8
n_samples = 5000
V = torch.randn(size=(n_samples, 2), dtype=torch.float64)
V[:, 1] = rho * V[:, 0] + (1 - rho**2)**0.5 * V[:, 1]
obs = ndtr(V).clamp(1e-10, 1 - 1e-10).to(device)

# Create and fit bivariate copula
bicop = tvc.BiCop(num_step_grid=128).to(device)
bicop.fit(obs, mtd_kde="tll", is_tau_est=True)
print(bicop)
# BiCop
# {'is_indep': False,
#  'num_obs': tensor(5000),
#  'negloglik': tensor(-2847.1234),
#  'num_step_grid': 128,
#  'tau': tensor([0.5912, 0.0000]),
#  'mtd_kde': 'tll',
#  'dtype': torch.float64,
#  'device': device(type='cpu')}
```

```python
import torch
import torchvinecopulib as tvc
from torch.special import ndtr

device = "cuda" if torch.cuda.is_available() else "cpu"

# Generate bivariate data
torch.manual_seed(0)
rho = 0.9
V = torch.randn(size=(10000, 2), dtype=torch.float64)
V[:, 1] = rho * V[:, 0] + (1 - rho**2)**0.5 * V[:, 1]
obs = ndtr(V).clamp(1e-10, 1 - 1e-10).to(device)

# Fit using TLL (transformation local-likelihood) method
bicop = tvc.BiCop(num_step_grid=128).to(device)
bicop.fit(
    obs=obs,
    mtd_kde="tll",           # "tll" or "fastKDE"
    mtd_tll="constant",      # "constant", "linear", or "quadratic"
    is_tau_est=True          # Compute Kendall's tau
)

# Alternative: Fit using fastKDE method with Sinkhorn normalization
bicop_fkde = tvc.BiCop(num_step_grid=256).to(device)
bicop_fkde.fit(
    obs=obs,
    mtd_kde="fastKDE",
    num_iter_max=17          # Sinkhorn/IPF iterations for normalization
)
```

--------------------------------

### Fit R-vine with Dissmann's Algorithm

Source: https://context7.com/ty-cheng/torchvinecopulib/llms.txt

Fits an R-vine copula using Dissmann's algorithm. Specifies dependence measure, truncation threshold, and KDE method. Useful for learning the structure of complex dependencies.

```python
import torch
import torchvinecopulib as tvc

device = "cpu"

# Generate multivariate data
torch.manual_seed(42)
num_dim = 6
n_samples = 10000
data = torch.randn(size=(n_samples, num_dim), dtype=torch.float64)

# Create dependencies
rho = 0.9
for i in range(1, num_dim):
    data[:, i] = rho * data[:, i-1] + (1 - rho**2)**0.5 * data[:, i]

# Fit R-vine with Dissmann's algorithm
vinecop = tvc.VineCop(num_dim=num_dim, is_cop_scale=False, num_step_grid=128).to(device)
vinecop.fit(
    obs=data,
    is_dissmann=True,           # Use Dissmann's algorithm for structure learning
    mtd_vine="rvine",           # Vine type: "cvine", "dvine", or "rvine"
    mtd_bidep="chatterjee_xi",  # Dependence measure: "chatterjee_xi", "kendall_tau",
                                # "mutual_info", "ferreira_tail_dep_coeff"
    thresh_trunc=0.01,          # Truncation threshold based on Kendall's tau p-value
    mtd_kde="tll",              # KDE method for bicops: "tll" or "fastKDE"
    first_tree_vertex=(0, 1),   # Priority vertices for conditional simulation
)

print(f"Sample order: {vinecop.sample_order}")
print(f"Vine matrix:\n{vinecop.matrix}")

# Fit D-vine structure
vinecop_dvine = tvc.VineCop(num_dim=num_dim, is_cop_scale=False, num_step_grid=128).to(device)
vinecop_dvine.fit(obs=data, mtd_vine="dvine", mtd_bidep="kendall_tau")

# Fit C-vine structure
vinecop_cvine = tvc.VineCop(num_dim=num_dim, is_cop_scale=False, num_step_grid=128).to(device)
vinecop_cvine.fit(obs=data, mtd_vine="cvine", mtd_bidep="kendall_tau")
```

--------------------------------

### Run tests

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/README.md

Command to execute the test suite using pytest.

```python
# inside project root folder
python -m pytest ./tests
```

--------------------------------

### Fit Copula using fastKDE with Torchvinecopulib

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/3_bicop_tll.ipynb

Fits a copula using the fastKDE method from torchvinecopulib and plots the fitted copula and its contour.

```python
cop_fastkde = tvc.BiCop(
    num_step_grid=1024,
).to(DEVICE)
cop_fastkde.fit(U_tensor, mtd_kde="fastKDE")
cop_fastkde.plot()
cop_fastkde.plot(plot_type="contour", margin_type="norm")
```

--------------------------------

### Refit Autoencoder with VineCop

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/4_mnist.ipynb

Loads a checkpointed autoencoder, injects the trained VineCop model, and resumes training using a PyTorch Lightning trainer.

```python
refit_model = LitMNISTAutoencoder.load_from_checkpoint(
    checkpoint_path=checkpoint_callback.best_model_path
)
refit_model.use_vine = True
refit_model.set_vine(vine_tvc)

# Instantiate a new trainer with the specified configuration
refit_trainer = pl.Trainer(
    accelerator=config.accelerator,
    devices=config.devices,
    max_epochs=config.max_epochs,
    logger=CSVLogger(save_dir=config.save_dir),
    callbacks=[checkpoint_callback],
)

# Train the model using the trainer
refit_trainer.fit(refit_model)
```

--------------------------------

### Fit Vine Copula Models per Class

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/4_mnist.ipynb

Iterates through unique classes to fit both pvc and tvc vine copula models, storing them in a dictionary and calculating log-likelihoods.

```python
# Prepare containers
class_vines = {}
unique_classes = np.unique(labels_np)

for cls in unique_classes:
    # 1. Select samples for this class
    class_mask = labels_np == cls
    x_cls = reps_np[class_mask]

    # 2. Convert to pseudo-observations
    u_cls = pvc.to_pseudo_obs(x_cls)
    u_cls_tensor = torch.tensor(u_cls, device=DEVICE)

    # 3. Fit vine copula with nonparametric TLL estimator
    controls = pvc.FitControlsVinecop(family_set=[pvc.BicopFamily.tll])  # nonparametric
    vine_pvc = pvc.Vinecop.from_data(u_cls, controls=controls)
    tvc_mat = (
        torch.tensor(
            np.array(vine_pvc.matrix, dtype=np.int32),
            dtype=torch.int32,
            device=DEVICE,
        )
        - 1
    ).rot90(k=3)
    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",
    )

    # 4. Store the fitted model
    class_vines[cls] = {}
    class_vines[cls]["vine_pvc"] = vine_pvc
    class_vines[cls]["vine_tvc"] = vine_tvc

    # 5. Compute and display the log-likelihood
    loglik_pvc = vine_pvc.loglik()
    loglik_tvc = vine_tvc.log_pdf(obs=u_cls_tensor).sum()
    print(
        f"Average log-likelihood for class {cls}: {loglik_pvc / len(x_cls):.4f} (pvc), {loglik_tvc / len(x_cls):.4f} (tvc)"
    )
    break
```

--------------------------------

### Generate Copula Samples

Source: https://context7.com/ty-cheng/torchvinecopulib/llms.txt

Generates random samples from a fitted bivariate copula using either pseudo-random numbers or Sobol quasi-random sequences. Requires data to be in the range [0, 1].

```python
import torch
import torchvinecopulib as tvc
from torch.special import ndtr

device = "cpu"

# Fit copula
torch.manual_seed(42)
rho = 0.85
V = torch.randn(size=(5000, 2), dtype=torch.float64)
V[:, 1] = rho * V[:, 0] + (1 - rho**2)**0.5 * V[:, 1]
obs = ndtr(V).clamp(1e-10, 1 - 1e-10).to(device)

bicop = tvc.BiCop(num_step_grid=128).to(device)
bicop.fit(obs, mtd_kde="tll")

# Generate samples using pseudo-random numbers
samples_random = bicop.sample(num_sample=1000, seed=42, is_sobol=False)
print(f"Random samples shape: {samples_random.shape}")
print(f"First 5 samples:\n{samples_random[:5]}")

# Generate samples using Sobol quasi-random sequence (better space coverage)
samples_sobol = bicop.sample(num_sample=1000, seed=42, is_sobol=True)
print(f"Sobol samples shape: {samples_sobol.shape}")
```

--------------------------------

### Run VCAE Experiments

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/vcae/vcae_debug.ipynb

Configures and executes experiments for MNIST or SVHN datasets, saving results to CSV files.

```python
# add autoreload and other ipython magic
import os

import pandas as pd
from IPython import get_ipython
from tqdm import tqdm
from vcae.config import config_mnist, config_svhn
from vcae.experiment import run_experiment

ipython = get_ipython()
ipython.run_line_magic("load_ext", "autoreload")
ipython.run_line_magic("autoreload", "2")
ipython.run_line_magic("matplotlib", "inline")
ipython.run_line_magic("config", 'InlineBackend.figure_format = "retina"')

results = []
dataset = "MNIST"  # or "SVHN"
# dataset = "SVHN"  # or "MNIST"
vine_lambda = 1.0  # Default value for vine lambda
save_results = True  # Save results for each seed in a separate CSV file
n_seeds = 1  # Number of seeds to run

if dataset == "MNIST":
    config = config_mnist
elif dataset == "SVHN":
    config = config_svhn
else:
    raise ValueError(f"Unknown dataset: {dataset}")

output_path = f"results_{dataset}_{vine_lambda}.csv"
for seed in tqdm(range(n_seeds), desc="Running experiments"):
    result = run_experiment(seed, config, dataset=dataset, vine_lambda=vine_lambda)
    results.append(result)
    # Save result to a CSV file
    if save_results:
        df_result = pd.DataFrame([result])

        # Write headers only once
        if not os.path.exists(output_path):
            df_result.to_csv(output_path, index=False, mode="w")
        else:
            df_result.to_csv(output_path, index=False, mode="a", header=False)


df_results = pd.DataFrame(results)
# df_results.to_csv("experiment_results.csv", index=False)
```

--------------------------------

### Compare Log-PDFs via Scatterplot

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/4_mnist.ipynb

Visualizes the relationship between the log-PDFs of the two bivariate models using a scatterplot.

```python
sns.scatterplot(
    x=np.log(bicop_pvc.pdf(u_cls[:, :2])),
    y=bicop_tvc.log_pdf(obs=u_cls_tensor[:, :2]).cpu().numpy().reshape(-1),
)
```

--------------------------------

### VineCop.fit - Fit Vine Copula Structure

Source: https://context7.com/ty-cheng/torchvinecopulib/llms.txt

Learns the vine structure and fits all bivariate copulas within the vine.

```APIDOC
## VineCop.fit - Fit Vine Copula Structure

### Description
Learns the vine structure using Dissmann's algorithm (or a user-specified matrix) and fits all bivariate copulas within the vine structure. This method estimates the dependence structure and parameters for the entire multivariate copula.

### Method
`fit(obs, mtd_vine='rvine', mtd_bidep='kendall_tau', structure=None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **obs** (torch.Tensor) - The observation data, shape (N, num_dim), where N is the number of samples and num_dim is the number of dimensions.
- **mtd_vine** (str, optional) - Method for learning the vine structure. Options: 'cvine', 'dvine', 'rvine'. Defaults to 'rvine'.
- **mtd_bidep** (str, optional) - Dependence measure used for structure learning. Options: 'kendall_tau', 'spearman_rho'. Defaults to 'kendall_tau'.
- **structure** (torch.Tensor, optional) - A pre-defined structure matrix. If provided, `mtd_vine` is ignored.

#### Request Body
None

### Request Example
```python
import torch
import torchvinecopulib as tvc

device = "cpu"

# Generate multivariate data
torch.manual_seed(42)
num_dim = 3
n_samples = 1000
rho = 0.7
data = torch.randn(size=(n_samples, num_dim), dtype=torch.float64)
for i in range(1, num_dim):
    data[:, i] = rho * data[:, i-1] + (1 - rho**2)**0.5 * data[:, i]

# Initialize VineCop
vinecop = tvc.VineCop(num_dim=num_dim, is_cop_scale=False)

# Fit the vine copula structure
vinecop.fit(obs=data, mtd_vine="dvine", mtd_bidep="spearman_rho")

print("Vine Copula fitted successfully.")
print(f"Negative Log-Likelihood: {vinecop.negloglik}")
```

### Response
#### Success Response (200)
- **negloglik** (float) - The negative log-likelihood of the fitted vine copula model.
- **structure** (torch.Tensor) - The learned vine structure matrix.

#### Response Example
```json
{
  "negloglik": 1234.5678,
  "structure": "[[0, 1, 2], [1, 0, 1], [2, 1, 0]]"
}
```
```

--------------------------------

### VineCop.sample - Generate Multivariate Samples

Source: https://context7.com/ty-cheng/torchvinecopulib/llms.txt

Draws random samples from the fitted vine copula using the inverse Rosenblatt transform.

```APIDOC
## VineCop.sample - Generate Multivariate Samples

Draw random samples from the fitted vine copula via inverse Rosenblatt transform.

### Method

`VineCop.sample(
    num_sample: int,
    seed: int = None,
    is_sobol: bool = False
)`

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

- **num_sample** (int) - Required - The number of samples to generate.
- **seed** (int) - Optional - Seed for the random number generator for reproducibility.
- **is_sobol** (bool) - Optional - If True, use Sobol sequences for quasi-random sampling. Defaults to False.

### Request Example

```python
import torch
import torchvinecopulib as tvc

device = "cpu"

torch.manual_seed(42)
num_dim = 5
data = torch.randn(size=(5000, num_dim), dtype=torch.float64)
for i in range(1, num_dim):
    data[:, i] = 0.85 * data[:, i-1] + (1 - 0.85**2)**0.5 * data[:, i]

vinecop = tvc.VineCop(num_dim=num_dim, is_cop_scale=False, num_step_grid=128).to(device)
vinecop.fit(obs=data, mtd_vine="rvine", mtd_bidep="kendall_tau")

samples = vinecop.sample(num_sample=1000, seed=42, is_sobol=True)
print(f"Samples shape: {samples.shape}")
print(f"First 3 samples:\n{samples[:3]}")
```

### Response

#### Success Response (200)

- **samples** (torch.Tensor) - The generated samples, shape (num_sample, num_dim).

#### Response Example

```json
{
  "samples": [[-0.8234, 0.1234, -0.5678, 0.3456, -0.9012], [1.2345, -0.4567, 0.7890, -0.1234, 0.5678], ...]
}
```
```

--------------------------------

### Perform unconditional sampling

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/1_vinecop.ipynb

Generates samples from the vine copula model.

```python
mdl_vcp.sample()[:5]
```

--------------------------------

### Fit VineCop Model

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/4_mnist.ipynb

Initializes and fits a VineCop model on a subset of representations.

```python
n_samples = 5000
representations_subset = representations[torch.randperm(representations.shape[0])[:n_samples]]
vine_tvc = tvc.VineCop(
    num_dim=representations_subset.shape[1],
    is_cop_scale=False,
    num_step_grid=30,
).to(DEVICE)
vine_tvc.fit(
    obs=representations_subset,
    mtd_kde="tll",
)
# sns.histplot(
#     x=vine_tvc.log_pdf(representations_subset).cpu().numpy().reshape(-1),
#     bins=100,
# )
```

--------------------------------

### Fit and Simulate Normal Copula with PyVineCopulib

Source: https://github.com/ty-cheng/torchvinecopulib/blob/main/examples/3_bicop_tll.ipynb

Fits a true normal copula using pyvinecopulib, simulates data from it, and plots the copula and its contour.

```python
rho = 0.7
seeds = [0, 1, 2, 3, 4]
n = 1000
cop_true = pv.Bicop(
    family=pv.gaussian,
    parameters=np.array([[rho]]),
)
cop_true.plot()
cop_true.plot(type="contour", margin_type="norm")
U = cop_true.simulate(n, seeds=seeds)
U_tensor = torch.tensor(U, device=DEVICE)
```