Tutorials¶

Quivers provides two ways to work with a model: a .qvr language for writing probabilistic programs and a typed Python API for building on the category-theoretic core. The tutorials follow these two tracks. Choose the one that matches your task.

QVR DSL track¶

If you have written a model in Pyro, NumPyro, Stan, or PyMC and want to express it in Quivers, start here. QVR is the primary user-facing language: you declare types, write a program block whose steps look like v <- Normal(loc=0, scale=1) or observe y <- Bernoulli(probs=p), and fit it with SVI or NUTS. The categorical structure informs the implementation but need not appear in the model.

Each chapter shows the QVR version of a familiar model alongside its Pyro / NumPyro / Stan equivalent, then explains what's different and why.

Your first model. Linear regression. Side-by-side with PyMC. SVI fit, posterior predictive check, point summaries.
Generalized linear models. Logistic and Poisson regression. Link functions. Posterior calibration plots.
Hierarchical models. Random intercepts; the eight-schools model; centered vs non-centered parameterizations; running NUTS with diagnostics.
Mixtures and discrete latents. Finite mixtures and HMM-shaped models via the marginalize block: QVR's typed-scope marginalization, the feature that distinguishes it most from Pyro/NumPyro.
Sequence models. Plates, scan, and weighted deduction for chart-shaped models. State-space models and HMMs.
Choosing an inference algorithm. A decision tree over eleven concrete guide classes, seven objectives, two MCMC kernels, and two hybrid approaches. Which combination matches which model shape.
Categorical foundations. (Optional reading.) Algebras as enrichment algebras, >> as enriched composition, and change-of-base as a functor. This chapter supplies the background needed to extend the library or interpret its algebra type errors.
Diagnostics and model comparison. ArviZ end-to-end: to_datatree, convergence diagnostics, posterior-predictive checks, PSIS-LOO model comparison.
Indexed data and total functions. Closed index sorts, indexed families, constructor refinement, recursive case analysis, and direct entry execution.
Effects and handlers. Lexical instances, open rows, authored handlers, resumption grades, and stable execution traces.
Parsing as an effectful computation. Schema-backed parsers, generated search and weight effects, reference inside scores, and parser calls from probabilistic programs.
Structural autoencoders. Signatures, encoder and decoder attachments, checked loss invocation, autograd, and checkpoint registration.
Check, inspect, and transpile. Target-aware checking, entry inspection, runtime traces, LSP configuration, grammar provenance, and release automation.
Exact Bayes with finite collection expressions. Pure map, effect-aware traverse, finite folds, and stable log-space normalization in a grid posterior.

You can read the first six chapters without touching category theory. Chapter 7 is the bridge to the Python API track; chapter 8 covers the Bayesian-analysis workflow once a fit is in hand. Chapters 9–14 cover indexed types, effects, generated search and neural computation graphs, the release boundary, and finite collection programs.

Python API track¶

The Python API gives you direct access to the typed categorical layer: FinSet, Morphism, Algebra, MonadicProgram, inference primitives, and structural-compression components. Use this track to build tooling on top of Quivers, extend its categorical implementation, or inspect what the DSL compiles into.

Your first quiver. FinSet objects, observed and latent morphisms, the >> composition operator, Program.
Stochastic relations. Markov kernels and the FinStoch category. Conditioning, marginalization, expectation queries.
Probabilistic programs. MonadicProgram by hand: continuous spaces, conditional families, bind (<-) / let / observe steps, sampling, and joint trace scoring.
Fuzzy logic factorization. Factorizing an observed fuzzy relation into a composition of latents, training under product-fuzzy noisy-OR composition.
Variational inference. Guide + Objective + SVI + Predictive. Setting up the full inference loop end-to-end.
First-class transformations. MorphismTransformation and AlgebraHomomorphism as values: let-binding, the >>> composition operator, change-of-base pipelines.
Composition rules beyond algebras. The CompositionRule → Semigroupoid → Algebra hierarchy, BilinearForm, and the operadic EinsumWiring API for n-ary contractions.
Analysis pipelines. Formula → fit → diagnostics: brms-style fit("y ~ x + (1|g)", data=df, ...), the emitted .qvr source, SVI on a hierarchical model, NUTS + PSIS-LOO model comparison, and ArviZ DataTree posterior-predictive checks.
Debugging quivers programs. Reading CompileError, inspecting a compiled Program, tracing intermediate values, watching SVI gradients, and using NUTS diagnostics to find the root cause of a misbehaving fit.

Prerequisites¶

For the QVR track:

Python 3.14+, PyTorch 2.0+, quivers installed (Installation).
Comfort with one of the popular probabilistic-programming languages (Pyro, NumPyro, Stan, PyMC). You don't need to know category theory.
For chapters 9–13, install Quivers from one source and keep the package, QVR grammar, reference machine, and language server at the same release.

For the Python API track:

Python and PyTorch as above.
Working knowledge of category theory: objects, morphisms, composition, and functors. The semantics section assumes enriched category theory at Kelly's level. The tutorials do not, though Core Types & Algebras is useful preparation for chapter 4.

How to read¶

Each chapter:

States the model or feature in plain English first.
Shows complete runnable code.
Calls out what changed from the previous chapter.
Ends with a "try this" exercise and pointers to the next chapter.

The chapters are independent enough that you can skim or skip, but each builds on the previous one's vocabulary, so out-of-order reading is easier in the second half.