Merge remote-tracking branch 'upstream/dev' into dev

Author: eodole

.github/workflows/multiversion-docs.yaml

@@ -6,7 +6,8 @@ on:
   workflow_dispatch:
   push:
     branches:
-      - dev
+      - main
+      - stable-legacy
 
 jobs:
 
@@ -17,16 +18,11 @@ jobs:
       - name: Checkout main
         uses: actions/checkout@v3
         with:
-          path: dev
+          path: repo
+          ref: main
           fetch-depth: 0
           fetch-tags: true
 
-      - name: Checkout gh-pages-dev
-        uses: actions/checkout@v3
-        with:
-          path: gh-pages-dev
-          ref: gh-pages-dev
-
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
@@ -35,22 +31,31 @@ jobs:
 
       - name: Install dependencies
         run: |
-          cd ./dev
+          cd ./repo
           python -m pip install .[docs]
+
       - name: Create local branches
         run: |
-          cd ./dev
-          git branch main remotes/origin/main
+          cd ./repo
+          git branch stable-legacy remotes/origin/stable-legacy
+
       - name: Make the Sphinx docs
         run: |
-          cd ./dev/docsrc
+          cd ./repo/docsrc
           make clean
           make docs-sequential
+
+      - name: Checkout gh-pages-dev
+        uses: actions/checkout@v3
+        with:
+          path: gh-pages-dev
+          ref: gh-pages-dev
+
       - name: Commit changes to docs
         run: |
           cd ./gh-pages-dev
           git rm --quiet -rf .
-          cp -R ../dev/docs/* ./
+          cp -R ../repo/docs/* ./
           git config --local user.email ""
           git config --local user.name "github-actions"
           git add -A

.github/workflows/test-docs.yaml

@@ -5,6 +5,7 @@ on:
   pull_request:
     branches:
       - dev
+      - main
 
 jobs:
   build_docs:

.github/workflows/tests.yaml

@@ -2,12 +2,15 @@
 name: Tests
 
 on:
+  workflow_dispatch:
   pull_request:
+    branches:
+      - main
+      - dev
   push:
     branches:
       - main
       - dev
-      - streamlined-backend
 
 
 jobs:
@@ -82,7 +85,7 @@ jobs:
       - name: Install PyTorch
         if: ${{ matrix.backend == 'torch' }}
         run: |
-          conda install pytorch torchvision torchaudio cpuonly -c pytorch
+          pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
 
       - name: Show Environment Info
         run: |
@@ -92,6 +95,7 @@ jobs:
           conda config --show
           printenv | sort
           conda env export
+          pip list
 
       - name: Run Tests
         run: |
@@ -101,6 +105,12 @@ jobs:
         run: |
           coverage xml
 
+      - name: Upload test results to Codecov
+        if: ${{ !cancelled() }}
+        uses: codecov/test-results-action@v1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
       - name: Upload Coverage Reports to CodeCov
         uses: codecov/codecov-action@v4
         with:

README.md

@@ -1,17 +1,17 @@
 # BayesFlow <img src="img/bayesflow_hex.png" style="float: right; width: 20%; height: 20%;" align="right" alt="BayesFlow Logo" />
 ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/bayesflow-org/bayesflow/tests.yaml?style=for-the-badge&label=Tests)
-![Codecov](https://img.shields.io/codecov/c/github/bayesflow-org/bayesflow/dev?style=for-the-badge)
+![Codecov](https://img.shields.io/codecov/c/github/bayesflow-org/bayesflow?style=for-the-badge&link=https%3A%2F%2Fapp.codecov.io%2Fgh%2Fbayesflow-org%2Fbayesflow%2Ftree%2Fmain)
 [![DOI](https://img.shields.io/badge/DOI-10.21105%2Fjoss.05702-blue?style=for-the-badge)](https://doi.org/10.21105/joss.05702)
 ![PyPI - License](https://img.shields.io/pypi/l/bayesflow?style=for-the-badge)
 
-BayesFlow 2 is a Python library for simulation-based **Amortized Bayesian Inference** with neural networks.
+BayesFlow is a Python library for simulation-based **Amortized Bayesian Inference** with neural networks.
 It provides users and researchers with:
 
 - A user-friendly API for rapid Bayesian workflows
 - A rich collection of neural network architectures
 - Multi-backend support via [Keras3](https://keras.io/keras_3/): You can use [PyTorch](https://github.com/pytorch/pytorch), [TensorFlow](https://github.com/tensorflow/tensorflow), or [JAX](https://github.com/google/jax)
 
-BayesFlow is designed to be a flexible and efficient tool that enables rapid statistical inference
+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.
 
 ## Conceptual Overview
@@ -49,7 +49,7 @@ history = workflow.fit_online(epochs=50, batch_size=32, num_batches_per_epoch=50
 diagnostics = workflow.plot_default_diagnostics(test_data=300)
 ```
 
-For an in-depth exposition, check out our walkthrough notebooks below. More tutorials are always welcome!
+For an in-depth exposition, check out our walkthrough notebooks below.
 
 1. [Linear regression starter example](examples/Linear_Regression_Starter.ipynb)
 2. [From ABC to BayesFlow](examples/From_ABC_to_BayesFlow.ipynb)
@@ -59,6 +59,8 @@ For an in-depth exposition, check out our walkthrough notebooks below. More tuto
 6. [Bayesian experimental design](examples/Bayesian_Experimental_Design.ipynb)
 7. [Simple model comparison example](examples/One_Sample_TTest.ipynb)
 
+More tutorials are always welcome! Please consider making a pull request if you have a cool application that you want to contribute.
+
 ## Install
 
 ### Backend
@@ -69,9 +71,8 @@ First, install one machine learning backend of choice. Note that BayesFlow **wil
 - [Install PyTorch](https://pytorch.org/get-started/locally/)
 - [Install TensorFlow](https://www.tensorflow.org/install)
 
-If you don't know which backend to use, we recommend JAX to get started.
-It is the fastest backend and already works pretty reliably with the current
-dev version of bayesflow.
+If you don't know which backend to use, we recommend JAX as it is currently
+the fastest backend.
 
 Once installed, [set the backend environment variable as required by keras](https://keras.io/getting_started/#configuring-your-backend). For example, inside your Python script write:
 
@@ -93,22 +94,22 @@ This way, you also don't have to manually set the backend every time you are sta
 
 ### Using pip
 
-You can install the dev version with pip:
+You can install the Bayesflow from Github with pip:
 
 ```bash
-pip install git+https://github.com/bayesflow-org/bayesflow@dev
+pip install git+https://github.com/bayesflow-org/bayesflow@main
 ```
 
-### Using Conda (coming soon)
+### Using Conda
 
-The dev version is not conda-installable yet.
+Bayesflow is currently not conda-installable.
 
 ### From Source
 
-If you want to contribute to BayesFlow, we recommend installing the dev branch from source:
+If you want to contribute to BayesFlow, we recommend installing it from source:
 
 ```bash
-git clone -b dev [email protected]:bayesflow-org/bayesflow.git
+git clone -b main [email protected]:bayesflow-org/bayesflow.git
 cd <local-path-to-bayesflow-repository>
 conda env create --file environment.yaml --name bayesflow
 ```
@@ -167,10 +168,24 @@ You can cite BayesFlow along the lines of:
 }
 ```
 
+## FAQ
+
+- *I am starting with Bayesflow, which backend shall I use?*
+**A**: We recommend JAX as it is currently the fastest backend.
+
+- *What is the difference between Bayesflow 2.0+ and previous versions?*
+**A**: BayesFlow 2.0+ is a complete rewrite of the library. It shares the same
+overall goals with previous versions, but has much better modularity
+and extensibility. What is more, the new BayesFlow has multi-backend support via Keras3,
+while the old version was based on TensorFlow.
+
+- *I still need the old BayesFlow for some of my projects. How can I install it?*
+**A**: You can find and install the old Bayesflow version via the `stable-legacy` branch on GitHub.
+
 ## Awesome Amortized Inference
 
 If you are interested in a curated list of resources, including reviews, software, papers, and other resources related to amortized inference, feel free to explore our [community-driven list](https://github.com/bayesflow-org/awesome-amortized-inference).
 
 ## Acknowledgments
 
-This project is currently managed by researchers from Rensselaer Polytechnic Institute, TU Dortmund University, and Heidelberg University. It is partially funded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation, Project 528702768). The project is further supported by Germany's Excellence Strategy -- EXC-2075 - 390740016 (Stuttgart Cluster of Excellence SimTech) and EXC-2181 - 390900948 (Heidelberg Cluster of Excellence STRUCTURES), as well as the Informatics for Life initiative funded by the Klaus Tschira Foundation.
+This project is currently managed by researchers from Rensselaer Polytechnic Institute, TU Dortmund University, and Heidelberg University. It is partially funded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) Projects 528702768 and 508399956. The project is further supported by Germany's Excellence Strategy -- EXC-2075 - 390740016 (Stuttgart Cluster of Excellence SimTech) and EXC-2181 - 390900948 (Heidelberg Cluster of Excellence STRUCTURES), the collaborative research cluster TRR 391 – 520388526, as well as the Informatics for Life initiative funded by the Klaus Tschira Foundation.

bayesflow/adapters/adapter.py

@@ -241,7 +241,7 @@ def apply(
         exclude: str | Sequence[str] = None,
         **kwargs,
     ):
-        """Append a :py:class:`~transforms.LambdaTransform` to the adapter.
+        """Append a :py:class:`~transforms.NumpyTransform` to the adapter.
 
         Parameters
         ----------

bayesflow/adapters/transforms/numpy_transform.py

@@ -9,7 +9,7 @@ class NumpyTransform(ElementwiseTransform):
     """
     A class to apply element-wise transformations using plain NumPy functions.
 
-    Attributes:
+    Attributes
     ----------
     _forward : str
         The name of the NumPy function to apply in the forward transformation.
@@ -31,11 +31,11 @@ def __init__(self, forward: str, inverse: str = None):
         """
         Initializes the NumpyTransform with specified forward and inverse functions.
 
-        Parameters:
+        Parameters
         ----------
-        forward: str
+        forward : str
             The name of the NumPy function to use for the forward transformation.
-        inverse: str, optional
+        inverse : str, optional
             The name of the NumPy function to use for the inverse transformation.
             By default, the inverse is inferred from the forward argument for supported methods.
         """

bayesflow/approximators/point_approximator.py

@@ -23,17 +23,17 @@ def estimate(
         conditions: dict[str, np.ndarray],
         split: bool = False,
         **kwargs,
-    ) -> dict[str, dict[str, np.ndarray]]:
+    ) -> dict[str, dict[str, np.ndarray | dict[str, np.ndarray]]]:
         """
-        Provides point estimates based on provided conditions (e.g., observables).
+        Estimates point summaries of inference variables based on specified conditions.
 
         This method processes input conditions, computes estimates, applies necessary adapter transformations,
         and optionally splits the resulting arrays along the last axis.
 
         Parameters
         ----------
         conditions : dict[str, np.ndarray]
-            A dictionary mapping variable names to NumPy arrays representing the conditions
+            A dictionary mapping variable names to arrays representing the conditions
             for the estimation process.
         split : bool, optional
             If True, the estimated arrays are split along the last axis, by default False.
@@ -42,9 +42,15 @@ def estimate(
 
         Returns
         -------
-        dict[str, dict[str, np.ndarray]]
-            A nested dictionary where the top-level keys correspond to original variable names,
-            and values contain dictionaries mapping estimation results to NumPy arrays.
+        estimates : dict[str, dict[str, np.ndarray or dict[str, np.ndarray]]]
+            The estimates of inference variables in a nested dictionary.
+
+            1. Each first-level key is the name of an inference variable.
+            2. Each second-level key is the name of a scoring rule.
+            3. (If the scoring rule comprises multiple estimators, each third-level key is the name of an estimator.)
+
+            Each estimator output (i.e., dictionary value that is not itself a dictionary) is an array
+            of shape (num_datasets, point_estimate_size, variable_block_size).
         """
 
         conditions = self._prepare_conditions(conditions, **kwargs)
@@ -67,39 +73,43 @@ def sample(
         conditions: dict[str, np.ndarray],
         split: bool = False,
         **kwargs,
-    ) -> dict[str, np.ndarray]:
+    ) -> dict[str, dict[str, np.ndarray]]:
         """
-        Generate samples from point estimates based on provided conditions. These samples
-        will generally not correspond to samples from the fully Bayesian posterior, since
-        they will assume some parametric form (e.g., Gaussian in the case of mean score).
+        Draws samples from a parametric distribution based on point estimates for given input conditions.
 
-        This method draws a specified number of samples according to the given conditions,
-        applies necessary transformations, and optionally splits the resulting arrays along the last axis.
+        These samples will generally not correspond to samples from the fully Bayesian posterior, since
+        they will assume some parametric form (e.g., multivariate normal when using the MultivariateNormalScore).
 
         Parameters
         ----------
         num_samples : int
             The number of samples to generate.
         conditions : dict[str, np.ndarray]
-            A dictionary mapping variable names to NumPy arrays representing the conditions
+            A dictionary mapping variable names to arrays representing the conditions
             for the sampling process.
         split : bool, optional
             If True, the sampled arrays are split along the last axis, by default False.
+            Currently not supported for `PointApproximator`.
         **kwargs
             Additional keyword arguments passed to underlying processing functions.
 
         Returns
         -------
-        dict[str, np.ndarray]
-            A dictionary where keys correspond to variable names and values are NumPy arrays
-            containing the generated samples.
-        """
+        samples : dict[str, np.ndarray or dict[str, np.ndarray]]
+            Samples for all inference variables and all parametric scoring rules in a nested dictionary.
+
+            1. Each first-level key is the name of an inference variable.
+            2. (If there are multiple parametric scores, each second-level key is the name of such a score.)
 
+            Each output (i.e., dictionary value that is not itself a dictionary) is an array
+            of shape (num_datasets, num_samples, variable_block_size).
+        """
         conditions = self._prepare_conditions(conditions, **kwargs)
         samples = self._sample(num_samples, **conditions, **kwargs)
         samples = self._apply_inverse_adapter_to_samples(samples, **kwargs)
         # Optionally split the arrays along the last axis.
         if split:
+            raise NotImplementedError("split=True is currently not supported for `PointApproximator`.")
             samples = split_arrays(samples, axis=-1)
         # Squeeze samples if there's only one key-value pair.
         samples = self._squeeze_samples(samples)