From 33357a0f14ba748d592660e936fefd607f602447 Mon Sep 17 00:00:00 2001 From: nabr Date: Tue, 20 Feb 2024 22:44:28 +0100 Subject: [PATCH] Add documentation for CUQIpy-Umbridge plugin --- clients/README.md | 76 +++++++++++++++++++ clients/python/cuqipy-client.py | 33 ++++++++ models/README.md | 73 +++++++++++++++++- models/cuqipy-distribution/Dockerfile | 9 +++ .../distribution-server.py | 14 ++++ models/cuqipy-model/Dockerfile | 9 +++ models/cuqipy-model/model-server.py | 14 ++++ 7 files changed, 227 insertions(+), 1 deletion(-) create mode 100644 clients/python/cuqipy-client.py create mode 100644 models/cuqipy-distribution/Dockerfile create mode 100644 models/cuqipy-distribution/distribution-server.py create mode 100644 models/cuqipy-model/Dockerfile create mode 100644 models/cuqipy-model/model-server.py diff --git a/clients/README.md b/clients/README.md index 25cf16d4..7f1e8472 100644 --- a/clients/README.md +++ b/clients/README.md @@ -563,3 +563,79 @@ which indeed returns `Ev = 2.9948`, i.e., close to 3 as expected. The script the [Full example sources here.](https://github.com/UM-Bridge/umbridge/blob/main/clients/matlab/sgmkClient.m) +## CUQIpy client + +CUQIpy stands for Computational Uncertainty Quantification for Inverse Problems in python. It’s a robust Python package designed for modeling and solving inverse problems using Bayesian inference. Here’s what it brings to the table: + +- A straightforward high-level interface for UQ analysis. + +- Complete control over the models and methods. + +- An array of predefined distributions, samplers, models, and test problems. + +- Easy extendability for your unique needs. + +A number of CUQIpy Plugins are available as separate packages that expand the functionality of CUQIpy. + +### CUQIpy-UMBridge + +The CUQIpy-Umbridge plugin allows you to use UM-Bridge models as a forward model in CUQIpy and UM-Bridge posterior models as distributions in CUQIpy. + +The plugin can be installed from pip + +``` +pip install cuqipy-umbridge +``` + +This installs CUQIpy and Umbridge as dependencies. + +### Examples + +Given a model server running at `http://localhost:4242`, we can connect to it and use it as a forward model in CUQIpy. + +TODO: ADD EXPLICIT MODEL FROM DOCKER IMAGES + +```python +import cuqipy_umbridge +import numpy as np + +# Create CUQIpy forward model +model = cuqipy_umbridge.client.create_model('http://localhost:4242', 'forward') + +# Print type of model and domain and range geometries +print(model) + +# Evaluate the model +result = model(np.ones(model.domain_dim)) +print(result) +``` + +Given a model server running at `http://localhost:4242`, we can connect to it and use it as a posterior model in CUQIpy. + +TODO: ADD EXPLICIT DISTRIBUTION FROM DOCKER IMAGES + +```python +import cuqi +import cuqipy_umbridge +import numpy as np + +# Create CUQIpy distribution +dist = cuqipy_umbridge.client.create_distribution('http://localhost:4242', 'posterior') + +# Print geometry of distribution +print(dist) + +# Sample distribution using MH sampler +sampler = cuqi.sampler.MH(dist) + +# Sample from distribution (1000 samples with 200 burn-in) +samples = sampler.sample(Ns=1000, Nb=200) + +# Plot trace of samples +samples.plot_trace() +``` + + + + + diff --git a/clients/python/cuqipy-client.py b/clients/python/cuqipy-client.py new file mode 100644 index 00000000..598102f3 --- /dev/null +++ b/clients/python/cuqipy-client.py @@ -0,0 +1,33 @@ +# Example depends on release of CUQIpy-Umbridge to PyPI + +import argparse +import cuqipy_umbridge # CUQIpy UM-Bridge integration. +import cuqi # pip install cuqipy + + +if __name__ == "__main__": + + # Read URL from command line argument + parser = argparse.ArgumentParser(description='Minimal HTTP model demo.') + + parser.add_argument('url', metavar='url', type=str, + help='the URL at which the model is running, for example http://localhost') + + args = parser.parse_args() + + print(f"Connecting to host URL {args.url}") + + # Set up CUQIpy distribution for umbridge model named "posterior" + posterior = cuqipy_umbridge.client.create_distribution(args.url, "posterior") + + # Print dimension of posterior + print(f"Dimension of posterior is {posterior.dim}") + + # Sample posterior using CUQIpy + sampler = cuqi.sampler.MH(posterior) + + # Sample from posterior + samples = sampler.sample(1000) + + # Plot samples + samples.plot_trace() diff --git a/models/README.md b/models/README.md index f1a5378a..69ca3b8a 100644 --- a/models/README.md +++ b/models/README.md @@ -143,4 +143,75 @@ The [MIT Uncertainty Quantification library (MUQ)](https://mituq.bitbucket.io), muq::Modeling::serveModPiece(mod_piece, "0.0.0.0", 4242); ``` -See MUQ's documentation for more in-depth documentation on model graphs and UM-Bridge integration. \ No newline at end of file +See MUQ's documentation for more in-depth documentation on model graphs and UM-Bridge integration. + +## CUQIpy server + +CUQIpy stands for Computational Uncertainty Quantification for Inverse Problems in python. It’s a robust Python package designed for modeling and solving inverse problems using Bayesian inference. Here’s what it brings to the table: + +- A straightforward high-level interface for UQ analysis. + +- Complete control over the models and methods. + +- An array of predefined distributions, samplers, models, and test problems. + +- Easy extendability for your unique needs. + +A number of CUQIpy Plugins are available as separate packages that expand the functionality of CUQIpy. + +### CUQIpy-UMBridge + +The CUQIpy-Umbridge plugin allows you to serve CUQIpy models and distributions via UM-Bridge. + +The plugin can be installed from pip + +``` +pip install cuqipy-umbridge +``` + +This installs CUQIpy and Umbridge as dependencies. + +### Examples + +Serving a CUQIpy model via UM-Bridge is as simple as: + +```python +import cuqi +import cuqipy_umbridge + +# This is the forward model to serve +# This can be changed to any other CUQIpy forward model +# Current example is the forward model of a 1D deconvolution test problem + +model = cuqi.testproblem.Deconvolution1D().model + +# Serve the distribution as UM-Bridge model +# Name will be name of CUQIpy class for distribution +# In this case "LinearModel" +cuqipy_umbridge.server.serve_model(model) + +``` + + +Serving a CUQIpy distribution via UM-Bridge is as simple as: + +```python + +import cuqi +import cuqipy_umbridge + +# This is the distribution to serve +# This can be changed to any other CUQIpy distribution +# Current example is the posterior of a 1D deconvolution test problem + +dist = cuqi.testproblem.Deconvolution1D().posterior + +# Serve the distribution as UM-Bridge model +# Name will be name of CUQIpy class for distribution +# In this case "Posterior" +cuqipy_umbridge.server.serve_distribution(dist) + +``` + + + diff --git a/models/cuqipy-distribution/Dockerfile b/models/cuqipy-distribution/Dockerfile new file mode 100644 index 00000000..8606ef30 --- /dev/null +++ b/models/cuqipy-distribution/Dockerfile @@ -0,0 +1,9 @@ +FROM ubuntu:latest + +COPY distribution-server.py / + +RUN apt update && \ + DEBIAN_FRONTEND="noninteractive" apt install -y python3-pip && \ + pip install cuqipy-umbridge + +CMD python3 distribution-server.py diff --git a/models/cuqipy-distribution/distribution-server.py b/models/cuqipy-distribution/distribution-server.py new file mode 100644 index 00000000..036b2921 --- /dev/null +++ b/models/cuqipy-distribution/distribution-server.py @@ -0,0 +1,14 @@ +import cuqi +import cuqipy_umbridge + +# This is the distribution to serve +# This can be changed to any other CUQIpy distribution +# Current example is the posterior of a 1D deconvolution test problem + +dist = cuqi.testproblem.Deconvolution1D().posterior + +# Serve the distribution as UM-Bridge model +# Name will be name of CUQIpy class for distribution +# In this case "Posterior" +cuqipy_umbridge.server.serve_distribution(dist) + diff --git a/models/cuqipy-model/Dockerfile b/models/cuqipy-model/Dockerfile new file mode 100644 index 00000000..2b92e0bb --- /dev/null +++ b/models/cuqipy-model/Dockerfile @@ -0,0 +1,9 @@ +FROM ubuntu:latest + +COPY model-server.py / + +RUN apt update && \ + DEBIAN_FRONTEND="noninteractive" apt install -y python3-pip && \ + pip install cuqipy-umbridge + +CMD python3 model-server.py diff --git a/models/cuqipy-model/model-server.py b/models/cuqipy-model/model-server.py new file mode 100644 index 00000000..5270ba88 --- /dev/null +++ b/models/cuqipy-model/model-server.py @@ -0,0 +1,14 @@ +import cuqi +import cuqipy_umbridge + +# This is the forward model to serve +# This can be changed to any other CUQIpy forward model +# Current example is the forward model of a 1D deconvolution test problem + +model = cuqi.testproblem.Deconvolution1D().model + +# Serve the distribution as UM-Bridge model +# Name will be name of CUQIpy class for distribution +# In this case "LinearModel" +cuqipy_umbridge.server.serve_model(model) +