Add FAQ section to improve user guidance #608

AoifeHughes · 2025-06-03T12:01:34Z

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:

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/

faq/index.qmd

github-actions · 2025-06-03T12:05:12Z

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).

faq/index.qmd

Co-authored-by: Penelope Yong <penelopeysm@gmail.com>

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Co-authored-by: Penelope Yong <penelopeysm@gmail.com>

…ing.jl models and parallelism usage

AoifeHughes · 2025-07-02T10:50:53Z

I think I've addressed the comments @penelopeysm

penelopeysm

Looking good! Thanks for expanding on the points here. A few more comments, which hopefully aren't too complicated to deal with.

penelopeysm · 2025-07-03T13:18:20Z

faq/index.qmd

+@model function f(x)
+    Threads.@threads for i in eachindex(x)
+        x[i] ~ Normal()  # UNSAFE: Assume statements in threads can crash!
+    end
+end


In this model, x is observed so it's fine. 'assume' means that it's a random parameter, so for example something like this:

Suggested change

@model function f(x)

Threads.@threads for i in eachindex(x)

x[i] ~ Normal() # UNSAFE: Assume statements in threads can crash!

end

end

@model function f(y)

x = Vector{Float64}(undef, length(y))

Threads.@threads for i in eachindex(y)

x[i] ~ Normal() # UNSAFE: `assume` statements in @threads can crash!

y[i] ~ Normal(x[i]) # `observe` statements are okay

end

end

penelopeysm · 2025-07-03T13:19:53Z

faq/index.qmd

+- **Multithreaded sampling**: Use `MCMCThreads()` to run one chain per thread
+- **Distributed sampling**: Use `MCMCDistributed()` for distributed computing
+
+See the [Core Functionality guide](../core-functionality/#sampling-multiple-chains) for examples.


Suggested change

See the [Core Functionality guide](../core-functionality/#sampling-multiple-chains) for examples.

See the [Core Functionality guide]({{< meta core-functionality >}}/#sampling-multiple-chains) for examples.

penelopeysm · 2025-07-03T13:20:23Z

faq/index.qmd

+The key insight is that `filldist` creates a single distribution (not N independent distributions), which is why you cannot condition on individual elements. The distinction is not just about what appears on the LHS of `~`, but whether you're dealing with separate distributions (`.~` with univariate) or a single distribution over multiple values (`~` with multivariate or `filldist`).
+
+To understand more about how Turing determines whether a variable is treated as random or observed, see:
+- [Core Functionality](../core-functionality/) - basic explanation of the `~` notation and conditioning


Suggested change

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

- [Core Functionality]({{< meta core-functionality >}}) - basic explanation of the `~` notation and conditioning

penelopeysm · 2025-07-03T13:21:56Z

faq/index.qmd

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


Suggested change

- For more advanced debugging, DynamicPPL provides `DynamicPPL.DebugUtils` for inspecting model internals

- For more advanced debugging, DynamicPPL provides [the `DynamicPPL.DebugUtils` module](https://turinglang.org/DynamicPPL.jl/stable/api/#Debugging-Utilities) for inspecting model internals

Friendly link

penelopeysm · 2025-07-03T13:22:24Z

faq/index.qmd

+
+Key syntactic differences include:
+
+- **Parameter blocks**: Stan requires explicit `data`, `parameters`, `transformed parameters`, and `model` blocks. In Turing, everything is defined within the `@model` macro


Suggested change

- **Parameter blocks**: Stan requires explicit `data`, `parameters`, `transformed parameters`, and `model` blocks. In Turing, everything is defined within the `@model` macro

- **Parameter blocks**: Stan requires explicit `data`, `parameters`, and `model` blocks. In Turing, everything is defined within the `@model` macro

transformed parameters isn't mandatory

penelopeysm · 2025-07-03T13:23:47Z

faq/index.qmd

+# Turing
+@model function my_model(y)
+    mu ~ Normal(0, 1)
+    sigma ~ truncated(Normal(0, 1), 0, Inf)


Suggested change

sigma ~ truncated(Normal(0, 1), 0, Inf)

sigma ~ truncated(Normal(0, 1); lower=0)

truncated(d, 0, Inf) causes issues with AD (https://turinglang.org/docs/usage/troubleshooting/#nan-gradient has an illustration of this).

penelopeysm · 2025-07-03T13:32:56Z

faq/index.qmd

+parameters {
+  real mu;
+  real<lower=0> sigma;
+}
+model {
+  y ~ normal(mu, sigma);
+}
+```


So I'm not a super duper expert on Stan, but I think that these parameters don't have priors assigned and thus have completely flat priors (i.e. the prior probability is always 1 for any value of mu and any value of sigma > 0). That would make this not equivalent to the Turing model which has non-flat priors. I think you would need to specify mu ~ normal(0, 1); and sigma ~ normal(0, 1); if you want to include a prior probability that is equivalent to the Turing model below it.

Add FAQ section to improve user guidance

978017b

AoifeHughes requested a review from Copilot June 3, 2025 12:01

AoifeHughes added the enhancement New feature or request label Jun 3, 2025

Copilot AI reviewed Jun 3, 2025

View reviewed changes

faq/index.qmd Outdated Show resolved Hide resolved

AoifeHughes mentioned this pull request Jun 3, 2025

Introduce a docs FAQ section TuringLang/Turing.jl#2431

Open

9 tasks

AoifeHughes marked this pull request as ready for review June 4, 2025 08:49

AoifeHughes self-assigned this Jun 4, 2025

AoifeHughes requested a review from penelopeysm June 4, 2025 08:52

penelopeysm requested changes Jun 16, 2025

View reviewed changes

penelopeysm reviewed Jun 16, 2025

View reviewed changes

faq/index.qmd Outdated Show resolved Hide resolved

AoifeHughes and others added 6 commits June 17, 2025 10:11

Update faq/index.qmd

d9a46e3

Co-authored-by: Penelope Yong <penelopeysm@gmail.com>

Update faq/index.qmd

41ab37b

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update faq/index.qmd

2b97c35

Co-authored-by: Penelope Yong <penelopeysm@gmail.com>

Enhance FAQ section with detailed explanations on conditioning in Tur…

6ec9c7e

…ing.jl models and parallelism usage

formatter wanted to fix this

571c44a

Merge branch 'main' into faq

6c6e32f

AoifeHughes requested a review from penelopeysm July 2, 2025 10:50

penelopeysm requested changes Jul 3, 2025

View reviewed changes

-@model function f(x)
-    Threads.@threads for i in eachindex(x)
-        x[i] ~ Normal()  # UNSAFE: Assume statements in threads can crash!
-    end
-end
+@model function f(y)
+    x = Vector{Float64}(undef, length(y))
+    Threads.@threads for i in eachindex(y)
+        x[i] ~ Normal()  # UNSAFE: `assume` statements in @threads can crash!
+        y[i] ~ Normal(x[i])  # `observe` statements are okay
+    end
+end

	See the [Core Functionality guide](../core-functionality/#sampling-multiple-chains) for examples.
	See the [Core Functionality guide]({{< meta core-functionality >}}/#sampling-multiple-chains) for examples.

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

	- For more advanced debugging, DynamicPPL provides `DynamicPPL.DebugUtils` for inspecting model internals
	- For more advanced debugging, DynamicPPL provides [the `DynamicPPL.DebugUtils` module](https://turinglang.org/DynamicPPL.jl/stable/api/#Debugging-Utilities) for inspecting model internals


		Key syntactic differences include:

		- Parameter blocks: Stan requires explicit `data`, `parameters`, `transformed parameters`, and `model` blocks. In Turing, everything is defined within the `@model` macro

	sigma ~ truncated(Normal(0, 1), 0, Inf)
	sigma ~ truncated(Normal(0, 1); lower=0)

Add FAQ section to improve user guidance #608

Are you sure you want to change the base?

Add FAQ section to improve user guidance #608

Uh oh!

Conversation

AoifeHughes commented Jun 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Website Navigation Update:

FAQ Section Addition:

Relevant Issues:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

github-actions bot commented Jun 3, 2025

Uh oh!

penelopeysm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AoifeHughes commented Jul 2, 2025

Uh oh!

penelopeysm left a comment

Choose a reason for hiding this comment

Uh oh!

penelopeysm Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

penelopeysm Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

penelopeysm Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

penelopeysm Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

penelopeysm Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

penelopeysm Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

penelopeysm Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AoifeHughes commented Jun 3, 2025 •

edited

Loading

penelopeysm Jul 3, 2025 •

edited

Loading

penelopeysm Jul 3, 2025 •

edited

Loading

penelopeysm Jul 3, 2025 •

edited

Loading