---
title: Quickstart
review-state: drafting
last-human-review: "2026-06-04"
depends-on:
  - src/pytyche/bcf/hurdle/compose.py
  - src/pytyche/generators/api.py
owner: tradcliffe
---

# Quickstart

The shortest path to a fitted joint hurdle BCF on a synthetic
adaptive-enrichment dataset. Runs in ~20 seconds on JAX-CPU.

```python
import numpy as np
import pandas as pd
from pytyche import generate, GPUBCFConfig, fit_hurdle_bcf

SEGMENTS = {
    "responders":     {"pct": 0.4, "base_conv": 0.08, "treatment_effect": 0.10,
                       "aov_mu": 3.5, "aov_sigma": 0.5, "treatment_aov_mu_shift": 0.15},
    "non_responders": {"pct": 0.6, "base_conv": 0.06, "treatment_effect": 0.0,
                       "aov_mu": 3.3, "aov_sigma": 0.5, "treatment_aov_mu_shift": 0.0},
}
bundle = generate(n_visitors=800, segments=SEGMENTS,
                  metric="revenue_per_visitor", seed=0)

control_df = bundle.observed.variants[0].visitors
treatment_df = bundle.observed.variants[1].visitors
visitors = pd.concat([control_df, treatment_df], ignore_index=True)

seg_to_idx = {name: i for i, name in enumerate(SEGMENTS)}
X = visitors["segment"].map(seg_to_idx).to_numpy().reshape(-1, 1).astype(np.float32)
Z = (visitors["variant"] == "treatment").to_numpy().astype(np.float32)
Y_rev = visitors["revenue"].to_numpy().astype(np.float32)
propensity = np.full(len(visitors), 0.5, dtype=np.float32)

result = fit_hurdle_bcf(X, Z, Y_rev, propensity, GPUBCFConfig(
    num_burnin=40, num_mcmc=80, num_trees_mu=30, num_trees_tau=15,
    max_depth=4, num_gfr_sweeps=2, random_seed=0,
))
# result.rpv_cate_samples → (n_visitors, 80) per-visitor CATE posterior draws
```

The full walk-through — including data unpacking, posterior
interpretation at the segment level, and ground-truth comparison — is
in the [first hurdle BCF fit tutorial](../tutorials/first-hurdle-bcf-fit.md).

For the *why* — what the joint hurdle BCF is doing, why segments are
discovered rather than declared, what calibration buys you — start
with the [overview](../concepts/overview.md).

## What's next

- **Scale up**: the tutorial above sizes for JAX-CPU. For realistic
  experimentation scale (50k–2M visitors per round), install the
  `[gpu]` extra and bump `num_burnin` / `num_mcmc` / `num_trees_mu` /
  `num_trees_tau`. The library is designed around GPU execution at
  scale; the per-round fit hits 4.5–8.6× speedup at n=750k versus the
  CPU StochTree backend.
- **Adaptive-enrichment loop**: the single-fit example above is a
  pre-cursor to the multi-round sequential targeting loop. See
  [sequential targeting](../concepts/sequential-targeting.md) for the
  full round-over-round design.
- **Calibration**: BCF posteriors at production scale are
  systematically overconfident. The
  [BCF calibration at scale](../concepts/bcf-calibration-at-scale.md)
  concept doc explains why and what to do about it.