Skip to content

Add FAQ section to improve user guidance #608

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Add FAQ section to improve user guidance #608

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
978017b
Add FAQ section to improve user guidance
Jun 3, 2025
d9a46e3
Update faq/index.qmd
AoifeHughes Jun 17, 2025
41ab37b
Update faq/index.qmd
AoifeHughes Jun 17, 2025
2b97c35
Update faq/index.qmd
AoifeHughes Jun 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions _quarto.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ website:
text: Get Started
- href: tutorials/coin-flipping/
text: Tutorials
- href: faq/
text: FAQ
- href: https://turinglang.org/library/
text: Libraries
- href: https://turinglang.org/news/
Expand Down
71 changes: 71 additions & 0 deletions faq/index.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
---
title: "Frequently Asked Questions"
description: "Common questions and answers about using Turing.jl"
---

## Why is this variable being treated as random instead of observed?

This is a common source of confusion. In Turing.jl, you can only condition or fix expressions that explicitly appear on the left-hand side (LHS) of a `~` statement.

For example, if your model contains:
```julia
x ~ filldist(Normal(), 2)
```

You cannot directly condition on `x[2]` using `condition(model, @varname(x[2]) => 1.0)` because `x[2]` never appears on the LHS of a `~` statement. Only `x` as a whole appears there.

Comment on lines +15 to +16
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be good to have a bit more subtlety here, as there is a case where this isn't true: if you use x .~ dist where dist is a univariate distribution, then each element of x is separately treated as being drawn from dist. So, you can do

@model function f1()
    x = Vector{Float64}(undef, 3)
    x .~ Normal()
end

m1 = f1() | (@varname(x[1]) => 1.0)
sample(m1, NUTS(), 100) # OK

However, you can't condition on part of a distribution, so because MvNormal() is a distribution that returns a vector, you can't condition on part of it. (Statistically, this would be like marginalising out some degrees of freedom, but we don't have the ability to do that now.)

@model function f2()
    x = Vector{Float64}(undef, 3)
    x ~ MvNormal(zeros(3), I)
end

m2 = f2() | (@varname(x[1]) => 1.0)
sample(m2, NUTS(), 100) # Not OK

And filldist doesn't create a set of N iid distributions; it lumps them all into a single distribution, which is why you can't condition on x[1] in the example. So it's not so much about conditioning on the LHS of a tilde, it's more about conditioning on entire distributions at once.

It's quite confusing, and hence why I think it's important to explain this carefully.

To understand more about how Turing determines whether a variable is treated as random or observed, see:
- [Compiler Design Overview](../developers/compiler/design-overview/) - explains the heuristics Turing uses
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- [Compiler Design Overview](../developers/compiler/design-overview/) - explains the heuristics Turing uses

This one is also very outdated

- [Core Functionality](../core-functionality/) - basic explanation of the `~` notation and conditioning

## How do I implement a sampler for a Turing.jl model?

We have comprehensive guides on implementing custom samplers:
- [Implementing Samplers Tutorial](../developers/inference/implementing-samplers/) - step-by-step guide on implementing samplers in the AbstractMCMC framework
- [AbstractMCMC-Turing Interface](../developers/inference/abstractmcmc-turing/) - how to integrate your sampler with Turing
- [AbstractMCMC Interface](../developers/inference/abstractmcmc-interface/) - the underlying interface documentation
Comment on lines +25 to +26
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- [AbstractMCMC-Turing Interface](../developers/inference/abstractmcmc-turing/) - how to integrate your sampler with Turing
- [AbstractMCMC Interface](../developers/inference/abstractmcmc-interface/) - the underlying interface documentation

These docs are severely outdated

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Surely we keep it then when we update the docs we don't have to worry about linking? Also that seems like a separate issue, why do we have outdated docs?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Surely we keep it then when we update the docs we don't have to worry about linking

Those pages specifically aren't even in the sidebar (I removed them in #607) so for all intents and purposes don't exist.

why do we have outdated docs?

I mean, it's a research project, nobody has time to write docs, blah blah. These aren't the only outdated pages, and even the up-to-date pages probably have sections which are out of date.


## Can I use parallelism / threads in my model?

Yes! Turing.jl supports both multithreaded and distributed sampling. See the [Core Functionality guide](../core-functionality/#sampling-multiple-chains) for detailed examples showing:
- Multithreaded sampling using `MCMCThreads()`
- Distributed sampling using `MCMCDistributed()`
Comment on lines +30 to +32
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one also needs more nuance. Sampling one chain per thread is indeed done with MCMCThreads() but (I think) the main intent behind this question is whether one can use threading within the model itself, e.g.,

@model function f(x)
    Threads.@threads for i in eachindex(x)
        x[i] ~ Normal()
    end
end

That means that the execution of the model itself is inherently multithreaded (as opposed to sampling with MCMCThreads(), where each chain runs the model many times but only on one thread).

The TLDR of this in the model is that threaded observe statements are OK but threaded assume statements are not (they often crash in unpredictable ways, or sometimes they actually work if you're really lucky).

Another aspect maybe worth mentioning is that threads inside models don't work with many AD backends (see multithreaded in https://turinglang.org/ADTests/ for an example)


## How do I check the type stability of my Turing model?

Type stability is crucial for performance. Check out:
- [Performance Tips](../usage/performance-tips/) - includes specific advice on type stability
- [Automatic Differentiation](../usage/automatic-differentiation/) - contains benchmarking utilities using `DynamicPPL.TestUtils.AD`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- [Automatic Differentiation](../usage/automatic-differentiation/) - contains benchmarking utilities using `DynamicPPL.TestUtils.AD`

The AD page doesn't discuss type stability.

I think the best 'high-level' way to determine type stability is https://turinglang.org/DynamicPPL.jl/stable/api/#DynamicPPL.DebugUtils.model_warntype although I've not used it myself.


## How do I debug my Turing model?

For debugging both statistical and syntactical issues:
- [Troubleshooting Guide](../usage/troubleshooting/) - common errors and their solutions
- For more advanced debugging, DynamicPPL provides `DynamicPPL.DebugUtils` for inspecting model internals

## What are the main differences between Turing, BUGS, and Stan syntax?

While there are many syntactic differences, key advantages of Turing include:
- **Julia ecosystem**: Full access to Julia's profiling and debugging tools
- **Parallel computing**: Much easier to use distributed and parallel computing inside models
- **Flexibility**: Can use arbitrary Julia code within models
- **Extensibility**: Easy to implement custom distributions and samplers
Comment on lines +48 to +52
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't answer the stated question?

If it's a question about syntax, I would personally think it's best to have Turing vs Stan in a single section, and Turing vs (other PPL) can be a different section. Apart from the parameter block, two of the common things that Stan models have that Turing doesn't are transformed data and generated quantities -- the gist in Turing is that any data transformations should be done before defining the model (so it's decoupled from the model) and generated quantities are covered in https://turinglang.org/docs/usage/tracking-extra-quantities/index.html.


## Which automatic differentiation backend should I use?

The choice of AD backend can significantly impact performance. See:
- [Automatic Differentiation Guide](../usage/automatic-differentiation/) - comprehensive comparison of ForwardDiff, Mooncake, ReverseDiff, and other backends
- [Performance Tips](../usage/performance-tips/#choose-your-ad-backend) - quick guide on choosing backends
- [AD Backend Benchmarks](https://turinglang.org/ADTests/) - performance comparisons across various models

For more specific recommendations, check out the [DifferentiationInterface.jl tutorial](https://juliadiff.org/DifferentiationInterface.jl/DifferentiationInterfaceTest/stable/tutorial/).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think DITest is relevant yet --- to use the benchmarking functionality in there we would need to have a way of constructing DifferentiationInterfaceTest.Scenarios from Turing models and although it's not very hard to write some code for that, it's probably too long to go into an FAQ page. Would be a good thing to add to the AD page, probably in a separate PR.


## I changed one line of my model and now it's so much slower; why?

Small changes can have big performance impacts. Common culprits include:
- Type instability introduced by the change
- Switching from vectorized to scalar operations (or vice versa)
- Inadvertently causing AD backend incompatibilities
- Breaking assumptions that allowed compiler optimizations

See our [Performance Tips](../usage/performance-tips/) and [Troubleshooting Guide](../usage/troubleshooting/) for debugging performance regressions.
Comment on lines +63 to +71
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know you took the list questions from somewhere else, but I don't really like this question. I don't get the intent behind it (what is the answer supposed to be?) and the result of this is, I think, reflected in the text, which is very vague and IMO not very helpful. If the answer is basically to read the performance section.

IME interactions with AD backend don't often lead to performance differences, usually it either runs fine or it crashes. If the AD is unusually slow it usually reflects slowness in the model itself.

Loading