Add Performance Tips and FAQ (#502)

bvdmitri · albertpod · web-flow · commit 2ccbafde3ed0 · 2025-08-28T20:25:34.000+02:00
* add perf tips and faq * Apply suggestion from @albertpod Co-authored-by: Albert <albert.podusenko@gmail.com> * Apply suggestion from @albertpod Co-authored-by: Albert <albert.podusenko@gmail.com> * Apply suggestion from @albertpod Co-authored-by: Albert <albert.podusenko@gmail.com> * links * Apply suggestion from @albertpod Co-authored-by: Albert <albert.podusenko@gmail.com> * Apply suggestion from @albertpod Co-authored-by: Albert <albert.podusenko@gmail.com> * Apply suggestion from @albertpod Co-authored-by: Albert <albert.podusenko@gmail.com> * fix link * missing cross references --------- Co-authored-by: Albert <albert.podusenko@gmail.com>
diff --git a/Makefile b/Makefile
@@ -46,6 +46,9 @@ dev_doc_init:
 docs: doc_init ## Generate documentation
 	julia --startup-file=no --project=docs/ docs/make.jl
 
+docs-serve: doc_init ## Serve documentation locally for preview in browser, requires `LiveServer.jl` installed globally
+	julia --project=docs/ -e 'ENV["DOCS_DRAFT"]="true"; using LiveServer; LiveServer.servedocs(launch_browser=true, port=5678)'
+
 devdocs: dev_doc_init ## Same as `make docs` but uses `dev-ed` versions of core packages
 	julia --startup-file=no --project=docs/ docs/make.jl
 
diff --git a/docs/make.jl b/docs/make.jl
@@ -13,7 +13,7 @@ draft = get(ENV, "DOCS_DRAFT", "false") == "true"
 
 makedocs(;
     draft = draft,
-    warnonly = false,
+    warnonly = draft,
     modules = [RxInfer],
     authors = "Bagaev Dmitry <d.v.bagaev@tue.nl> and contributors",
     sitename = "RxInfer.jl",
@@ -49,6 +49,8 @@ makedocs(;
             ],
             "Inference customization" =>
                 ["Defining a custom node and rules" => "manuals/customization/custom-node.md", "Inference results postprocessing" => "manuals/customization/postprocess.md"],
+            "Performance Tips" => "manuals/performance-tips.md",
+            "FAQ" => "manuals/faq.md",
             "Debugging" => "manuals/debugging.md",
             "Session summary" => "manuals/session_summary.md",
             "Sharing sessions & telemetry" => "manuals/telemetry.md",
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -74,6 +74,8 @@ Pages = [
   "manuals/meta-specification.md",
   "manuals/inference-execution.md",
   "manuals/custom-node.md",
+  "manuals/performance-tips.md",
+  "manuals/faq.md",
   "manuals/debugging.md",
   "manuals/delta-node.md",
   "manuals/how-to-use-rxinfer-from-python.md",
diff --git a/docs/src/manuals/faq.md b/docs/src/manuals/faq.md
@@ -0,0 +1,111 @@
+# [Frequently Asked Questions (FAQ)](@id user-guide-faq)
+
+This section addresses common questions and issues that users encounter when working with RxInfer. The FAQ is a living document that grows based on community feedback and common usage patterns.
+
+## General Questions
+
+### What is RxInfer?
+
+RxInfer is a Julia package for automated Bayesian inference on factor graphs using reactive message passing. It provides an efficient, scalable framework for probabilistic programming with a focus on streaming data.
+
+### How does RxInfer compare to other probabilistic programming packages?
+
+See our detailed [comparison guide](@ref comparison) for a comprehensive analysis of RxInfer vs. other tools like Turing.jl, Stan, and PyMC.
+
+### Is RxInfer suitable for beginners?
+
+Yes! RxInfer provides a user-friendly syntax through GraphPPL and comprehensive documentation. Start with the [Getting Started](@ref user-guide-getting-started) guide and work through examples.
+
+## Installation and Setup
+
+See [Installation](@ref user-guide-getting-started-installation) for details.
+
+### I'm getting dependency conflicts. What should I do?
+
+Try `Pkg.resolve()` to resolve conflicts. See [Pkg.jl](https://pkgdocs.julialang.org/v1/getting-started/) for more details.
+
+### Can I use RxInfer from Python?
+
+Yes! See our guide on [Using RxInfer from Python](@ref python-usage).
+
+## Model Specification
+
+### What's the difference between `=` and `:=` in model specification?
+
+- `=` is a regular Julia assignment operator, use it only for regular Julia variables
+- `:=` creates a random variable node, use it to create latent variables in your model
+
+See [Sharp Bits: Using `=` instead of `:=`](@ref usage-colon-equality) for details.
+
+### How do I handle missing/incomplete data?
+
+RxInfer supports missing data through the `missing` value in Julia. The inference engine will automatically handle missing observations. See [Missing Data](@ref manual-static-inference-missing-data) for details.
+
+### How do I create custom nodes and message update rules?
+
+See [Custom Node and Rules](@ref create-node) for detailed guidance on extending RxInfer.
+
+## Inference Issues
+
+### I'm getting "Rule not found" errors. What does this mean?
+
+This error occurs when RxInfer can't find appropriate message update rules for your model. See [Rule Not Found Error](@ref rule-not-found) for solutions.
+
+### "Stack overflow in inference"
+
+See [Stack Overflow during inference](@ref stack-overflow-inference) for more details.
+
+### My inference is running very slowly. How can I improve performance?
+
+Check our [Performance Tips](@ref user-guide-performance-tips) section for optimization strategies.
+
+### How do I debug inference problems?
+
+Check out the [Debugging](@ref user-guide-debugging) guide.
+
+## Performance and Scaling
+
+### How large can my models be?
+
+RxInfer can handle models with millions of latent variables. Performance depends on:
+- Model complexity (e.g. simple models with conjugate pairs of distributions are the fastest)
+- Available memory (large models require more memory)
+- Computational resources (more cores, more memory, faster CPU, etc.)
+- Optimization techniques used (see [Performance Tips](@ref user-guide-performance-tips))
+
+### Can I use RxInfer for real-time applications?
+
+Yes! RxInfer is designed for real-time inference with reactive message passing. See our [streaming inference](@ref manual-online-inference) documentation.
+
+## Community and Support
+
+### Where can I get help?
+
+1. **Documentation**: Start with the relevant sections in the [User Guide](@ref user-guide-getting-started)
+2. **GitHub Discussions**: [Ask](https://github.com/ReactiveBayes/RxInfer.jl/discussions) questions and share experiences
+3. **Issues**: [Report](https://github.com/ReactiveBayes/RxInfer.jl/issues) bugs and request features
+4. **Community Meetings**: Join regular public discussions, more info [here](https://dynalist.io/d/F4aA-Z2c8X-M1iWTn9hY_ndN)
+
+### How can I contribute?
+
+See our [Contributing Guide](@ref contributing-guidelines) for ways to help. Any help is welcome!
+
+## Contributing to the FAQ
+
+This FAQ grows through community contributions! If you have questions that aren't covered here:
+
+1. **Check existing discussions** on GitHub
+2. **Ask your question** in GitHub Discussions
+3. **Consider contributing** the answer back to this FAQ
+4. **Open an issue** if you find a documentation gap
+
+### How to add questions to the FAQ
+
+1. Open a discussion or issue with your question
+2. If it's a common question, consider adding it here
+3. Follow the [Contributing to Documentation](@ref guide-docs-contributing) guide
+4. Use clear, concise language and include code examples when helpful
+
+---
+
+**Note**: This FAQ is maintained by the community. For the most up-to-date information, check GitHub discussions and issues. If you find outdated information, please help us keep it current!
diff --git a/docs/src/manuals/getting-started.md b/docs/src/manuals/getting-started.md
@@ -8,7 +8,7 @@ It supports both exact and variational inference algorithms and forms an ecosyst
 
 This page provides the necessary information you need to get started with `Rxinfer`. We will show the general approach to solving inference problems with `RxInfer` by means of a running example: inferring the bias of a coin using a simple Beta-Bernoulli model.
 
-## Installation
+## [Installation](@id user-guide-getting-started-installation)
 
 `RxInfer` is an officially registered Julia package. Install `RxInfer` through the Julia package manager by using the following command from the package manager mode:
 
diff --git a/docs/src/manuals/how-to-use-rxinfer-from-python.md b/docs/src/manuals/how-to-use-rxinfer-from-python.md
@@ -1,4 +1,4 @@
-# Using RxInfer from Python
+# [Using RxInfer from Python](@id python-usage)
 
 RxInfer can be used from Python through the [`RxInferServer.jl`](https://github.com/lazydynamics/RxInferServer) RESTful API and the [`RxInferClient.py`](https://github.com/lazydynamics/RxInferClient.py) Python SDK.
 
diff --git a/docs/src/manuals/inference/static.md b/docs/src/manuals/inference/static.md
@@ -95,7 +95,7 @@ p = plot!(p, rθ, (x) -> pdf(results.posteriors[:θ], x), title="Posterior", fil
 p = vline!(p, [ hidden_θ ], label = "Real (hidden) θ")
 ```
 
-### Missing data points and predictions
+### [Missing data points and predictions](@id manual-static-inference-missing-data)
 
 ```@example manual-static-inference
 result = infer(
diff --git a/docs/src/manuals/performance-tips.md b/docs/src/manuals/performance-tips.md
@@ -0,0 +1,58 @@
+# [Performance Tips](@id user-guide-performance-tips)
+
+This section provides practical advice and best practices for optimizing the performance of your RxInfer models. Following these guidelines can significantly improve inference speed and memory efficiency.
+
+!!! note 
+    Before diving into RxInfer-specific optimizations, we strongly recommend reading Julia's official [Performance Tips](https://docs.julialang.org/en/v1/manual/performance-tips/) guide. Many performance improvements come from following Julia's general best practices, such as avoiding global variables, using type stability, and minimizing allocations. The tips in this section build upon those fundamental principles.
+
+## Julia Compilation Latency
+
+Julia uses **Just-In-Time (JIT)** compilation. The **first time** you run a model and inference procedure, Julia compiles the specialized machine code. This can cause noticeable delays **only once**. Afterward, execution becomes much faster. This might be especially problematic for models and factor nodes that accept a dynamic number of arguments. Such nodes include mixture nodes (where the number of components is only known at compilation time) as well as deterministic nodes representing non-linear transformations (since those transformations can be arbitrary, their signature is only known at compilation time).
+
+**Tips:** 
+- Don't worry about long first-run times during development — focus on steady-state performance.
+- Use the `@time` macro from Julia to investigate the time spent on compilation and execution.
+
+## Model Structure Optimization
+
+RxInfer is designed for fast inference on factor graphs and leverages the model structure to optimize the inference procedure. However, it is always possible to create a huge model with complex dependencies between variables and make inference slow with RxInfer. 
+
+**General guidelines for model structure optimization:**
+
+### Choose Appropriate Parametrization for Your Nodes
+
+While confusing at first glance, the choice of parametrization for your nodes can have a significant impact on the performance of the inference procedure. For this reason, RxInfer allows you to choose, for example, between `NormalMeanPrecision` and `NormalMeanVariance` parametrizations for `Normal` nodes. Or, you can choose between `MvNormalMeanPrecision` and `MvNormalMeanScalePrecision` parametrizations for `MvNormal` nodes. The difference between these parametrizations is that the former needs to store the entire precision matrix, while the latter uses a single number to store the scale of the diagonal of the precision matrix.
+
+### Use Conjugate Pairs
+
+[Conjugate pairs](https://en.wikipedia.org/wiki/Conjugate_prior) enable analytical message updates. For example, a `Gamma` prior is appropriate for a `NormalMeanPrecision` node, but an `InverseGamma` is not. Conversely, an `InverseGamma` prior is appropriate for a `NormalMeanVariance` node, but a `Gamma` is not. Another example is that a `Beta` prior is appropriate for a `Bernoulli` node, but a `Binomial` is not. A `Wishart` prior is appropriate for an `MvNormalMeanPrecision` node, and an `InverseWishart` is appropriate for an `MvNormalMeanCovariance` node.  Note that the conjugacy also depends on the local factorization of your model. If you place priors on both the mean and the precision in `MvNormalMeanPrecision`, you must enforce independence (e.g., `q(μ,Λ)=q(μ)q(Λ)`) to make the model conditionally conjugate.
+### Be Aware of the Computational Overhead of Deterministic Nodes
+
+Each deterministic node adds computational overhead and requires approximation method specification. Read more about approximation methods in the [Deterministic nodes](@ref delta-node-manual) section. In some situations, however, it is possible to use specialized factor nodes instead of deterministic nodes. For example, the `SoftDot` node is a specialized factor node for computing the dot product of two vectors where the result is passed to a `Normal` node. Using `SoftDot` directly instead of `Normal(mean = dot(...), ...)` can significantly improve both the performance and accuracy of the inference procedure. Similar applies to `ContinuousTransition` node.
+
+If a specialized node is not available, you can either [create one yourself](@ref create-node) or choose an appropriate approximation method for the deterministic node. For example, if all inputs to the non-linear transformation are known to be Gaussian, the fastest approximation method is probably `Linearization`. However, it requires the function to be differentiable and "nice" enough. More computationally expensive methods, such as `Unscented` or `CVIProjection`, are more robust and can be used in more general cases. We also suggest you to check [Fusing deterministic transformations with stochastic nodes](@ref inference-undefinedrules-fusedelta) example that provides additional tricks.
+
+### Smoothing vs. Filtering
+
+It might be appropriate to convert your model from operating on the whole dataset (smoothing) to operating on one observation at a time (filtering). Read more about smoothing in the [Static Inference](@ref manual-static-inference) section and about filtering in the [Online Inference](@ref manual-online-inference) section. It is also possible to combine both approaches and process data in batches.
+
+## Inference Procedure Optimization
+
+The [`infer`](@ref) function is the main entry point for inference in RxInfer.jl. It is a wrapper around the inference procedure and allows you to specify the inference algorithm, the number of iterations, the initial values for the parameters, and more. The default parameters are chosen to be a good compromise between speed and accuracy. However, in some situations, it is possible to improve the performance of the inference procedure by tuning the parameters.
+
+### Use `free_energy = Float64` Instead of `free_energy = true`
+
+By default, when computing free energy values, they are stored as an abstract type `Real` and are converted to `Float64` only when they are returned. This can be a significant overhead (read Julia's [Performance Tips](https://docs.julialang.org/en/v1/manual/performance-tips/#Avoid-unnecessary-type-conversions)), especially for large models. The reason for this choice is that in this case, the inference procedure can be auto-differentiated where free energy values serve as the objective function. If you do not plan to auto-differentiate the inference procedure, you can set `free_energy = Float64` to avoid the overhead of type conversions.
+
+### Be Aware of the Computational Overhead of the `limit_stack_depth` Option
+
+RxInfer provides a `limit_stack_depth` option to limit the depth of the stack of the inference procedure, which is explained in the [Stack Overflow during inference](@ref stack-overflow-inference) section. This can be useful to avoid stack overflows, but it can also significantly degrade the performance of the inference procedure. The larger the value, the less the performance is degraded. You can tune the value based on the size of your model as well as your computer. The optimal value differs for different models and computers.
+
+## Getting Help
+
+If you encounter performance issues:
+
+1. **Check the documentation**: Review relevant sections for optimization tips
+2. **Use the community**: Open discussions on GitHub for specific issues
+3. **Profile your code**: Use Julia's profiling tools to identify bottlenecks
+4. **Start simple**: Build complexity gradually to identify performance issues

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Using RxInfer from Python`
	`1`	`+# [Using RxInfer from Python](@id python-usage)`
`2`	`2`
`3`	`3`	RxInfer can be used from Python through the [`RxInferServer.jl`](https://github.com/lazydynamics/RxInferServer) RESTful API and the [`RxInferClient.py`](https://github.com/lazydynamics/RxInferClient.py) Python SDK.
`4`	`4`