Add FAQ section to improve user guidance #608
Conversation
There was a problem hiding this comment.
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.qmdwith 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 itstext:line with the other menu entries.
- href: faq/
|
Preview the changes: https://turinglang.org/docs/pr-previews/608 |
There was a problem hiding this comment.
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
Outdated
| 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 |
There was a problem hiding this comment.
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.
faq/index.qmd
Outdated
| ## 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. |
There was a problem hiding this comment.
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.
Co-authored-by: Penelope Yong <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Penelope Yong <[email protected]>
…ing.jl models and parallelism usage
|
I think I've addressed the comments @penelopeysm |
| - **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. |
There was a problem hiding this comment.
| 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. |
faq/index.qmd
Outdated
| parameters { | ||
| real mu; | ||
| real<lower=0> sigma; | ||
| } | ||
| model { | ||
| y ~ normal(mu, sigma); | ||
| } | ||
| ``` |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
updated this in the next commit - just pushed
Co-authored-by: Penelope Yong <[email protected]>
Co-authored-by: Penelope Yong <[email protected]>
Co-authored-by: Penelope Yong <[email protected]>
Co-authored-by: Penelope Yong <[email protected]>
Co-authored-by: Penelope Yong <[email protected]>
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: