---
title: Copulas
description: Bivariate (Clayton, Frank, Gumbel, independence) and multivariate (Gaussian, tree, vine) copulas with the BivariateExt / MultivariateExt traits.
category: copula
since: 2.0.0
status: stable
---

# Copulas

The `stochastic-rs-copulas` crate ships bivariate and multivariate
copulas plus correlation utilities and an empirical copula.

## Bivariate (`BivariateExt<T>`)

Archimedean and elliptical:

| Copula        | Family       | Tail dependence    |
|---------------|--------------|--------------------|
| Clayton       | Archimedean  | Lower only         |
| Frank         | Archimedean  | None (symmetric)   |
| Gumbel        | Archimedean  | Upper only         |
| Independence  | Trivial      | None               |

The bivariate samplers are consolidated under `BivariateExt`; the v1.x
`NCopula2DExt` was removed in v2.0.

## Multivariate (`MultivariateExt<T>`)

| Copula        | Family        | Notes                          |
|---------------|---------------|--------------------------------|
| Gaussian      | Elliptical    | Cholesky-based                 |
| Tree          | Vine, simplified | Tree-structured Pair-copula |
| Vine          | Vine, full    | R-vine / D-vine / C-vine       |

> Multivariate copulas require the `openblas` feature for the Cholesky
> factorisation. See [Feature flags](/docs/concepts/feature-flags).

## Examples

### Clayton — lower-tail dependence

$\theta > 0$ produces lower-tail dependence, useful for modelling joint
crashes in equity returns.

<Tabs items={['Rust', 'Python']}>
<Tab value="Rust">
```rust
use stochastic_rs::copulas::bivariate::clayton::Clayton;
use stochastic_rs::traits::BivariateExt;

let mut cop = Clayton::new();
cop.set_tau(0.5);                            // τ ⇒ θ via Kendall inversion
let _ = cop.compute_theta();
let uv = cop.sample_with_seed(10_000, 42)?;  // Array2<f64>, shape (10_000, 2)
let (u, v) = (uv.column(0), uv.column(1));   // both in [0, 1]

let tau_hat = stochastic_rs::stats::tail_index::kendall_tau(u, v);
println!("τ̂ = {:.3}", tau_hat);
```
</Tab>
<Tab value="Python">
```python
import stochastic_rs as srs

cop = srs.Clayton(theta=2.0)
uv = cop.sample(10_000, seed=42)             # shape (10_000, 2)
u, v = uv[:, 0], uv[:, 1]
print("Kendall's tau ≈", srs.kendall_tau(u, v))   # ≈ 0.5
```
</Tab>
</Tabs>

### Gaussian copula — multivariate sampling

<Tabs items={['Rust']}>
<Tab value="Rust">
```rust
use stochastic_rs::copulas::multivariate::gaussian::GaussianMultivariate;
use stochastic_rs::traits::MultivariateExt;
use ndarray::array;

let corr = array![
    [1.0, 0.7, 0.3],
    [0.7, 1.0, 0.5],
    [0.3, 0.5, 1.0],
];
let cop = GaussianMultivariate::new_with_corr(corr)?;
let samples = cop.sample(10_000)?;           // Array2<f64>, shape (10_000, 3)
```

> The multivariate Gaussian copula depends on `ndarray-linalg` (the
> `openblas` feature) for the Cholesky factorisation, so it is **not**
> wrapped for Python — use the Rust API directly.
</Tab>
</Tabs>

## Adding a copula

See the
[`copula-bivariate`](https://github.com/dancixx/stochastic-rs/blob/main/.claude/skills/copula-bivariate/SKILL.md)
SKILL — file-by-file recipe for Clayton / Frank / Gumbel / Joe /
Plackett / FGM / extreme-value families.
