CUQIpy 1.1.1.post0.dev38__tar.gz → 1.1.1.post0.dev78__tar.gz

{cuqipy-1.1.1.post0.dev38 → cuqipy-1.1.1.post0.dev78}/CUQIpy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: CUQIpy
-Version: 1.1.1.post0.dev38
+Version: 1.1.1.post0.dev78
 Summary: Computational Uncertainty Quantification for Inverse problems in Python
 Maintainer-email: "Nicolai A. B. Riis" <nabr@dtu.dk>, "Jakob S. Jørgensen" <jakj@dtu.dk>, "Amal M. Alghamdi" <amaal@dtu.dk>, Chao Zhang <chaz@dtu.dk>
 License:                                  Apache License

{cuqipy-1.1.1.post0.dev38 → cuqipy-1.1.1.post0.dev78}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: CUQIpy
-Version: 1.1.1.post0.dev38
+Version: 1.1.1.post0.dev78
 Summary: Computational Uncertainty Quantification for Inverse problems in Python
 Maintainer-email: "Nicolai A. B. Riis" <nabr@dtu.dk>, "Jakob S. Jørgensen" <jakj@dtu.dk>, "Amal M. Alghamdi" <amaal@dtu.dk>, Chao Zhang <chaz@dtu.dk>
 License:                                  Apache License

{cuqipy-1.1.1.post0.dev38 → cuqipy-1.1.1.post0.dev78}/cuqi/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2024-09-09T21:48:47+0200",
+ "date": "2024-09-11T08:37:02+0200",
  "dirty": false,
  "error": null,
- "full-revisionid": "98a74d508a1aa4659a6176a0126a90371a6be581",
- "version": "1.1.1.post0.dev38"
+ "full-revisionid": "e332fa9b589e70ff3171d724fcc381c556631eb4",
+ "version": "1.1.1.post0.dev78"
 }
 '''  # END VERSION_JSON
 

{cuqipy-1.1.1.post0.dev38 → cuqipy-1.1.1.post0.dev78}/cuqi/array/_array.py

@@ -15,19 +15,7 @@ class CUQIarray(np.ndarray):
         Boolean flag whether input_array is to be interpreted as parameter (True) or function values (False).
 
     geometry : cuqi.geometry.Geometry, default None
-        Contains the geometry related of the data
-
-    Attributes
-    ----------
-    funvals : CUQIarray
-        Returns itself as function values.
-
-    parameters : CUQIarray
-        Returns itself as parameters.
-
-    Methods
-    ----------
-    :meth:`plot`: Plots the data as function or parameters.
+        Contains the geometry related of the data.
     """
 
     def __repr__(self) -> str: 
@@ -62,6 +50,7 @@ class CUQIarray(np.ndarray):
 
     @property
     def funvals(self):
+        """ Returns itself as function values. """
         if self.is_par is True:
             vals = self.geometry.par2fun(self)
         else:
@@ -82,6 +71,7 @@ class CUQIarray(np.ndarray):
 
     @property
     def parameters(self):
+        """ Returns itself as parameters. """
         if self.is_par is False:
             if self.dtype == np.dtype('O'):
                 # If the current state if the CUQIarray is function values, and
@@ -109,6 +99,7 @@ class CUQIarray(np.ndarray):
                 f"Cannot convert {self.__class__.__name__} to numpy array")
 
     def plot(self, plot_par=False, **kwargs):
+        """ Plot the data as function or parameters. """
         if plot_par:
             kwargs["is_par"]=True
             return self.geometry.plot(self.parameters, plot_par=plot_par, **kwargs)

{cuqipy-1.1.1.post0.dev38 → cuqipy-1.1.1.post0.dev78}/cuqi/distribution/_beta.py

@@ -9,23 +9,19 @@ class Beta(Distribution):
     """
     Multivariate beta distribution of independent random variables x_i. Each is distributed according to the PDF function
 
-    f(x) = x^(alpha-1) * (1-x)^(beta-1) * Gamma(alpha+beta) / (Gamma(alpha)*Gamma(beta))
+    .. math::
 
-    where Gamma is the Gamma function.
+        f(x) = x^{(\\alpha-1)}(1-x)^{(\\beta-1)}\Gamma(\\alpha+\\beta) / (\Gamma(\\alpha)\Gamma(\\beta))
+
+    where :math:`\Gamma` is the Gamma function.
 
     Parameters
     ------------
     alpha: float or array_like
+           The shape parameter :math:`\\alpha` of the beta distribution.
 
     beta: float or array_like
-
-    Methods
-    -----------
-    sample: generate one or more random samples
-    pdf: evaluate probability density function
-    logpdf: evaluate log probability density function
-    cdf: evaluate cumulative probability function
-    gradient: evaluate the gradient of the logpdf
+          The shape parameter :math:`\\beta` of the beta distribution.
     
     Example
     -------

{cuqipy-1.1.1.post0.dev38 → cuqipy-1.1.1.post0.dev78}/cuqi/distribution/_custom.py

@@ -12,12 +12,6 @@ class UserDefinedDistribution(Distribution):
     gradient_func: Function evaluating the gradient of the logpdf. Callable.
     sample_func: Function drawing samples from distribution. Callable.
     
-    Methods
-    -----------
-    sample: generate one or more random samples
-    logpdf: evaluate log probability density function
-    gradient: evaluate gradient of logpdf
-    
     Example
     -----------
     .. code-block:: python

{cuqipy-1.1.1.post0.dev38 → cuqipy-1.1.1.post0.dev78}/cuqi/distribution/_distribution.py

@@ -28,37 +28,6 @@ class Distribution(Density, ABC):
     is_symmetric : bool, default None
         Indicator if distribution is symmetric.
 
-    Attributes
-    ----------
-    dim : int or None
-        Dimension of distribution.
-
-    name : str or None
-        Name of distribution.
-    
-    geometry : Geometry or None
-        Geometry of distribution.
-
-    is_cond : bool
-        Indicator if distribution is conditional.
-
-    Methods
-    -------
-    pdf():
-        Evaluate the probability density function.
-
-    logpdf():
-        Evaluate the log probability density function.
-
-    sample():
-        Generate one or more random samples.
-
-    get_conditioning_variables():
-        Return the conditioning variables of distribution.
-
-    get_mutable_variables():
-        Return the mutable variables (attributes and properties) of distribution.
-
     Notes
     -----
     A distribution can be conditional if one or more mutable variables are unspecified.
@@ -239,6 +208,7 @@ class Distribution(Density, ABC):
             "enable_FD().")
 
     def sample(self,N=1,*args,**kwargs):
+        """ Sample from the distribution. """
 
         if self.is_cond:
             raise ValueError(f"Cannot sample from conditional distribution. Missing conditioning variables: {self.get_conditioning_variables()}")
@@ -263,6 +233,7 @@ class Distribution(Density, ABC):
         pass
 
     def pdf(self,x):
+        """ Evaluate the log probability density function of the distribution. """
         return np.exp(self.logpdf(x))
 
     def _condition(self, *args, **kwargs):

{cuqipy-1.1.1.post0.dev38 → cuqipy-1.1.1.post0.dev78}/cuqi/distribution/_gamma.py

@@ -6,14 +6,18 @@ from cuqi.utilities import force_ndarray
 class Gamma(Distribution):
     """
     Represents a multivariate Gamma distribution characterized by shape and rate parameters of independent random variables x_i. Each is distributed according to the PDF function
+
+    .. math::
     
-    f(x_i; shape, rate) = rate^shape * x_i^(shape-1) * exp(-rate * x_i) / Gamma(shape)
+        f(x_i; \\alpha, \\beta) = \\beta^\\alpha x_i^{\\alpha-1} \\exp(-\\beta x_i) / \Gamma(\\alpha)
 
-    where `shape` and `rate` are the parameters of the distribution, and Gamma is the Gamma function.
+    where shape :math:`\\alpha` and rate :math:`\\beta` are the parameters of the distribution, and :math:`\Gamma` is the Gamma function.
 
     In case shape and/or rate are arrays, the pdf looks like
 
-    f(x_i; shape_i, rate_i) = rate_i^shape_i * x_i^(shape_i-1) * exp(-rate_i * x_i) / Gamma(shape_i)
+    .. math::
+    
+        f(x_i; \\alpha_i, \\beta_i) = \\beta_i^{\\alpha_i} x_i^{\\alpha_i-1} \\exp(-\\beta_i x_i) / \Gamma(\\alpha_i)
 
     Parameters
     ----------

{cuqipy-1.1.1.post0.dev38 → cuqipy-1.1.1.post0.dev78}/cuqi/distribution/_gaussian.py

@@ -730,18 +730,6 @@ class JointGaussianSqrtPrec(Distribution):
     ------------
     means: List of means for each Gaussian distribution.
     sqrtprecs: List of sqrt precision matricies for each Gaussian distribution.
-
-    Attributes
-    ------------
-    sqrtprec: Returns the sqrt precision matrix of the joined gaussian in stacked form.
-    sqrtprecTimesMean: Returns the sqrt precision matrix times the mean of the distribution.
-    
-    Methods
-    -----------
-    sample: generate one or more random samples (NotImplemented)
-    pdf: evaluate probability density function (NotImplemented)
-    logpdf: evaluate log probability density function (NotImplemented)
-    cdf: evaluate cumulative probability function (NotImplemented)
     """    
     def __init__(self,means=None,sqrtprecs=None,is_symmetric=True,**kwargs):
 
@@ -783,6 +771,7 @@ class JointGaussianSqrtPrec(Distribution):
 
     @property
     def sqrtprec(self):
+        """ Returns the sqrt precision matrix of the joined gaussian in stacked form. """
         if spa.issparse(self._sqrtprecs[0]):
             return spa.vstack((self._sqrtprecs))
         else:
@@ -790,6 +779,7 @@ class JointGaussianSqrtPrec(Distribution):
 
     @property
     def sqrtprecTimesMean(self):
+        """ Returns the sqrt precision matrix times the mean of the distribution."""
         result = []
         for i in range(len(self._means)):
             result.append((self._sqrtprecs[i]@self._means[i]).flatten())

{cuqipy-1.1.1.post0.dev38 → cuqipy-1.1.1.post0.dev78}/cuqi/distribution/_inverse_gamma.py

@@ -8,9 +8,11 @@ class InverseGamma(Distribution):
     """
     Multivariate inverse gamma distribution of independent random variables x_i. Each is distributed according to the PDF function
 
-    f(x) = (x-location)^(-shape-1) * exp(-scale/(x-location)) / (scale^(-shape)*Gamma(shape))
+    .. math::
 
-    where shape, location and scale are the shape, location and scale of x_i, respectively. And Gamma is the Gamma function.
+        f(x) = (x-\\beta)^{(-\\alpha-1)} * \exp(-\\gamma/(x-\\beta)) / (\\gamma^{(-\\alpha)}*\Gamma(\\alpha))
+
+    where shape :math:`\\alpha`, location :math:`\\beta` and scale :math:`\\gamma` are the shape, location and scale of x_i, respectively. And :math:`\Gamma` is the Gamma function.
 
     Parameters
     ------------
@@ -23,14 +25,6 @@ class InverseGamma(Distribution):
     scale: float or array_like
         The scale of the inverse gamma distribution (non-negative)
 
-    
-    Methods
-    -----------
-    sample: generate one or more random samples
-    pdf: evaluate probability density function
-    logpdf: evaluate log probability density function
-    cdf: evaluate cumulative probability function
-    
     Example
     -------
     .. code-block:: python

{cuqipy-1.1.1.post0.dev38 → cuqipy-1.1.1.post0.dev78}/cuqi/distribution/_lognormal.py

@@ -16,13 +16,6 @@ class Lognormal(Distribution):
     cov: np.ndarray
         Covariance matrix of the normal distribution used to define the lognormal distribution 
     
-    Methods
-    -----------
-    sample: generate one or more random samples
-    pdf: evaluate probability density function
-    logpdf: evaluate log probability density function
-    cdf: evaluate cumulative probability function
-    
     Example
     -------
     .. code-block:: python

{cuqipy-1.1.1.post0.dev38 → cuqipy-1.1.1.post0.dev78}/cuqi/distribution/_modifiedhalfnormal.py

@@ -7,14 +7,17 @@ from cuqi.utilities import force_ndarray
 class ModifiedHalfNormal(Distribution):
     """
     Represents a modified half-normal (MHN) distribution, a three-parameter family of distributions generalizing the Gamma distribution.
-    The distribution is continuous with pdf 
-    f(x; alpha, beta, gamma) propto x^(alpha-1) * exp(-beta * x^2 + gamma * x)
+    The distribution is continuous with pdf
+
+    .. math::
+    
+        f(x; \\alpha, \\beta, \\gamma) \propto x^{(\\alpha-1)} * \exp(-\\beta * x^2 + \\gamma * x)
 
     The MHN generalizes the half-normal distribution, because
-    f(x; 1, beta, 0) propto exp(-beta * x^2)
+    :math:`f(x; 1, \\beta, 0) \propto \exp(-\\beta * x^2)`
 
     The MHN generalizes the gamma distribution because
-    f(x; alpha, 0, -gamma) propto x^(alpha-1) * exp(- gamma * x)
+    :math:`f(x; \\alpha, 0, -\\gamma) \propto x^{(\\alpha-1)} * \exp(- \\gamma * x)`
 
     Reference:
     [1] Sun, et al. "The Modified-Half-Normal distribution: Properties and an efficient sampling scheme." Communications in Statistics-Theory and Methods
@@ -22,13 +25,13 @@ class ModifiedHalfNormal(Distribution):
     Parameters
     ----------
     alpha : float
-        The polynomial exponent parameter of the MHN distribution. Must be positive.
+        The polynomial exponent parameter :math:`\\alpha` of the MHN distribution. Must be positive.
 
     beta : float
-        The quadratic exponential parameter of the MHN distribution. Must be positive.
+        The quadratic exponential parameter :math:`\\beta` of the MHN distribution. Must be positive.
 
     gamma : float
-        The linear exponential parameter of the MHN distribution.
+        The linear exponential parameter :math:`\\gamma` of the MHN distribution.
 
     """
     def __init__(self, alpha=None, beta=None, gamma=None, is_symmetric=False, **kwargs):

{cuqipy-1.1.1.post0.dev38 → cuqipy-1.1.1.post0.dev78}/cuqi/distribution/_normal.py

@@ -12,13 +12,6 @@ class Normal(Distribution):
     mean: mean of distribution
     std: standard deviation
     
-    Methods
-    -----------
-    sample: generate one or more random samples
-    pdf: evaluate probability density function
-    logpdf: evaluate log probability density function
-    cdf: evaluate cumulative probability function
-    
     Example
     -----------
     .. code-block:: python

{cuqipy-1.1.1.post0.dev38 → cuqipy-1.1.1.post0.dev78}/cuqi/experimental/mcmc/_gibbs.py

@@ -1,6 +1,7 @@
 from cuqi.distribution import JointDistribution
 from cuqi.experimental.mcmc import Sampler
 from cuqi.samples import Samples
+from cuqi.experimental.mcmc import NUTS
 from typing import Dict
 import numpy as np
 import warnings
@@ -151,18 +152,50 @@ class HybridGibbs:
             sampler.validate_target()
 
     def sample(self, Ns) -> 'HybridGibbs':
-        """ Sample from the joint distribution using Gibbs sampling """
+        """ Sample from the joint distribution using Gibbs sampling
+
+        Parameters
+        ----------
+        Ns : int
+            The number of samples to draw.
+
+        """
+
         for _ in tqdm(range(Ns)):
+
             self.step()
+
             self._store_samples()
 
-    def warmup(self, Nb) -> 'HybridGibbs':
-        """ Warmup (tune) the Gibbs sampler """
+        return self
+
+    def warmup(self, Nb, tune_freq=0.1) -> 'HybridGibbs':
+        """ Warmup (tune) the samplers in the Gibbs sampling scheme
+
+        Parameters
+        ----------
+        Nb : int
+            The number of samples to draw during warmup.
+
+        tune_freq : float, optional
+            Frequency of tuning the samplers. Tuning is performed every tune_freq*Nb steps.
+
+        """
+
+        tune_interval = max(int(tune_freq * Nb), 1)
+
         for idx in tqdm(range(Nb)):
+
             self.step()
-            self.tune(idx)
+
+            # Tune the sampler at tuning intervals (matching behavior of Sampler class)
+            if (idx + 1) % tune_interval == 0:
+                self.tune(tune_interval, idx // tune_interval) 
+                
             self._store_samples()
 
+        return self
+
     def get_samples(self) -> Dict[str, Samples]:
         samples_object = {}
         for par_name in self.par_names:
@@ -182,38 +215,65 @@ class HybridGibbs:
             # Get sampler
             sampler = self.samplers[par_name]
 
-            # Set initial parameters using current point and scale (subset of state)
-            # This does not store the full state from e.g. NUTS sampler
-            # But works on samplers like MH, PCN, ULA, MALA, LinearRTO, UGLA, CWMH
-            # that only use initial_point and initial_scale
-            sampler.initial_point = self.current_samples[par_name]
-            if hasattr(sampler, 'initial_scale'): sampler.initial_scale = sampler.scale
+            # Instead of simply changing the target of the sampler, we reinitialize it.
+            # This is to ensure that all internal variables are set to match the new target.
+            # To return the sampler to the old state and history, we first extract the state and history
+            # before reinitializing the sampler and then set the state and history back to the sampler
+
+            # Extract state and history from sampler
+            if isinstance(sampler, NUTS): # Special case for NUTS as it is not playing nice with get_state and get_history
+                sampler.initial_point = sampler.current_point
+            else:
+                sampler_state = sampler.get_state()
+                sampler_history = sampler.get_history()
 
             # Reinitialize sampler
-            # This makes the sampler lose all of its state.
-            # This is only OK because we set the initial values above from the previous state
             sampler.reinitialize()
 
+            # Set state and history back to sampler
+            if not isinstance(sampler, NUTS): # Again, special case for NUTS.
+                sampler.set_state(sampler_state)
+                sampler.set_history(sampler_history)
+
             # Run pre_warmup and pre_sample methods for sampler
             # TODO. Some samplers (NUTS) seem to require to run _pre_warmup before _pre_sample
             self._pre_warmup_and_pre_sample_sampler(sampler)
 
-            # Take MCMC steps
+            # Allow for multiple sampling steps in each Gibbs step
             for _ in range(self.num_sampling_steps[par_name]):
-                sampler.step()
+                # Sampling step
+                acc = sampler.step()
+
+                # Store acceptance rate in sampler (matching behavior of Sampler class Sample method)
+                sampler._acc.append(acc)
 
             # Extract samples (Ensure even 1-dimensional samples are 1D arrays)
-            self.current_samples[par_name] = sampler.current_point.reshape(-1)
+            if isinstance(sampler.current_point, np.ndarray):
+                self.current_samples[par_name] = sampler.current_point.reshape(-1)
+            else:
+                self.current_samples[par_name] = sampler.current_point
+
+    def tune(self, skip_len, update_count):
+        """ Run a single tuning step on each of the samplers in the Gibbs sampling scheme
+
+        Parameters
+        ----------
+        skip_len : int
+            Defines the number of steps in between tuning (i.e. the tuning interval).
+
+        update_count : int
+            The number of times tuning has been performed. Can be used for internal bookkeeping.
 
-    def tune(self, idx):
-        """ Tune each of the samplers """
+        """
         for par_name in self.par_names:
-            self.samplers[par_name].tune(skip_len=1, update_count=idx)
+            self.samplers[par_name].tune(skip_len=skip_len, update_count=update_count)
 
     # ------------ Private methods ------------
     def _initialize_samplers(self):
         """ Initialize samplers """
         for sampler in self.samplers.values():
+            if isinstance(sampler, NUTS):
+                print(f'Warning: NUTS sampler is not fully stateful in HybridGibbs. Sampler will be reinitialized in each Gibbs step.')
             sampler.initialize()
 
     def _initialize_num_sampling_steps(self):

{cuqipy-1.1.1.post0.dev38 → cuqipy-1.1.1.post0.dev78}/cuqi/samples/_samples.py

@@ -36,24 +36,6 @@ class Samples(object):
     geometry : cuqi.geometry.Geometry, default None
         Contains the geometry related of the samples
 
-    Attributes
-    ----------
-    shape : tuple
-        Returns the shape of samples.
-
-    Ns : int
-        Returns the number of samples
-
-    Methods
-    ----------
-    :meth:`plot`: Plots one or more samples.
-    :meth:`plot_ci`: Plots a credibility interval for the samples.
-    :meth:`plot_mean`: Plots the mean of the samples.
-    :meth:`plot_std`: Plots the std of the samples.
-    :meth:`plot_chain`: Plots all samples of one or more variables (MCMC chain).
-    :meth:`hist_chain`: Plots histogram of all samples of a single variable (MCMC chain).
-    :meth:`burnthin`: Removes burn-in and thins samples.
-    :meth:`diagnostics`: Conducts diagnostics on the chain.
     """
     def __init__(self, samples, geometry=None, is_par=True, is_vec=True):
         self.geometry = geometry
@@ -83,6 +65,7 @@ class Samples(object):
 
     @property
     def shape(self):
+        """Returns the shape of samples."""
         return self.samples.shape
 
     @property
@@ -408,6 +391,7 @@ class Samples(object):
         return ax
 
     def plot(self,sample_indices=None,*args,**kwargs):
+        """ Plots one or more samples. """
         Ns = self.Ns
         Np = 5 # Number of samples to plot if Ns > 5
 
@@ -447,6 +431,7 @@ class Samples(object):
         return lines
     
     def hist_chain(self,variable_indices,*args,**kwargs):
+        """ Plots samples histogram of variables with indices specified in variable_indices. """
 
         self._raise_error_if_not_vec(self.hist_chain.__name__)
 
@@ -580,6 +565,7 @@ class Samples(object):
 
 
     def diagnostics(self):
+        """ Conducts diagnostics on the chain (Geweke test). """
         # Geweke test
         Geweke(self.samples.T)
 

{cuqipy-1.1.1.post0.dev38 → cuqipy-1.1.1.post0.dev78}/cuqi/solver/_solver.py

@@ -174,9 +174,12 @@ class LS(object):
     """Wrapper for :meth:`scipy.optimize.least_squares`.
 
     Solve nonlinear least-squares problems with bounds:
+
+    .. math::
     
-    minimize F(x) = 0.5 * sum(rho(f_i(x)**2), i = 0, ..., m-1)
-    subject to lb <= x <= ub
+        \min F(x) = 0.5 * \sum(\\rho(f_i(x)^2), i = 0, ..., m-1)
+
+    subject to :math:`lb <= x <= ub`.
     
     Parameters
     ----------