CUQIpy 1.3.0__py3-none-any.whl → 1.4.0.post0.dev61__py3-none-any.whl

cuqi/experimental/_recommender.py

@@ -0,0 +1,216 @@
+import cuqi
+import inspect
+import numpy as np
+
+# This import makes suggest_sampler easier to read
+import cuqi.sampler as samplers 
+
+
+class SamplerRecommender(object):
+    """
+    This class can be used to automatically choose a sampler.
+
+    Parameters
+    ----------
+    target: Density or JointDistribution
+        Distribution to get sampler recommendations for.
+
+    exceptions: list[cuqi.sampler.Sampler], *optional*
+        Samplers not to be recommended.
+    
+    Example
+    -------
+    .. code-block:: python
+        import numpy as np
+        from cuqi.distribution import Gamma, Gaussian, JointDistribution
+        from cuqi.experimental import SamplerRecommender
+
+        x = Gamma(1, 1)
+        y = Gaussian(np.zeros(2), cov=lambda x: 1 / x)
+        target = JointDistribution(y, x)(y=1)
+
+        recommender = SamplerRecommender(target)
+        valid_samplers = recommender.valid_samplers()
+        recommended_sampler = recommender.recommend()
+        print("Valid samplers:", valid_samplers)
+        print("Recommended sampler:\n", recommended_sampler)
+
+    """
+
+    def __init__(self, target:cuqi.density.Density, exceptions = []):
+        self._target = target
+        self._exceptions = exceptions
+        self._create_ordering()
+
+    @property
+    def target(self) -> cuqi.density.Density:
+        """ Return the target Distribution. """
+        return self._target
+
+    @target.setter
+    def target(self, value:cuqi.density.Density):
+        """ Set the target Distribution. Runs validation of the target. """
+        if value is None:
+            raise ValueError("Target needs to be of type cuqi.density.Density.")
+        self._target = value
+
+    def _create_ordering(self):
+        """
+        Every element in the ordering consists of a tuple:
+        (
+            Sampler: Class
+            boolean: additional conditions on the target
+            parameters: additional parameters to be passed to the sampler once initialized
+        )
+        """
+        number_of_components = np.sum(self._target.dim)
+
+        self._ordering = [
+            # Direct and Conjugate samplers
+            (samplers.Direct, True, {}),
+            (samplers.Conjugate, True, {}),
+            (samplers.ConjugateApprox, True, {}),
+            # Specialized samplers
+            (samplers.LinearRTO, True, {}),
+            (samplers.RegularizedLinearRTO, True, {}),
+            (samplers.UGLA, True, {}),
+            # Gradient.based samplers (Hamiltonian and Langevin)
+            (samplers.NUTS, True, {}),
+            (samplers.MALA, True, {}),
+            (samplers.ULA, True, {}),
+            # Gibbs and Componentwise samplers
+            (samplers.HybridGibbs, True, {"sampling_strategy" : self.recommend_HybridGibbs_sampling_strategy(as_string = False)}),
+            (samplers.CWMH, number_of_components <= 100, {"scale" : 0.05*np.ones(number_of_components),
+                            "initial_point" : 0.5*np.ones(number_of_components)}),
+            # Proposal based samplers
+            (samplers.PCN, True, {"scale" : 0.02}),
+            (samplers.MH, number_of_components <= 1000, {}),
+        ]
+
+    @property
+    def ordering(self):
+        """ Returns the ordered list of recommendation rules used by the recommender. """
+        return self._ordering
+
+    def valid_samplers(self, as_string = True):
+        """
+        Finds all possible samplers that can be used for sampling from the target distribution.
+
+        Parameters
+        ----------
+
+        as_string : boolean
+            Whether to return the name of the sampler as a string instead of instantiating a sampler. *Optional*
+
+        """
+
+        all_samplers = [(name, cls) for name, cls in inspect.getmembers(cuqi.sampler, inspect.isclass) if issubclass(cls, cuqi.sampler.Sampler)]
+        valid_samplers = []
+
+        for name, sampler in all_samplers:
+            try:
+                sampler(self.target)
+                valid_samplers += [name if as_string else sampler]
+            except:
+                pass
+
+        # Need a separate case for HybridGibbs
+        if self.valid_HybridGibbs_sampling_strategy() is not None:
+            valid_samplers += [cuqi.sampler.HybridGibbs.__name__ if as_string else cuqi.sampler.HybridGibbs]
+
+        return valid_samplers
+
+    def valid_HybridGibbs_sampling_strategy(self, as_string = True):
+        """
+            Find all possible sampling strategies to be used with the HybridGibbs sampler.
+            Returns None if no sampler could be suggested for at least one conditional distribution.
+
+            Parameters
+            ----------
+
+            as_string : boolean
+                Whether to return the name of the samplers in the sampling strategy as a string instead of instantiating samplers. *Optional*
+        
+
+        """
+
+        if not isinstance(self.target, cuqi.distribution.JointDistribution):
+            return None
+
+        par_names = self.target.get_parameter_names()
+
+        valid_samplers = dict()
+        for par_name in par_names:
+            conditional_params = {par_name_: np.ones(self.target.dim[i]) for i, par_name_ in enumerate(par_names) if par_name_ != par_name}
+            conditional = self.target(**conditional_params)
+
+            recommender = SamplerRecommender(conditional)
+            samplers = recommender.valid_samplers(as_string)
+            if len(samplers) == 0:
+                return None
+
+            valid_samplers[par_name] = samplers
+
+        return valid_samplers
+
+    def recommend(self, as_string = False):
+        """
+            Suggests a possible sampler that can be used for sampling from the target distribution.
+            Return None if no sampler could be suggested.
+
+            Parameters
+            ----------
+
+            as_string : boolean
+                Whether to return the name of the sampler as a string instead of instantiating a sampler. *Optional*
+
+        """
+
+        valid_samplers = self.valid_samplers(as_string = False)
+
+        for suggestion, flag, values in self._ordering:
+            if flag and (suggestion in valid_samplers) and (suggestion not in self._exceptions):
+                # Sampler found
+                if as_string:
+                    return suggestion.__name__
+                else:
+                    return suggestion(self.target, **values)
+
+        # No sampler can be suggested
+        raise ValueError("Cannot suggest any sampler. Either the provided distribution is incorrectly defined or there are too many exceptions provided.")
+
+    def recommend_HybridGibbs_sampling_strategy(self, as_string = False):
+        """
+            Suggests a possible sampling strategy to be used with the HybridGibbs sampler.
+            Returns None if no sampler could be suggested for at least one conditional distribution.
+
+            Parameters
+            ----------
+
+            target : `cuqi.distribution.JointDistribution`
+                The target distribution get a sampling strategy for.
+            
+            as_string : boolean
+                Whether to return the name of the samplers in the sampling strategy as a string instead of instantiating samplers. *Optional*
+        
+        """
+
+        if not isinstance(self.target, cuqi.distribution.JointDistribution):
+            return None
+
+        par_names = self.target.get_parameter_names()
+
+        suggested_samplers = dict()
+        for par_name in par_names:
+            conditional_params = {par_name_: np.ones(self.target.dim[i]) for i, par_name_ in enumerate(par_names) if par_name_ != par_name}
+            conditional = self.target(**conditional_params)
+
+            recommender = SamplerRecommender(conditional, exceptions = self._exceptions.copy())
+            sampler = recommender.recommend(as_string = as_string)
+
+            if sampler is None:
+                return None
+
+            suggested_samplers[par_name] = sampler
+
+        return suggested_samplers

cuqi/experimental/geometry/_productgeometry.py

@@ -172,10 +172,10 @@ class _ProductGeometry(Geometry):
         return tuple(funvecs)
         
     
-    def __repr__(self) -> str:
+    def __repr__(self, pad="") -> str:
         """Representation of the product geometry."""
         string = "{}(".format(self.__class__.__name__) + "\n"
         for g in self.geometries:
-            string += "\t{}\n".format(g.__repr__())
-        string += ")"
+            string += pad + "    {}\n".format(g.__repr__())
+        string += pad + ")"
         return string

cuqi/geometry/_geometry.py

@@ -225,7 +225,18 @@ class Geometry(ABC):
         return self._all_values_equal(obj)
 
     def __repr__(self) -> str:
-        return "{}{}".format(self.__class__.__name__,self.par_shape)
+        if self.par_shape == self.fun_shape:
+            return "{}[{}]".format(self.__class__.__name__,
+                                   self.par_shape if len(self.par_shape) != 1 else self.par_shape[0])
+        return "{}[{}: {}]".format(
+            self.__class__.__name__,
+            self.par_shape if len(self.par_shape) != 1 else self.par_shape[0],
+            (
+                self.fun_shape
+                if (self.fun_shape is None or len(self.fun_shape) != 1)
+                else self.fun_shape[0]
+            ),
+        )
 
     def _all_values_equal(self, obj):
         """Returns true of all values of the object and self are equal"""

cuqi/implicitprior/__init__.py

@@ -1,5 +1,5 @@
 from ._regularizedGaussian import RegularizedGaussian, ConstrainedGaussian, NonnegativeGaussian
 from ._regularizedGMRF import RegularizedGMRF, ConstrainedGMRF, NonnegativeGMRF
 from ._regularizedUnboundedUniform import RegularizedUnboundedUniform
-from ._restorator import RestorationPrior, MoreauYoshidaPrior
+from ._restorator import RestorationPrior, MoreauYoshidaPrior, TweediePrior
 

cuqi/implicitprior/_regularizedGaussian.py

@@ -2,10 +2,12 @@ from cuqi.utilities import get_non_default_args
 from cuqi.distribution import Distribution, Gaussian
 from cuqi.solver import ProjectNonnegative, ProjectBox, ProximalL1
 from cuqi.geometry import Continuous1D, Continuous2D, Image2D
-from cuqi.operator import FirstOrderFiniteDifference, Operator
+from cuqi.operator import FirstOrderFiniteDifference, SecondOrderFiniteDifference, Operator
 
 import numpy as np
 import scipy.sparse as sparse
+import scipy.optimize as spoptimize
+
 from copy import copy
 
 
@@ -60,12 +62,18 @@ class RegularizedGaussian(Distribution):
         min_(z in C) 0.5||x-z||_2^2.
 
     constraint : string or None
-        Preset constraints that generate the corresponding proximal parameter. Can be set to "nonnegativity" and "box". Required for use in Gibbs.
-        For "box", the following additional parameters can be passed:
+        Preset constraints that generate the corresponding proximal parameter. Required for use in Gibbs. For any geometry the following can be chosen:
+        - "nonnegativity"
+        - "box", the following additional parameters can be passed:
             lower_bound : array_like or None
                 Lower bound of box, defaults to zero
             upper_bound : array_like
                 Upper bound of box, defaults to one
+        Additionally, for Continuous1D geometry the following options can be chosen:
+        - "increasing"
+        - "decreasing"
+        - "convex"
+        - "concave"
 
     regularization : string or None
         Preset regularization that generate the corresponding proximal parameter. Can be set to "l1" or 'tv'. Required for use in Gibbs in future update.
@@ -178,6 +186,34 @@ class RegularizedGaussian(Distribution):
                 self._proximal = lambda z, _: ProjectBox(z, _box_lower, _box_upper)
                 self._box_bounds = (np.ones(self.dim)*_box_lower, np.ones(self.dim)*_box_upper)
                 self._preset["constraint"] = "box"
+            elif c_lower == "increasing":
+                if not isinstance(self.geometry, Continuous1D):
+                    raise ValueError("Geometry not supported for " + c_lower)
+                if hasattr(spoptimize, 'isotonic_regression'):
+                    self._constraint_prox = lambda z, _: spoptimize.isotonic_regression(z, increasing=True).x
+                else:
+                    raise AttributeError(f"The function 'isotonic_regression' does not exist in scipy.optimize. Installed scipy version: {spoptimize.__version__}. You need to install a scipy >= 1.12.0")
+                self._preset["constraint"] = "increasing"
+            elif c_lower == "decreasing":
+                if not isinstance(self.geometry, Continuous1D):
+                    raise ValueError("Geometry not supported for " + c_lower)
+                if hasattr(spoptimize, 'isotonic_regression'):
+                    self._constraint_prox = lambda z, _: spoptimize.isotonic_regression(z, increasing=False).x
+                else:
+                    raise AttributeError(f"The function 'isotonic_regression' does not exist in scipy.optimize. Installed scipy version: {spoptimize.__version__}. You need to install a scipy >= 1.12.0")
+                self._preset["constraint"] = "decreasing"
+            elif c_lower == "convex":
+                if not isinstance(self.geometry, Continuous1D):
+                    raise ValueError("Geometry not supported for " + c_lower)
+                self._constraint_prox = lambda z, _: -ProjectNonnegative(-z)
+                self._constraint_oper = SecondOrderFiniteDifference(self.geometry.fun_shape, bc_type='neumann')
+                self._preset["constraint"] = "convex"
+            elif c_lower == "concave":
+                if not isinstance(self.geometry, Continuous1D):
+                    raise ValueError("Geometry not supported for " + c_lower)
+                self._constraint_prox = lambda z, _: ProjectNonnegative(z)
+                self._constraint_oper = SecondOrderFiniteDifference(self.geometry.fun_shape, bc_type='neumann')
+                self._preset["constraint"] = "concave"
             else:
                 raise ValueError("Constraint not supported.")
 
@@ -289,7 +325,7 @@ class RegularizedGaussian(Distribution):
   
     @staticmethod
     def constraint_options():
-        return ["nonnegativity", "box"]
+        return ["nonnegativity", "box", "increasing", "decreasing", "convex", "concave"]
 
     @staticmethod
     def regularization_options():

cuqi/implicitprior/_restorator.py

@@ -232,4 +232,38 @@ class MoreauYoshidaPrior(Distribution):
         """ Returns the conditioning variables of the distribution. """
         # Currently conditioning variables are not supported for user-defined
         # distributions.
-        return []
+        return []
+
+class TweediePrior(MoreauYoshidaPrior):
+    """
+    Alias for MoreauYoshidaPrior following Tweedie's formula framework. TweediePrior 
+    defines priors where gradients are computed based on Tweedie's identity that links 
+    MMSE (Minimum Mean Square Error) denoisers with the underlying smoothed prior, see:
+        - Laumont et al. https://arxiv.org/abs/2103.04715 or https://doi.org/10.1137/21M1406349
+
+    Tweedie's Formula
+    -------------------------
+    In the context of denoising, Tweedie's identity states that for a signal x
+    corrupted by Gaussian noise:
+
+        ∇_x log p_e(x) = (D_e(x) - x) / e
+
+    where D_e(x) is the MMSE denoiser output and e is the noise variance.
+    This enables us to perform gradient-based sampling with algorithms like ULA.
+
+    At implementation level, TweediePrior shares identical functionality with MoreauYoshidaPrior. 
+    Thus, it is implemented as an alias of MoreauYoshidaPrior, meaning all methods, 
+    properties, and behavior are identical. The separate name provides clarity when 
+    working specifically with Tweedie's formula-based approaches.
+
+    Parameters
+    ----------
+    prior : RestorationPrior
+        Prior of the RestorationPrior type containing a denoiser/restorator.
+        
+    smoothing_strength : float, default=0.1
+        Corresponds to the noise variance e in Tweedie's formula context.
+
+    See MoreauYoshidaPrior for the underlying implementation with complete documentation.
+    """
+    pass

cuqi/legacy/__init__.py

@@ -0,0 +1,2 @@
+""" Legacy module for functionalities that are no longer supported or developed. """
+from . import sampler

cuqi/legacy/sampler/__init__.py

@@ -0,0 +1,11 @@
+from ._sampler import Sampler, ProposalBasedSampler
+from ._conjugate import Conjugate
+from ._conjugate_approx import ConjugateApprox
+from ._cwmh import CWMH
+from ._gibbs import Gibbs
+from ._hmc import NUTS
+from ._langevin_algorithm import ULA, MALA
+from ._laplace_approximation import UGLA
+from ._mh import MH
+from ._pcn import pCN
+from ._rto import LinearRTO, RegularizedLinearRTO

cuqi/legacy/sampler/_conjugate.py

@@ -0,0 +1,55 @@
+from cuqi.distribution import Posterior, Gaussian, Gamma, GMRF
+from cuqi.implicitprior import RegularizedGaussian, RegularizedGMRF
+import numpy as np
+
+class Conjugate: # TODO: Subclass from Sampler once updated
+    """ Conjugate sampler
+
+    Sampler for sampling a posterior distribution where the likelihood and prior are conjugate.
+
+    Currently supported conjugate pairs are:
+    - (Gaussian, Gamma)
+    - (GMRF, Gamma)
+    - (RegularizedGaussian, Gamma) with nonnegativity constraints only
+
+    For more information on conjugate pairs, see https://en.wikipedia.org/wiki/Conjugate_prior.
+
+    For implicit regularized Gaussians see:
+    
+    [1] Everink, Jasper M., Yiqiu Dong, and Martin S. Andersen. "Bayesian inference with projected densities." SIAM/ASA Journal on Uncertainty Quantification 11.3 (2023): 1025-1043.
+
+    """
+
+    def __init__(self, target: Posterior):
+        if not isinstance(target.likelihood.distribution, (Gaussian, GMRF, RegularizedGaussian, RegularizedGMRF)):
+            raise ValueError("Conjugate sampler only works with a Gaussian-type likelihood function")
+        if not isinstance(target.prior, Gamma):
+            raise ValueError("Conjugate sampler only works with Gamma prior")
+        if not target.prior.dim == 1:
+            raise ValueError("Conjugate sampler only works with univariate Gamma prior")
+            
+        if isinstance(target.likelihood.distribution, (RegularizedGaussian, RegularizedGMRF)) and (target.likelihood.distribution.preset["constraint"] not in ["nonnegativity"] or target.likelihood.distribution.preset["regularization"] is not None) :
+               raise ValueError("Conjugate sampler only works implicit regularized Gaussian likelihood with nonnegativity constraints")
+        
+        self.target = target
+
+    def step(self, x=None):
+        # Extract variables
+        b = self.target.likelihood.data                                 #mu
+        m = self._calc_m_for_Gaussians(b)                               #n
+        Ax = self.target.likelihood.distribution.mean                   #x_i
+        L = self.target.likelihood.distribution(np.array([1])).sqrtprec #L
+        alpha = self.target.prior.shape                                 #alpha
+        beta = self.target.prior.rate                                   #beta
+
+        # Create Gamma distribution and sample
+        dist = Gamma(shape=m/2+alpha,rate=.5*np.linalg.norm(L@(Ax-b))**2+beta)
+
+        return dist.sample()
+
+    def _calc_m_for_Gaussians(self, b):
+        """ Helper method to calculate m parameter for Gaussian-Gamma conjugate pair. """
+        if isinstance(self.target.likelihood.distribution, (Gaussian, GMRF)):
+            return len(b)
+        elif isinstance(self.target.likelihood.distribution, (RegularizedGaussian, RegularizedGMRF)):
+            return np.count_nonzero(b) # See 

cuqi/legacy/sampler/_conjugate_approx.py

@@ -0,0 +1,52 @@
+from cuqi.distribution import Posterior, LMRF, Gamma
+import numpy as np
+import scipy as sp
+
+class ConjugateApprox: # TODO: Subclass from Sampler once updated
+    """ Approximate Conjugate sampler
+
+    Sampler for sampling a posterior distribution where the likelihood and prior can be approximated
+    by a conjugate pair.
+
+    Currently supported pairs are:
+    - (LMRF, Gamma): Approximated by (Gaussian, Gamma)
+
+    For more information on conjugate pairs, see https://en.wikipedia.org/wiki/Conjugate_prior.
+
+    """
+
+    
+    def __init__(self, target: Posterior):
+        if not isinstance(target.likelihood.distribution, LMRF):
+            raise ValueError("Conjugate sampler only works with Laplace diff likelihood function")
+        if not isinstance(target.prior, Gamma):
+            raise ValueError("Conjugate sampler only works with Gamma prior")
+        self.target = target
+
+    def step(self, x=None):
+        # Extract variables
+        # Here we approximate the Laplace diff with a Gaussian
+
+        # Extract diff_op from target likelihood
+        D = self.target.likelihood.distribution._diff_op
+        n = D.shape[0]
+
+        # Gaussian approximation of LMRF prior as function of x_k
+        # See Uribe et al. (2022) for details
+        # Current has a zero mean assumption on likelihood! TODO
+        beta=1e-5
+        def Lk_fun(x_k):
+            dd =  1/np.sqrt((D @ x_k)**2 + beta*np.ones(n))
+            W = sp.sparse.diags(dd)
+            return W.sqrt() @ D
+
+        x = self.target.likelihood.data                 #x
+        d = len(x)                                      #d
+        Lx = Lk_fun(x)@x                                #Lx
+        alpha = self.target.prior.shape                 #alpha
+        beta = self.target.prior.rate                   #beta
+
+        # Create Gamma distribution and sample
+        dist = Gamma(shape=d+alpha, rate=np.linalg.norm(Lx)**2+beta)
+
+        return dist.sample()