Add FAQ section to improve user guidance

[AoifeHughes]

This pull request adds a new FAQ section to the Turing.jl website and updates the navigation menu to include a link to the FAQ page. The FAQ section provides answers to common questions about using Turing.jl, covering topics such as random variables, implementing samplers, parallelism, debugging, syntax differences, automatic differentiation backends, and performance issues.

Website Navigation Update:

• _quarto.yml: Added a new link to the FAQ page in the website's navigation menu.

FAQ Section Addition:

• faq/index.qmd: Created a new FAQ page with detailed answers to common questions about Turing.jl. Topics include variable treatment, sampler implementation, parallelism, type stability, debugging, syntax differences, automatic differentiation backends, and performance debugging.

Relevant Issues:

• Request: FAQ section #437
• Introduce a docs FAQ section Turing.jl#2431
• Automate choice of AD backend Turing.jl#2417
• Better performance guidelines and support for user Turing.jl#2414

[Copilot]

Pull Request Overview

This PR adds a new FAQ section to the Turing.jl website and updates the navigation menu to include a link to it.

• Added a “FAQ” entry in the site navigation
• Created faq/index.qmd with a set of common Q&A on using Turing.jl

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
_quarto.yml	Inserted a navigation entry for the FAQ
faq/index.qmd	Added FAQ page with detailed user guidance

Comments suppressed due to low confidence (1)

_quarto.yml:27

• Indentation of the new navigation entry does not match the surrounding items and could break the YAML. Align the - href: faq/ and its text: line with the other menu entries.

- href: faq/

[github-actions]

Preview the changes: https://turinglang.org/docs/pr-previews/608
Please avoid using the search feature and navigation bar in PR previews!

[penelopeysm]

This is a nice start, I think there are a few places where it's necessary to go into more detail, which I've commented on.

General comment for the entire PR: for the URLs, you can use the meta variables defined in _quarto.yml, i.e. [text]({{< meta usage-automatic-differentiation >}}) to avoid hardcoding relative paths (useful if you want to move pages around, which has happened a couple of times).

[penelopeysm]

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.

[penelopeysm]

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

[AoifeHughes]

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?

[penelopeysm]

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.

[penelopeysm]

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)

[penelopeysm]

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.

[penelopeysm]

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.

[penelopeysm]

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.

[penelopeysm]

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.

[penelopeysm]

Suggested change

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

This one is also very outdated