CUQIpy 1.1.1.post0.dev36__py3-none-any.whl → 1.4.1.post0.dev124__py3-none-any.whl

cuqi/distribution/_truncated_normal.py

@@ -0,0 +1,129 @@
+import numpy as np
+from scipy.special import erf
+from cuqi.utilities import force_ndarray
+from cuqi.distribution import Distribution
+from cuqi.distribution import Normal
+
+class TruncatedNormal(Distribution):
+    """
+    Truncated Normal probability distribution.
+    
+    Generates instance of cuqi.distribution.TruncatedNormal. 
+    It allows the user to specify upper and lower bounds on random variables 
+    represented by a Normal distribution. This distribution is suitable for a 
+    small dimension setup (e.g. `dim`=3 or 4). Using TruncatedNormal 
+    Distribution with a larger dimension can lead to a high rejection rate when
+    used within MCMC samplers.
+    
+    The variables of this distribution are iid.
+
+    
+    Parameters
+    ------------
+    mean : float or array_like of floats
+        mean of distribution
+    std : float or array_like of floats
+        standard deviation
+    low : float or array_like of floats
+        lower bound of the distribution
+    high : float or array_like of floats
+        upper bound of the distribution
+    
+    Example
+    -----------
+    .. code-block:: python
+
+        #Generate Normal with mean 0, standard deviation 1 and bounds [-2,2]
+        p = cuqi.distribution.TruncatedNormal(mean=0, std=1, low=-2, high=2)
+        samples = p.sample(5000)
+    """
+    def __init__(self, mean=None, std=None, low=-np.inf, high=np.inf, is_symmetric=False, **kwargs):
+        # Init from abstract distribution class
+        super().__init__(is_symmetric=is_symmetric, **kwargs)  
+
+        # Init specific to this distribution
+        self.mean = mean
+        self.std = std
+        self.low = low
+        self.high = high
+
+        # Init underlying normal distribution
+        self._normal = Normal(self.mean, self.std, is_symmetric=True, **kwargs)
+
+    @property
+    def mean(self):
+        """ Mean of the distribution """
+        return self._mean
+
+    @mean.setter
+    def mean(self, value):
+        self._mean = force_ndarray(value, flatten=True)
+        if hasattr(self, '_normal'):
+            self._normal.mean = self._mean
+
+    @property
+    def std(self):
+        """ Std of the distribution """
+        return self._std
+
+    @std.setter
+    def std(self, value):
+        self._std = force_ndarray(value, flatten=True)
+        if hasattr(self, '_normal'):
+            self._normal.std = self._std
+
+    @property
+    def low(self):
+        """ Lower bound of the distribution """
+        return self._low
+
+    @low.setter
+    def low(self, value):
+        self._low = force_ndarray(value, flatten=True)
+
+    @property
+    def high(self):
+        """ Higher bound of the distribution """
+        return self._high
+
+    @high.setter
+    def high(self, value):
+        self._high = force_ndarray(value, flatten=True)
+
+    def logpdf(self, x):
+        """
+        Computes the unnormalized logpdf at the given values of x.
+        """
+        # the unnormalized logpdf
+        # check if x falls in the range between np.array a and b
+        if np.any(x < self.low) or np.any(x > self.high):
+            return -np.inf
+        else:
+             return self._normal.logpdf(x)
+
+    def _gradient(self, x, *args, **kwargs):
+        """
+        Computes the gradient of the unnormalized logpdf at the given values of x.
+        """
+        # check if x falls in the range between np.array a and b
+        if np.any(x < self.low) or np.any(x > self.high):
+            return np.nan*np.ones_like(x)
+        else:
+            return self._normal.gradient(x, *args, **kwargs)
+
+    def _sample(self, N=1, rng=None):
+        """
+        Generates random samples from the distribution.
+        """
+        max_iter = 1e9 # maximum number of trials to avoid infinite loop
+        samples = []
+        for i in range(int(max_iter)):
+            if len(samples) == N:
+                break
+            sample = self._normal.sample(1,rng)
+            if np.all(sample >= self.low) and np.all(sample <= self.high):
+                samples.append(sample)
+        # raise a error if the number of iterations exceeds max_iter
+        if i == max_iter-1:
+            raise RuntimeError("Failed to generate {} samples within {} iterations".format(N, max_iter))
+        return np.array(samples).T.reshape(-1,N)

cuqi/distribution/_uniform.py

@@ -1,5 +1,6 @@
 import numpy as np
 from cuqi.distribution import Distribution
+from cuqi.geometry import Geometry
 
 class Uniform(Distribution):
 
@@ -21,6 +22,9 @@ class Uniform(Distribution):
         self.high = high      
 
     def logpdf(self, x):
+        """
+        Evaluate the logarithm of the PDF at the given values of x.
+        """
         # First check whether x is outside bounds.
         # It is outside if any coordinate is outside the interval.
         if np.any(x < self.low) or np.any(x > self.high):
@@ -38,6 +42,15 @@ class Uniform(Distribution):
             return_val = np.log(1.0/v)
         return return_val
 
+    def gradient(self, x):
+        """
+        Computes the gradient of logpdf at the given values of x.
+        """
+        if np.any(x < self.low) or np.any(x > self.high):
+            return np.nan*np.ones_like(x)
+        else:
+            return np.zeros_like(x)
+
     def _sample(self,N=1, rng=None):
 
         if rng is not None:
@@ -45,4 +58,37 @@ class Uniform(Distribution):
         else:
             s = np.random.uniform(self.low, self.high, (N,self.dim)).T
 
-        return s
+        return s
+
+class UnboundedUniform(Distribution):
+    """
+    Unbounded uniform distribution. This is a special case of the
+    Uniform distribution, where the lower and upper bounds are set to
+    -inf and inf, respectively. This distribution is not normalizable,
+    and therefore cannot be sampled from. It is mainly used for
+    initializing non-informative priors.
+    Parameters
+    ----------
+    geometry : int or Geometry
+        The geometry of the distribution. If an integer is given, it is
+        interpreted as the dimension of the distribution. If a
+        Geometry object is given, its par_dim attribute is used.
+    """
+    def __init__(self, geometry, is_symmetric=True, **kwargs):
+        super().__init__(geometry=geometry, is_symmetric=is_symmetric, **kwargs) 
+
+    def logpdf(self, x):
+        """
+        Evaluate the logarithm of the unnormalized PDF at the given values of x.
+        """
+        # Always return 1.0 (the unnormalized log PDF)
+        return 1.0
+
+    def gradient(self, x):
+        """
+        Computes the gradient of logpdf at the given values of x.
+        """
+        return np.zeros_like(x)
+
+    def _sample(self, N=1, rng=None):
+        raise NotImplementedError("Cannot sample from UnboundedUniform distribution")

cuqi/experimental/__init__.py

@@ -1,2 +1,2 @@
-""" Experimental module for testing new features and ideas. """
-from . import mcmc
+""" Experimental module for testing new features and ideas.  """
+from ._recommender import SamplerRecommender

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/geometry/__init__.py

@@ -16,6 +16,8 @@ from ._geometry import (
     StepExpansion
 )
 
+from ._product_geometry import _ProductGeometry
+
 
 # TODO: We will remove the use of identity geometries in the future
 _identity_geometries = [_DefaultGeometry1D, _DefaultGeometry2D, Continuous1D, Continuous2D, Discrete, Image2D]

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"""
@@ -522,6 +533,9 @@ class Image2D(Geometry):
     Plotting is handled via matplotlib.pyplot.imshow.
     Colormap is defaulted to grayscale.
 
+    A How-To guide on the use of Image2D as the domain/range geometry of a CUQI 
+    :class:`Model` is available `here <https://cuqi-dtu.github.io/CUQIpy/user/_auto_howtos/Image2D.html>`_.
+
     Parameters
     -----------
     im_shape : tuple

cuqi/geometry/_product_geometry.py

@@ -0,0 +1,181 @@
+from cuqi.geometry import Geometry
+import numpy as np
+
+class _ProductGeometry(Geometry):
+    """ A class for representing a product geometry. A product geometry
+    represents the product space of multiple geometries of type :class:`Geometry`.
+    See the example below for a product geometry of two geometries.
+
+    Parameters
+    ----------
+    \*geometries : cuqi.geometry.Geometry
+        The geometries to be combined into a product geometry. Each geometry
+        is passed as a comma-separated argument.
+
+    Example
+    -------
+    .. code-block:: python
+        import numpy as np
+        from cuqi.geometry import Continuous1D, Discrete
+        from cuqi.geometry import _ProductGeometry
+        geometry1 = Continuous1D(np.linspace(0, 1, 100))
+        geometry2 = Discrete(["sound_speed"])
+        product_geometry = _ProductGeometry(geometry1, geometry2)
+    """
+
+    def __init__(self, *geometries):
+        self.geometries = geometries
+
+    @property
+    def geometries(self):
+        """List of geometries that are combined to form the product geometry."""
+        return self._geometries
+    
+    @geometries.setter
+    def geometries(self, geometries):
+        # Check if all geometries are of type Geometry.
+        for g in geometries:
+            if not isinstance(g, Geometry):
+                raise TypeError(
+                    "All geometries must be of type Geometry. "
+                    "Received: {}".format(type(g))
+                )
+        self._geometries = geometries
+
+    @property
+    def fun_shape(self):
+        """Shape of the function representation. Returns a tuple, where
+        each element of the tuple is the shape of the function 
+        representation of each geometry."""
+        return tuple([g.fun_shape for g in self.geometries])
+    
+    @property
+    def fun_dim(self):
+        """Dimension of the function representation which is the sum of
+        the function representation dimensions of each geometry."""
+        return sum([g.fun_dim for g in self.geometries])
+
+    @property
+    def par_shape(self):
+        """Shape of the parameter representation. Returns a tuple, where
+        each element of the tuple is the shape of the parameter
+        representation of each geometry."""
+        return tuple([g.par_shape for g in self.geometries])
+    
+    @property
+    def par_dim(self):
+        """Dimension of the parameter representation which is the sum of
+        the parameter representation dimensions of each geometry."""
+        return sum(self.par_dim_list)
+    
+    @property
+    def par_dim_list(self):
+        """List of the parameter representation dimensions of each
+        geometry. This property is useful for indexing a stacked parameter
+        vector."""
+        return [g.par_dim for g in self.geometries]
+    
+    @property
+    def stacked_par_split_indices(self):
+        """Indices at which the stacked parameter vector should be split
+        to obtain the parameter vectors for each geometry. For example, if
+        the stacked parameter vector is [1, 2, 3, 4, 5, 6] and the parameter
+        vectors for each geometry are [1, 2], [3, 4], and [5, 6], then the
+        split indices are [2, 4]"""
+        return np.cumsum(self.par_dim_list[:-1])
+
+    @property
+    def number_of_geometries(self):
+        """Number of geometries in the product geometry."""
+        return len(self.geometries)
+    
+    def _split_par(self, par):
+        """Splits a stacked parameter vector into parameter vectors for each
+        geometry."""
+        return tuple(np.split(par, self.stacked_par_split_indices))
+    
+    def _plot(self, values, **kwargs):
+        """Plotting function for the product geometry."""
+        raise NotImplementedError(
+            f"Plotting not implemented for {self.__class__.__name__}.")
+
+    def par2fun(self, *pars):
+        """Converts parameter vector(s) into function values for each 
+        geometry. The parameter vector can be stacked (all parameters are
+        in one vector) or unstacked (one parameter vector corresponds to
+        each geometry). In all cases, the order of the parameter vectors
+        should follow the order of the geometries in the product, i.e., the
+        first parameter vector corresponds to the first geometry and so on."""
+
+        # If one argument is passed, then it is assumed that the parameter
+        # vector is stacked and split it.
+        # No effect if the parameter vector is already split and corresponds
+        # to one geometry.
+        if len(pars) == 1:
+            pars = self._split_par(pars[0])
+
+        # Convert parameter vectors to function values for each geometry.
+        funvals = []
+        for i, g in enumerate(self.geometries):
+            funval_i = g.par2fun(pars[i])
+            funvals.append(funval_i)
+        return tuple(funvals)
+
+    def fun2par(self, *funvals, stacked=False):
+        """Converts (multiple) function values into the corresponding
+        parameter vectors. If the flag stacked is set to True, then the
+        parameter vectors are stacked into one vector. Otherwise, the
+        parameter vectors are returned as a tuple. The order of function
+        values should follow the order of the geometries in the product,
+        i.e., the first function value corresponds to the first geometry
+        and so on."""
+
+        pars = []
+        for i, g in enumerate(self.geometries):
+            par_i = g.fun2par(funvals[i])
+            pars.append(par_i)
+
+        # stack parameters:
+        if stacked:
+            # if single sample
+            if len(pars[0].shape) == 1:
+                stacked_val = np.hstack(pars)
+            elif len(pars[0].shape) == 2:
+                stacked_val = np.vstack(pars)
+            else:
+                raise ValueError(
+                    "Cannot stack parameter vectors with more than 2 dimensions."
+                    )
+
+        return  stacked_val if stacked else tuple(pars)
+
+    def vec2fun(self, *funvecs):
+        """Maps function vector representation, if available, to function 
+        values. The order of the function vectors should follow the order of
+        the geometries in the product, i.e., the first function vector
+        corresponds to the first geometry and so on."""
+        funvals = []  
+        for i, g in enumerate(self.geometries):
+            funvals.append(g.vec2fun(funvecs[i]))
+
+        return tuple(funvals)
+    
+    def fun2vec(self, *funvals):
+        """Maps function values to a vector representation of the function
+        values, if available. The order of the function values should follow
+        the order of the geometries in the product, i.e., the first function
+        value corresponds to the first geometry and so on."""
+        funvecs = []
+        for i, g in enumerate(self.geometries):
+            funvecs.append(g.fun2vec(funvals[i]))
+        
+        return tuple(funvecs)
+        
+    
+    def __repr__(self, pad="") -> str:
+        """Representation of the product geometry."""
+        string = "{}(".format(self.__class__.__name__) + "\n"
+        for g in self.geometries:
+            string += pad + "    {}\n".format(g.__repr__())
+        string += pad + ")"
+        return string

cuqi/implicitprior/__init__.py

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