Merge pull request #427 from vpratz/docs-migration-advice

Add advice regarding moving from v1 to v2 to README.

Author: vpratz

README.md

@@ -15,6 +15,19 @@ It provides users and researchers with:
 BayesFlow (version 2+) is designed to be a flexible and efficient tool that enables rapid statistical inference
 fueled by continuous progress in generative AI and Bayesian inference.
 
+## Important Note for Existing Users
+
+You are currently looking at BayesFlow 2.0+, which is a complete rewrite of the library.
+While it shares the same overall goals with the 1.x versions, the API is not compatible.
+
+> [!CAUTION]
+> A few features, most notably hierarchical models, have not been ported to BayesFlow 2.0+
+> yet. We are working on those features and plan to add them soon. You can find the complete
+> list in the [FAQ](#faq) below.
+
+The [Moving from BayesFlow v1.1 to v2.0](examples/From_BayesFlow_1.1_to_2.0.ipynb) guide
+highlights how concepts and classes relate between the two versions.
+
 ## Conceptual Overview
 
 <div align="center">
@@ -216,11 +229,47 @@ while the old version was based on TensorFlow.
 
 -------------
 
+**Question:**
+Should I switch to BayesFlow 2.0+ now? Are there features that are still missing?
+
+**Answer:**
+In general, we recommend to switch, as the new version is easier to use and will continue
+to receive improvements and new features. However, a few features are still missing, so you
+might want to wait until everything you need has been ported to BayesFlow 2.0+.
+
+Depending on your needs, you might not want to upgrade yet if one of the following applies:
+
+- You have an ongoing project that uses BayesFlow 1.x, and you do not want to allocate
+  time for migrating it to the new API.
+- You have already trained models in BayesFlow 1.x, that you do not want to re-train
+  with the new version. Loading models from version 1.x in version 2.0+ is not supported.
+- You require a feature that was not ported to BayesFlow 2.0+ yet. To our knowledge,
+  this applies to:
+  * Two-level/Hierarchical models: `TwoLevelGenerativeModel`, `TwoLevelPrior`.
+  * Sensitivity analysis: functionality from the `bayesflow.sensitivity` module.
+  * MCMC (discontinued): The `bayesflow.mcmc` module. We are considering other options
+    to enable the use of BayesFlow in an MCMC setting.
+  * Networks: `EvidentialNetwork`.
+  * Model misspecification detection: MMD test in the summary space (see #384).
+
+If you encounter any functionality that is missing and not listed here, please let us
+know by opening an issue.
+
+-------------
+
 **Question:**
 I still need the old BayesFlow for some of my projects. How can I install it?
 
 **Answer:**
 You can find and install the old Bayesflow version via the `stable-legacy` branch on GitHub.
+The corresponding [documentation](https://bayesflow.org/stable-legacy/index.html) can be
+accessed by selecting the "stable-legacy" entry in the version picker of the documentation.
+
+You can also install the latest version of BayesFlow v1.x from PyPI using
+
+```
+pip install "bayesflow<2.0"
+```
 
 -------------
 

docsrc/source/index.md

@@ -10,6 +10,9 @@ It provides users and researchers with:
 BayesFlow (version 2+) is designed to be a flexible and efficient tool that enables rapid statistical inference
 fueled by continuous progress in generative AI and Bayesian inference.
 
+To access the documentation for [BayesFlow version 1.x](https://github.com/bayesflow-org/bayesflow/tree/stable-legacy), select `stable-legacy` in the version picker above.
+For advice on the migration from version 1.x to version 2+, please refer to the [README](https://github.com/bayesflow-org/bayesflow/blob/main/README.md).
+
 ## Conceptual Overview
 
 <div align="center">