aspire-inference 0.1.0a7__tar.gz → 0.1.0a9__tar.gz

aspire_inference-0.1.0a9/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: aspire-inference
+Version: 0.1.0a9
+Summary: Accelerate Sequential Posterior Inference via REuse
+Author-email: "Michael J. Williams" <michaeljw1@googlemail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/mj-will/aspire
+Project-URL: Documentation, https://aspire.readthedocs.io/
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: array-api-compat
+Requires-Dist: wrapt
+Requires-Dist: h5py
+Provides-Extra: scipy
+Requires-Dist: scipy; extra == "scipy"
+Provides-Extra: jax
+Requires-Dist: jax; extra == "jax"
+Requires-Dist: jaxlib; extra == "jax"
+Requires-Dist: flowjax; extra == "jax"
+Provides-Extra: torch
+Requires-Dist: torch; extra == "torch"
+Requires-Dist: zuko; extra == "torch"
+Requires-Dist: tqdm; extra == "torch"
+Provides-Extra: minipcn
+Requires-Dist: minipcn; extra == "minipcn"
+Provides-Extra: emcee
+Requires-Dist: emcee; extra == "emcee"
+Provides-Extra: blackjax
+Requires-Dist: blackjax; extra == "blackjax"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-requires; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Dynamic: license-file
+
+# aspire: Accelerated Sequential Posterior Inference via REuse
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15658747.svg)](https://doi.org/10.5281/zenodo.15658747)
+[![PyPI](https://img.shields.io/pypi/v/aspire-inference)](https://pypi.org/project/aspire-inference/)
+[![Documentation Status](https://readthedocs.org/projects/aspire/badge/?version=latest)](https://aspire.readthedocs.io/en/latest/?badge=latest)
+![tests](https://github.com/mj-will/aspire/actions/workflows/tests.yml/badge.svg)
+
+
+aspire is a framework for reusing existing posterior samples to obtain new results at a reduced cost.
+
+## Installation
+
+aspire can be installed from PyPI using `pip`
+
+```
+pip install aspire-inference
+```
+
+**Important:** the name of `aspire` on PyPI is `aspire-inference` but once installed
+the package can be imported and used as `aspire`.
+
+## Quickstart
+
+```python
+import numpy as np
+from aspire import Aspire, Samples
+
+# Define a log-likelihood and log-prior
+def log_likelihood(samples):
+    x = samples.x
+    return -0.5 * np.sum(x**2, axis=-1)
+
+def log_prior(samples):
+    return -0.5 * np.sum(samples.x**2, axis=-1)
+
+# Create the initial samples
+init = Samples(np.random.normal(size=(2_000, 4)))
+
+# Define the aspire object
+aspire = Aspire(
+    log_likelihood=log_likelihood,
+    log_prior=log_prior,
+    dims=4,
+    parameters=[f"x{i}" for i in range(4)],
+)
+
+# Fit the normalizing flow
+aspire.fit(init, n_epochs=20)
+
+# Sample the posterior
+posterior = aspire.sample_posterior(
+    sampler="smc",
+    n_samples=500,
+    sampler_kwargs=dict(n_steps=100),
+)
+
+# Plot the posterior distribution
+posterior.plot_corner()
+```
+
+## Documentation
+
+See the [documentation on ReadTheDocs][docs].
+
+## Citation
+
+If you use `aspire` in your work please cite the [DOI][DOI] and [paper][paper].
+
+
+[docs]: https://aspire.readthedocs.io/
+[DOI]: https://doi.org/10.5281/zenodo.15658747
+[paper]: https://arxiv.org/abs/2511.04218

aspire_inference-0.1.0a9/README.md

@@ -0,0 +1,72 @@
+# aspire: Accelerated Sequential Posterior Inference via REuse
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15658747.svg)](https://doi.org/10.5281/zenodo.15658747)
+[![PyPI](https://img.shields.io/pypi/v/aspire-inference)](https://pypi.org/project/aspire-inference/)
+[![Documentation Status](https://readthedocs.org/projects/aspire/badge/?version=latest)](https://aspire.readthedocs.io/en/latest/?badge=latest)
+![tests](https://github.com/mj-will/aspire/actions/workflows/tests.yml/badge.svg)
+
+
+aspire is a framework for reusing existing posterior samples to obtain new results at a reduced cost.
+
+## Installation
+
+aspire can be installed from PyPI using `pip`
+
+```
+pip install aspire-inference
+```
+
+**Important:** the name of `aspire` on PyPI is `aspire-inference` but once installed
+the package can be imported and used as `aspire`.
+
+## Quickstart
+
+```python
+import numpy as np
+from aspire import Aspire, Samples
+
+# Define a log-likelihood and log-prior
+def log_likelihood(samples):
+    x = samples.x
+    return -0.5 * np.sum(x**2, axis=-1)
+
+def log_prior(samples):
+    return -0.5 * np.sum(samples.x**2, axis=-1)
+
+# Create the initial samples
+init = Samples(np.random.normal(size=(2_000, 4)))
+
+# Define the aspire object
+aspire = Aspire(
+    log_likelihood=log_likelihood,
+    log_prior=log_prior,
+    dims=4,
+    parameters=[f"x{i}" for i in range(4)],
+)
+
+# Fit the normalizing flow
+aspire.fit(init, n_epochs=20)
+
+# Sample the posterior
+posterior = aspire.sample_posterior(
+    sampler="smc",
+    n_samples=500,
+    sampler_kwargs=dict(n_steps=100),
+)
+
+# Plot the posterior distribution
+posterior.plot_corner()
+```
+
+## Documentation
+
+See the [documentation on ReadTheDocs][docs].
+
+## Citation
+
+If you use `aspire` in your work please cite the [DOI][DOI] and [paper][paper].
+
+
+[docs]: https://aspire.readthedocs.io/
+[DOI]: https://doi.org/10.5281/zenodo.15658747
+[paper]: https://arxiv.org/abs/2511.04218

aspire_inference-0.1.0a9/aspire_inference.egg-info/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: aspire-inference
+Version: 0.1.0a9
+Summary: Accelerate Sequential Posterior Inference via REuse
+Author-email: "Michael J. Williams" <michaeljw1@googlemail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/mj-will/aspire
+Project-URL: Documentation, https://aspire.readthedocs.io/
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: array-api-compat
+Requires-Dist: wrapt
+Requires-Dist: h5py
+Provides-Extra: scipy
+Requires-Dist: scipy; extra == "scipy"
+Provides-Extra: jax
+Requires-Dist: jax; extra == "jax"
+Requires-Dist: jaxlib; extra == "jax"
+Requires-Dist: flowjax; extra == "jax"
+Provides-Extra: torch
+Requires-Dist: torch; extra == "torch"
+Requires-Dist: zuko; extra == "torch"
+Requires-Dist: tqdm; extra == "torch"
+Provides-Extra: minipcn
+Requires-Dist: minipcn; extra == "minipcn"
+Provides-Extra: emcee
+Requires-Dist: emcee; extra == "emcee"
+Provides-Extra: blackjax
+Requires-Dist: blackjax; extra == "blackjax"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-requires; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Dynamic: license-file
+
+# aspire: Accelerated Sequential Posterior Inference via REuse
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15658747.svg)](https://doi.org/10.5281/zenodo.15658747)
+[![PyPI](https://img.shields.io/pypi/v/aspire-inference)](https://pypi.org/project/aspire-inference/)
+[![Documentation Status](https://readthedocs.org/projects/aspire/badge/?version=latest)](https://aspire.readthedocs.io/en/latest/?badge=latest)
+![tests](https://github.com/mj-will/aspire/actions/workflows/tests.yml/badge.svg)
+
+
+aspire is a framework for reusing existing posterior samples to obtain new results at a reduced cost.
+
+## Installation
+
+aspire can be installed from PyPI using `pip`
+
+```
+pip install aspire-inference
+```
+
+**Important:** the name of `aspire` on PyPI is `aspire-inference` but once installed
+the package can be imported and used as `aspire`.
+
+## Quickstart
+
+```python
+import numpy as np
+from aspire import Aspire, Samples
+
+# Define a log-likelihood and log-prior
+def log_likelihood(samples):
+    x = samples.x
+    return -0.5 * np.sum(x**2, axis=-1)
+
+def log_prior(samples):
+    return -0.5 * np.sum(samples.x**2, axis=-1)
+
+# Create the initial samples
+init = Samples(np.random.normal(size=(2_000, 4)))
+
+# Define the aspire object
+aspire = Aspire(
+    log_likelihood=log_likelihood,
+    log_prior=log_prior,
+    dims=4,
+    parameters=[f"x{i}" for i in range(4)],
+)
+
+# Fit the normalizing flow
+aspire.fit(init, n_epochs=20)
+
+# Sample the posterior
+posterior = aspire.sample_posterior(
+    sampler="smc",
+    n_samples=500,
+    sampler_kwargs=dict(n_steps=100),
+)
+
+# Plot the posterior distribution
+posterior.plot_corner()
+```
+
+## Documentation
+
+See the [documentation on ReadTheDocs][docs].
+
+## Citation
+
+If you use `aspire` in your work please cite the [DOI][DOI] and [paper][paper].
+
+
+[docs]: https://aspire.readthedocs.io/
+[DOI]: https://doi.org/10.5281/zenodo.15658747
+[paper]: https://arxiv.org/abs/2511.04218

{aspire_inference-0.1.0a7 → aspire_inference-0.1.0a9}/aspire_inference.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@
 LICENSE
 README.md
 pyproject.toml
+readthedocs.yml
 .github/workflows/lint.yml
 .github/workflows/publish.yml
 .github/workflows/tests.yml
@@ -11,7 +12,18 @@ aspire_inference.egg-info/SOURCES.txt
 aspire_inference.egg-info/dependency_links.txt
 aspire_inference.egg-info/requires.txt
 aspire_inference.egg-info/top_level.txt
+docs/Makefile
+docs/conf.py
+docs/entry_points.rst
+docs/examples.rst
+docs/index.rst
+docs/installation.rst
+docs/multiprocessing.rst
+docs/recipes.rst
+docs/requirements.txt
+docs/user_guide.rst
 examples/basic_example.py
+examples/blackjax_smc_example.py
 examples/smc_example.py
 src/aspire/__init__.py
 src/aspire/aspire.py
@@ -42,5 +54,6 @@ tests/test_transforms.py
 tests/test_utils.py
 tests/integration_tests/conftest.py
 tests/integration_tests/test_integration.py
+tests/test_flows/test_flows_core.py
 tests/test_flows/test_jax_flows/test_flowjax_flows.py
 tests/test_flows/test_torch_flows/test_zuko_flows.py

aspire_inference-0.1.0a9/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

aspire_inference-0.1.0a9/docs/conf.py

@@ -0,0 +1,71 @@
+"""Sphinx configuration for the aspire documentation."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+# Ensure the package can be imported when building the docs locally
+ROOT = os.path.abspath("..")
+if ROOT not in sys.path:
+    sys.path.insert(0, ROOT)
+
+import aspire  # noqa: E402
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "aspire"
+copyright = "2025, Michael J. Williams"
+author = "Michael J. Williams"
+version = aspire.__version__
+release = aspire.__version__
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "autoapi.extension",
+]
+
+autodoc_typehints = "description"
+autodoc_member_order = "bysource"
+autosummary_generate = True
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_preprocess_types = True
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Configure autoapi -------------------------------------------------------
+
+autoapi_type = "python"
+autoapi_dirs = ["../src/aspire/"]
+autoapi_add_toctree_entry = True
+autoapi_options = [
+    "members",
+    "imported-members",
+    "show-inheritance",
+    "show-module-summary",
+    "undoc-members",
+]
+
+# -- Options for HTML output -------------------------------------------------
+
+html_theme = "sphinx_book_theme"
+html_static_path = ["_static"]
+html_title = "aspire"
+html_theme_options = {
+    "path_to_docs": "docs",
+    "repository_url": "https://github.com/mj-will/aspire",
+    "repository_branch": "main",
+    "use_edit_page_button": True,
+    "use_issues_button": True,
+    "use_repository_button": True,
+    "use_download_button": True,
+}

aspire_inference-0.1.0a9/docs/entry_points.rst

@@ -0,0 +1,29 @@
+Entry Points
+============
+
+Aspire uses Python's entry point system to allow for extensibility and
+integration with external libraries. This mechanism enables users to register
+custom components that can be seamlessly integrated into the Aspire framework.
+
+.. _custom_flows:
+
+Custom Flows
+------------
+
+Aspire supports custom flow implementations via the
+``aspire.flows`` entry point group. To register a new flow backend, define an
+entry point in your ``pyproject.toml`` like so:
+
+.. code-block:: toml
+
+    [project.entry-points."aspire.flows"]
+    myflow = "my_module:MyFlowClass"
+
+
+The specified class must inherit from :class:`aspire.flows.base.Flow` (or one
+of the existing flow wrappers), implement the required methods and define the
+``xp`` attribute which specifies the array namespace.
+You can then select your custom flow by setting
+``flow_backend="myflow"`` when initializing Aspire.
+
+For an example see ``GWFlow`` in ``aspire-gw`` (https://github.com/mj-will/aspire-gw).

aspire_inference-0.1.0a9/docs/examples.rst

@@ -0,0 +1,28 @@
+Examples
+========
+
+The repository ships with runnable scripts that demonstrate typical Aspire
+workflows. Execute them from the examples directory after installing the relevant
+extras.
+
+Sequential Monte Carlo (MiniPCN)
+--------------------------------
+
+.. literalinclude:: ../examples/smc_example.py
+   :language: python
+   :linenos:
+   :lines: 1-80
+   :caption: ``examples/smc_example.py`` (excerpt)
+
+Run the full example:
+
+.. code-block:: console
+
+   $ python smc_example.py
+
+The script demonstrates how to:
+
+- Build contrived mixtures of Gaussians for testing,
+- Fit a Neural Spline Flow to biased initial samples,
+- Run adaptive MiniPCN-SMC via :meth:`aspire.Aspire.sample_posterior`,
+- Plot diagnostics (loss curves, beta schedule, corner plots).

aspire_inference-0.1.0a9/docs/index.rst

@@ -0,0 +1,63 @@
+aspire: Accelerated Sequential Posterior Inference via REuse
+============================================================
+
+``aspire`` is a lightweight framework for reusing existing posterior samples
+and normalizing flows to accelerate Bayesian inference. It focuses on
+practical workflows: fit a flow, adaptively run Sequential Monte Carlo (SMC),
+MCMC or importance samplers, and visualise or export the resulting samples.
+
+Key capabilities
+----------------
+
+- Fit flow-based proposals (PyTorch or JAX backends) with automatic handling of
+  bounded and periodic parameters.
+- Run adaptive SMC (MiniPCN or BlackJAX kernels) and importance sampling with
+  detailed diagnostic histories.
+- Inspect results via convenience helpers for evidence estimates, corner plots,
+  and HDF5/JSON export.
+
+Quick start
+-----------
+
+.. code-block:: python
+
+    import numpy as np
+    from aspire import Aspire, Samples
+
+    def log_likelihood(samples):
+        x = samples.x
+        return -0.5 * np.sum(x**2, axis=-1)
+
+    def log_prior(samples):
+        return -0.5 * np.sum(samples.x**2, axis=-1)
+
+    init = Samples(np.random.normal(size=(2_000, 4)))
+
+    aspire = Aspire(
+        log_likelihood=log_likelihood,
+        log_prior=log_prior,
+        dims=4,
+        parameters=[f"x{i}" for i in range(4)],
+    )
+    aspire.fit(init, n_epochs=20)
+    posterior = aspire.sample_posterior(
+        sampler="smc",
+        n_samples=500,
+        sampler_kwargs=dict(n_steps=100),
+    )
+
+    posterior.plot_corner()
+
+Use the sections below for environment setup, conceptual guidance, runnable
+examples, and the complete API reference.
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Contents
+
+    installation
+    user_guide
+    recipes
+    multiprocessing
+    examples
+    entry_points

aspire_inference-0.1.0a9/docs/installation.rst

@@ -0,0 +1,73 @@
+Installation
+============
+
+``aspire`` targets Python 3.10+ and relies on ``numpy``, ``matplotlib``,
+``array-api-compat`` and ``h5py`` for core functionality. Optional extras
+provide tighter integration with popular samplers and flow backends.
+
+Basic setup
+-----------
+
+Install the library from PyPI (note the published name):
+
+.. code-block:: console
+
+   $ python -m pip install aspire-inference
+
+The installed distribution exposes the ``aspire`` import namespace.
+
+Optional extras
+---------------
+
+Additional features can be enabled by installing the relevant extras:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 70
+
+   * - Extra
+     - Purpose
+   * - ``scipy``
+     - Access to SciPy utilities used by certain transforms.
+   * - ``jax``
+     - JAX + ``flowjax`` backend for training normalizing flows.
+   * - ``torch``
+     - PyTorch + ``zuko`` backend (default) for normalizing flows and flow matching.
+   * - ``minipcn``
+     - Enables the MiniPCN SMC kernel.
+   * - ``emcee``
+     - Enables the ``emcee`` ensemble sampler integration.
+   * - ``blackjax``
+     - Enables the BlackJAX SMC kernel.
+   * - ``test``
+     - Installs ``pytest`` and coverage helpers for local testing.
+
+Install extras via:
+
+.. code-block:: console
+
+   $ python -m pip install "aspire-inference[torch,minipcn]"
+
+From source
+-----------
+
+Clone the repository and install in editable mode:
+
+.. code-block:: console
+
+   $ git clone https://github.com/mj-will/aspire.git
+   $ cd aspire
+    # (optional) create/activate a virtual environment
+   $ python -m pip install -e ".[torch,minipcn]"
+
+After installation, run the unit test suite to confirm everything is wired up:
+
+.. code-block:: console
+
+   $ python -m pytest
+
+Building the docs locally requires ``sphinx`` and (optionally) the
+``sphinx-``. These are installed automatically when you run
+``python -m pip install -r docs/requirements.txt`` if such a file exists, or
+you can install ``sphinx`` manually before invoking ``make html`` inside the
+``docs`` directory.

aspire_inference-0.1.0a9/docs/multiprocessing.rst

@@ -0,0 +1,70 @@
+Multiprocessing
+===============
+
+Use :meth:`aspire.Aspire.enable_pool` to run your likelihood (and optionally
+prior) in parallel across a :class:`multiprocessing.Pool`. The helper swaps the
+``map_fn`` argument expected by your log-likelihood / log-prior for
+``pool.map`` while the context is active, then restores the original methods.
+
+Prepare a map-aware likelihood
+------------------------------
+
+Your likelihood must accept ``map_fn``. A minimal
+pattern:
+
+.. code-block:: python
+
+    import numpy as np
+
+
+    def _global_log_likelihood(x):
+        # Expensive likelihood computation for a single sample `x`
+        return -np.sum(x**2)  # Example likelihood
+
+    def log_likelihood(samples, map_fn=map):
+        logl = -np.inf * np.ones(len(samples.x))
+        if samples.log_prior is None:
+            raise RuntimeError("log-prior has not been evaluated!")
+        mask = np.isfinite(samples.log_prior, dtype=bool)
+        x = np.asarray(samples.x[mask, :], dtype=float)
+        logl[mask] = np.fromiter(
+            map_fn(_global_log_likelihood, x),
+            dtype=float,
+        )
+        return logl
+
+Swap in a multiprocessing pool
+------------------------------
+
+Wrap your sampling call inside ``enable_pool`` to parallelize the map step:
+
+.. code-block:: python
+
+    import multiprocessing as mp
+    from aspire import Aspire
+
+    aspire = Aspire(
+        log_likelihood=log_likelihood,
+        log_prior=log_prior,   # must also accept map_fn if parallelize_prior=True
+        dims=4,
+        parameters=["a", "b", "c", "d"],
+    )
+
+    with mp.Pool() as pool, aspire.enable_pool(pool):
+        samples, history = aspire.sample_posterior(
+            sampler="smc",
+            n_samples=1_000,
+            return_history=True,
+        )
+
+Notes
+-----
+
+- By default only the likelihood is parallelized; set
+  ``aspire.enable_pool(pool, parallelize_prior=True)`` if your prior also
+  accepts ``map_fn``.
+- ``enable_pool`` closes the pool on exit unless you pass ``close_pool=False``.
+- The context manager itself is implemented by
+  :class:`aspire.utils.PoolHandler`; if you need finer control (for example,
+  reusing the same pool across multiple ``Aspire`` instances) you can
+  instantiate it directly.