aspire-inference 0.1.0a8__tar.gz → 0.1.0a10__tar.gz

aspire_inference-0.1.0a10/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: aspire-inference
+Version: 0.1.0a10
+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[array-api]>=0.2.0a3; extra == "minipcn"
+Requires-Dist: orng; 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`. By default, you need to install
+one of the backends for the normalizing flows, either `torch` or `jax`.
+We also recommend installing `minipcn` if using the `smc` sampler:
+
+
+**Torch**
+
+We recommend installing `torch` manually to ensure correct CPU/CUDA versions are
+ installed. See the [PyTorch installation instructions](https://pytorch.org/)
+ for more details.
+
+```
+pip install aspire-inference[torch,minipcn]
+```
+
+**Jax**:
+
+We recommend install `jax` manually to ensure the correct GPU/CUDA versions
+are installed. See the [jax documentation for details](https://docs.jax.dev/en/latest/installation.html)
+
+```
+pip install aspire-inference[jax,minipcn]
+```
+
+**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.0a10/README.md

@@ -0,0 +1,90 @@
+# 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`. By default, you need to install
+one of the backends for the normalizing flows, either `torch` or `jax`.
+We also recommend installing `minipcn` if using the `smc` sampler:
+
+
+**Torch**
+
+We recommend installing `torch` manually to ensure correct CPU/CUDA versions are
+ installed. See the [PyTorch installation instructions](https://pytorch.org/)
+ for more details.
+
+```
+pip install aspire-inference[torch,minipcn]
+```
+
+**Jax**:
+
+We recommend install `jax` manually to ensure the correct GPU/CUDA versions
+are installed. See the [jax documentation for details](https://docs.jax.dev/en/latest/installation.html)
+
+```
+pip install aspire-inference[jax,minipcn]
+```
+
+**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.0a10/aspire_inference.egg-info/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: aspire-inference
+Version: 0.1.0a10
+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[array-api]>=0.2.0a3; extra == "minipcn"
+Requires-Dist: orng; 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`. By default, you need to install
+one of the backends for the normalizing flows, either `torch` or `jax`.
+We also recommend installing `minipcn` if using the `smc` sampler:
+
+
+**Torch**
+
+We recommend installing `torch` manually to ensure correct CPU/CUDA versions are
+ installed. See the [PyTorch installation instructions](https://pytorch.org/)
+ for more details.
+
+```
+pip install aspire-inference[torch,minipcn]
+```
+
+**Jax**:
+
+We recommend install `jax` manually to ensure the correct GPU/CUDA versions
+are installed. See the [jax documentation for details](https://docs.jax.dev/en/latest/installation.html)
+
+```
+pip install aspire-inference[jax,minipcn]
+```
+
+**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.0a8 → aspire_inference-0.1.0a10}/aspire_inference.egg-info/SOURCES.txt

@@ -13,15 +13,17 @@ aspire_inference.egg-info/dependency_links.txt
 aspire_inference.egg-info/requires.txt
 aspire_inference.egg-info/top_level.txt
 docs/Makefile
-docs/api.rst
 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

{aspire_inference-0.1.0a8 → aspire_inference-0.1.0a10}/aspire_inference.egg-info/requires.txt

@@ -16,7 +16,8 @@ jaxlib
 flowjax
 
 [minipcn]
-minipcn
+minipcn[array-api]>=0.2.0a3
+orng
 
 [scipy]
 scipy

{aspire_inference-0.1.0a8 → aspire_inference-0.1.0a10}/docs/conf.py

@@ -29,6 +29,7 @@ extensions = [
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    "autoapi.extension",
 ]
 
 autodoc_typehints = "description"
@@ -41,6 +42,19 @@ 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 = False
+autoapi_options = [
+    "members",
+    "imported-members",
+    "show-inheritance",
+    "show-module-summary",
+    "undoc-members",
+]
+
 # -- Options for HTML output -------------------------------------------------
 
 html_theme = "sphinx_book_theme"

{aspire_inference-0.1.0a8 → aspire_inference-0.1.0a10}/docs/index.rst

@@ -22,8 +22,7 @@ Quick start
 .. code-block:: python
 
     import numpy as np
-    from aspire import Aspire
-    from aspire.samples import Samples
+    from aspire import Aspire, Samples
 
     def log_likelihood(samples):
         x = samples.x
@@ -58,6 +57,15 @@ examples, and the complete API reference.
 
     installation
     user_guide
+    recipes
+    multiprocessing
     examples
     entry_points
-    api
+    API Reference </autoapi/aspire/index>
+
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Related Packages
+
+    aspire-bilby <https://aspire.readthedocs.io/projects/aspire-bilby/en/latest/>

{aspire_inference-0.1.0a8 → aspire_inference-0.1.0a10}/docs/installation.rst

@@ -14,7 +14,11 @@ Install the library from PyPI (note the published name):
 
    $ python -m pip install aspire-inference
 
-The installed distribution exposes the ``aspire`` import namespace.
+The installed distribution exposes the ``aspire`` import namespace. By default,
+this doesn't include any optional dependencies beyond the core ones listed above.
+We recommend installing with at least one backend for normalizing flows, e.g.
+``torch`` (PyTorch + ``zuko``) or ``jax`` (JAX + ``flowjax``).
+and optionally the ``minipcn`` SMC kernel.
 
 Optional extras
 ---------------

aspire_inference-0.1.0a10/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.

aspire_inference-0.1.0a10/docs/recipes.rst

@@ -0,0 +1,70 @@
+Practical recipes
+=================
+
+Checking the prior when evaluating the likelihood
+-------------------------------------------------
+
+By default, Aspire samplers always evaluate the log-prior before the
+log-likelihood. This allows users to check the prior support and skip
+likelihood evaluations for samples that lie outside the prior bounds.
+
+.. code-block:: python
+
+    import aspire
+    import numpy as np
+
+
+    def log_likelihood(samples: aspire.Samples) -> np.ndarray:
+        if samples.log_prior is None:
+            raise RuntimeError("log-prior has not been evaluated!")
+        # Return -inf for samples with invalid prior
+        logl = np.full(samples.n_samples, -np.inf, dtype=float)
+        # Only evaluate the likelihood where the prior is finite
+        mask = np.isfinite(samples.log_prior, dtype=bool)
+        # Valid samples
+        x = samples.x[mask, :]
+        logl[mask] = -np.sum(x**2, axis=1)  # Example likelihood
+        return logl
+
+
+Checking the flow distribution
+------------------------------
+
+It can be useful to inspect the flow-based proposal distribution before sampling
+from the posterior. You can do this by drawing samples from the flow after fitting
+and comparing them to the initial samples:
+
+
+.. code-block:: python
+
+    from aspire import Aspire, Samples
+    from aspire.plot import plot_comparison
+
+    # Define the initial samples
+    initial_samples = Samples(...)
+
+    # Define the Aspire instance
+    aspire = Aspire(
+        log_likelihood=log_likelihood,
+        log_prior=log_prior,
+        ...
+    )
+
+    # Fit the flow to the initial samples
+    fit_history = aspire.fit(initial_samples)
+
+    # Draw samples from the flow
+    flow_samples = aspire.sample_flow(10_000)
+
+    # Plot a comparison between initial samples and flow samples
+    fig = plot_comparison(
+        initial_samples,
+        flow_samples,
+        per_samples_kwargs=[
+            dict(include_weights=False, color="C0"),
+            dict(include_weights=False, color="C1"),
+        ],
+        labels=["Initial samples", "Flow samples"],
+    )
+    # Save or show the figure
+    fig.savefig("flow_comparison.png")

{aspire_inference-0.1.0a8 → aspire_inference-0.1.0a10}/docs/requirements.txt

@@ -1,2 +1,3 @@
 sphinx>=7.2
 sphinx-book-theme>=1.1
+sphinx-autoapi>=3.2

{aspire_inference-0.1.0a8 → aspire_inference-0.1.0a10}/docs/user_guide.rst

@@ -44,8 +44,8 @@ switch namespaces or merge multiple runs with
 Flows and transforms
 --------------------
 
-Aspire can work with any proposal that implements ``sample_and_log_prob`` and
-``log_prob``; normalising flows remain the default. Flows are defined via
+Aspire can work with any flow that implements ``sample_and_log_prob`` and
+``log_prob``. Flows are defined via
 :class:`aspire.flows.base.Flow` and instantiated by
 :meth:`aspire.Aspire.init_flow`. By default Aspire uses the ``zuko``
 implementation of Masked Autoregressive Flows on top of PyTorch. The flow is
@@ -61,6 +61,55 @@ estimator (requires the `zuko` backend).
 External flow implementations can be plugged in via the
 ``aspire.flows`` entry point group. See :ref:`custom_flows` for details.
 
+Transform mechanics
+~~~~~~~~~~~~~~~~~~~
+
+Aspire keeps a clear separation between your native parameters and the space
+where flows or kernels operate:
+
+* :class:`aspire.transforms.FlowTransform` is attached to every flow created by
+  :meth:`aspire.Aspire.init_flow`. By default, it maps bounded parameters to the real line (``probit`` or
+  ``logit``), and recentres / rescales dimensions with an affine
+  transform learned from the training samples. Log-Jacobian terms are tracked so
+  calls to ``log_prob`` or ``sample_and_log_prob`` remain properly normalised.
+  ``bounded_to_unbounded`` and ``affine_transform`` can be specified when creating
+  the Aspire instance to control this behaviour.
+* The same components are exposed via :class:`aspire.transforms.CompositeTransform`
+  if you want to opt out of the bounded-to-unbounded step or the affine
+  whitening when building custom transports.
+
+Preconditioning inside samplers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+SMC and MCMC samplers also work in a transformed space. They fit the chosen
+``preconditioning`` transform to the initial particles, perform moves there, and
+then call ``inverse(...)`` (including the log-Jacobian) whenever the likelihood
+or prior is evaluated. Configure it via
+:meth:`aspire.Aspire.sample_posterior`:
+
+* ``"default"`` / ``"standard"`` uses :class:`aspire.transforms.CompositeTransform`
+  with bounded-to-unbounded and affine scaling turned off by default; periodic
+  wrapping still applies. To whiten dimensions or map bounds to the real line,
+  pass ``preconditioning_kwargs={"affine_transform": True, "bounded_to_unbounded": True}``.
+* ``"flow"`` fits a lightweight :class:`aspire.transforms.FlowPreconditioningTransform`
+  to the current particles and treats it as a transport map during SMC/MCMC
+  updates. This reuses the same bounded / periodic handling while providing a
+  richer geometry for the kernels.
+* ``None`` leaves the sampler in the original parameterisation with an identity
+  transform. The importance sampler defaults to this; other samplers default to
+  ``"standard"`` so periodic parameters are at least kept consistent with their
+  bounds.
+
+
+.. note::
+
+    By default, the preconditioning transform does not include bounded-to-unbounded
+    steps. This means your log-prior and log-likelihood must handle points that
+    lie outside the specified bounds (e.g. by returning ``-inf``). If you want
+    the sampler to automatically map bounded parameters to an unconstrained
+    space, enable the ``bounded_to_unbounded`` option in
+    ``preconditioning_kwargs``.
+
 Sampling strategies
 -------------------
 
@@ -101,11 +150,6 @@ Sequential Monte Carlo
     Replaces the internal MCMC move with the ``emcee`` ensemble sampler,
     providing a gradient-free option that still benefits from SMC tempering.
 
-You can plug in custom preconditioning by setting ``preconditioning`` to
-``"standard"`` (affine normalisation based on current samples), ``"flow"``
-(use the fitted flow as a transport map), or ``None`` to disable additional
-transforms.
-
 History, diagnostics, and persistence
 -------------------------------------