added all the docstrings for PowerSpace and changed PowerSpace.log to...

added all the docstrings for PowerSpace and changed PowerSpace.log to PowerSpace.logarithmic as well as PowerSpace.harmonic_domain to harmonic_partner

nifty/field.py

@@ -167,7 +167,7 @@ class Field(Loggable, Versionable, object):
 
     # ---Powerspectral methods---
 
-    def power_analyze(self, spaces=None, log=False, nbin=None, binbounds=None,
+    def power_analyze(self, spaces=None, logarithmic=False, nbin=None, binbounds=None,
                       decompose_power=False):
         # check if all spaces in `self.domain` are either harmonic or
         # power_space instances
@@ -210,10 +210,10 @@ class Field(Loggable, Versionable, object):
             self.val.get_axes_local_distribution_strategy(
                 self.domain_axes[space_index])
 
-        harmonic_domain = self.domain[space_index]
-        power_domain = PowerSpace(harmonic_domain=harmonic_domain,
+        harmonic_partner = self.domain[space_index]
+        power_domain = PowerSpace(harmonic_partner=harmonic_partner,
                                   distribution_strategy=distribution_strategy,
-                                  log=log, nbin=nbin, binbounds=binbounds)
+                                  logarithmic=logarithmic, nbin=nbin, binbounds=binbounds)
 
         # extract pindex and rho from power_domain
         pindex = power_domain.pindex
@@ -221,7 +221,7 @@ class Field(Loggable, Versionable, object):
 
         if decompose_power:
             hermitian_part, anti_hermitian_part = \
-                harmonic_domain.hermitian_decomposition(
+                harmonic_partner.hermitian_decomposition(
                                             self.val,
                                             axes=self.domain_axes[space_index])
 
@@ -322,8 +322,8 @@ class Field(Loggable, Versionable, object):
         result_domain = list(self.domain)
         for power_space_index in spaces:
             power_space = self.domain[power_space_index]
-            harmonic_domain = power_space.harmonic_domain
-            result_domain[power_space_index] = harmonic_domain
+            harmonic_partner = power_space.harmonic_partner
+            result_domain[power_space_index] = harmonic_partner
 
         # create random samples: one or two, depending on whether the
         # power spectrum is real or complex
@@ -365,8 +365,8 @@ class Field(Loggable, Versionable, object):
 
         if real_signal:
             for power_space_index in spaces:
-                harmonic_domain = result_domain[power_space_index]
-                result_val_list = [harmonic_domain.hermitian_decomposition(
+                harmonic_partner = result_domain[power_space_index]
+                result_val_list = [harmonic_partner.hermitian_decomposition(
                                     result_val,
                                     axes=result.domain_axes[power_space_index],
                                     preserve_gaussian_variance=True)[0]

nifty/spaces/lm_space/lm_space.py

@@ -66,7 +66,7 @@ class LMSpace(Space):
 
     def __init__(self, lmax):
         """
-            Sets the attributes for an lm_space class instance.
+            Sets the attributes for a lm_space class instance.
 
             Parameters
             ----------

nifty/spaces/power_space/power_index_factory.py

@@ -24,15 +24,15 @@ class _PowerIndexFactory(object):
         self.power_indices_storage = {}
 
     def get_power_index(self, domain, distribution_strategy,
-                        log=False, nbin=None, binbounds=None):
+                        logarithmic=False, nbin=None, binbounds=None):
         key = (domain, distribution_strategy)
 
         if key not in self.power_indices_storage:
             self.power_indices_storage[key] = \
                 PowerIndices(domain, distribution_strategy,
-                             log=log, nbin=nbin, binbounds=binbounds)
+                             logarithmic=logarithmic, nbin=nbin, binbounds=binbounds)
         power_indices = self.power_indices_storage[key]
-        power_index = power_indices.get_index_dict(log=log,
+        power_index = power_indices.get_index_dict(logarithmic=logarithmic,
                                                    nbin=nbin,
                                                    binbounds=binbounds)
         return power_index

nifty/spaces/power_space/power_indices.py

@@ -26,7 +26,7 @@ from d2o.config import configuration as d2o_config
 
 class PowerIndices(object):
     def __init__(self, domain, distribution_strategy,
-                 log=False, nbin=None, binbounds=None):
+                 logarithmic=False, nbin=None, binbounds=None):
         """
             Returns an instance of the PowerIndices class. Given the shape and
             the density of a underlying rectangular grid it provides the user
@@ -42,7 +42,7 @@ class PowerIndices(object):
             dgrid : tuple, list, ndarray
                 Array-like object which specifies the step-width of the
                 underlying grid
-            log : bool *optional*
+            logarithmic : bool *optional*
                 Flag specifying if the binning of the default indices is
                 performed on logarithmic scale.
             nbin : integer *optional*
@@ -59,7 +59,7 @@ class PowerIndices(object):
         # Initialize the dictionary which stores all individual index-dicts
         self.global_dict = {}
         # Set self.default_parameters
-        self.set_default(config_dict={'log': log,
+        self.set_default(config_dict={'logarithmic': logarithmic,
                                       'nbin': nbin,
                                       'binbounds': binbounds})
 
@@ -88,7 +88,7 @@ class PowerIndices(object):
 
             Parameters
             ----------
-            log : bool
+            logarithmic : bool
                 Flag specifying if the binning is performed on logarithmic
                 scale.
             nbin : integer
@@ -113,24 +113,24 @@ class PowerIndices(object):
             return self._cast_config_helper(**temp_config_dict)
         else:
             defaults = self.default_parameters
-            temp_log = kwargs.get("log", defaults['log'])
+            temp_logarithmic = kwargs.get("logarithmic", defaults['logarithmic'])
             temp_nbin = kwargs.get("nbin", defaults['nbin'])
             temp_binbounds = kwargs.get("binbounds", defaults['binbounds'])
 
-            return self._cast_config_helper(log=temp_log,
+            return self._cast_config_helper(logarithmic=temp_logarithmic,
                                             nbin=temp_nbin,
                                             binbounds=temp_binbounds)
 
-    def _cast_config_helper(self, log, nbin, binbounds):
+    def _cast_config_helper(self, logarithmic, nbin, binbounds):
         """
             internal helper function which sets the defaults for the
             _cast_config function
         """
 
         try:
-            temp_log = bool(log)
+            temp_logarithmic = bool(logarithmic)
         except(TypeError):
-            temp_log = False
+            temp_logarithmic = False
 
         try:
             temp_nbin = int(nbin)
@@ -142,7 +142,7 @@ class PowerIndices(object):
         except(TypeError):
             temp_binbounds = None
 
-        temp_dict = {"log": temp_log,
+        temp_dict = {"logarithmic": temp_logarithmic,
                      "nbin": temp_nbin,
                      "binbounds": temp_binbounds}
         return temp_dict
@@ -158,7 +158,7 @@ class PowerIndices(object):
             store : bool
                 Flag specifying if  the calculated index dictionary should be
                 stored in the global_dict for future use.
-            log : bool
+            logarithmic : bool
                 Flag specifying if the binning is performed on logarithmic
                 scale.
             nbin : integer
@@ -210,7 +210,7 @@ class PowerIndices(object):
         """
         # if no binning is requested, compute the indices, build the dict,
         # and return it straight.
-        if not config_dict["log"] and config_dict["nbin"] is None and \
+        if not config_dict["logarithmic"] and config_dict["nbin"] is None and \
                 config_dict["binbounds"] is None:
             (temp_pindex, temp_kindex, temp_rho, temp_pundex) =\
                 self._compute_indices(self.k_array)
@@ -222,7 +222,7 @@ class PowerIndices(object):
             # Get the unbinned indices
             temp_unbinned_indices = self.get_index_dict(nbin=None,
                                                         binbounds=None,
-                                                        log=False,
+                                                        logarithmic=False,
                                                         store=False)
             # Bin them
             (temp_pindex, temp_kindex, temp_rho, temp_pundex) = \
@@ -344,7 +344,7 @@ class PowerIndices(object):
                 Array of all k-vector lengths.
             rho : ndarray
                 Degeneracy factor of the individual k-vectors.
-            log : bool
+            logarithmic : bool
                 Flag specifying if the binning is performed on logarithmic
                 scale.
             nbin : integer
@@ -361,7 +361,7 @@ class PowerIndices(object):
         """
         # Cast the given config
         temp_config_dict = self._cast_config(**kwargs)
-        log = temp_config_dict['log']
+        logarithmic = temp_config_dict['logarithmic']
         nbin = temp_config_dict['nbin']
         binbounds = temp_config_dict['binbounds']
 
@@ -375,9 +375,9 @@ class PowerIndices(object):
             binbounds = np.sort(binbounds)
         # equal binning
         else:
-            if(log is None):
-                log = False
-            if(log):
+            if(logarithmic is None):
+                logarithmic = False
+            if(logarithmic):
                 k = np.r_[0, np.log(kindex[1:])]
             else:
                 k = kindex
@@ -391,7 +391,7 @@ class PowerIndices(object):
                 dk = (k[-1] - 0.5 * (k[2] + k[1])) / (nbin - 2.5)
             binbounds = np.r_[0.5 * (3 * k[1] - k[2]),
                               0.5 * (k[1] + k[2]) + dk * np.arange(nbin - 2)]
-            if(log):
+            if(logarithmic):
                 binbounds = np.exp(binbounds)
         # reordering
         reorder = np.searchsorted(binbounds, kindex)

nifty/spaces/power_space/power_space.py

@@ -30,31 +30,63 @@ class PowerSpace(Space):
 
     # ---Overwritten properties and methods---
 
-    def __init__(self, harmonic_domain=RGSpace((1,)),
+    def __init__(self, harmonic_partner=RGSpace((1,)),
                  distribution_strategy='not',
-                 log=False, nbin=None, binbounds=None):
-
+                 logarithmic=False, nbin=None, binbounds=None):
+        """Sets the attributes for a PowerSpace class instance.
+
+            Parameters
+            ----------
+            harmonic_partner : Space
+                The harmonic Space of which this is the power space.
+            distribution_strategy : str *optional*
+                The distribution strategy of a d2o-object represeting a field over this PowerSpace.
+                (default : 'not')
+            logarithmic : bool *optional*
+                True if logarithmic binning should be used.
+                (default : False)
+            nbin : {int, None} *optional*
+                The number of bins this space has.
+                (default : None) if nbin == None : It takes the nbin from its harmonic_partner
+            binbounds :  {list, array} *optional*
+                Array-like inner boundaries of the used bins of the default
+                indices.
+                (default : None) if binbounds == None : Calculates the bounds from the kindex and corrects for logartihmic scale 
+            Notes
+            -----
+            A power space is the result of a projection of a harmonic space where multiple k-modes get mapped to one power index.
+            This can be regarded as a response operator :math:`R` going from harmonic space to power space. 
+            An array giving this map is stored in pindex (array which says in which power box a k-mode gets projected)
+            An array for the adjoint of :math:`R` is given by kindex, which is an array of arrays stating which k-mode got mapped to a power index
+            The a right-inverse to :math:`R` is given by the pundex which is an array giving one k-mode that maps to a power bin for every power bin.
+            The amount of k-modes that get mapped to one power bin is given by rho. This is :math:`RR^\dagger` in the language of this projection operator            
+            Returns
+            -------
+            None.
+
+        """
+        #FIXME: default probably not working for log and normal scale
         super(PowerSpace, self).__init__()
         self._ignore_for_hash += ['_pindex', '_kindex', '_rho', '_pundex',
                                   '_k_array']
 
-        if not isinstance(harmonic_domain, Space):
+        if not isinstance(harmonic_partner, Space):
             raise ValueError(
-                "harmonic_domain must be a Space.")
-        if not harmonic_domain.harmonic:
+                "harmonic_partner must be a Space.")
+        if not harmonic_partner.harmonic:
             raise ValueError(
-                "harmonic_domain must be a harmonic space.")
-        self._harmonic_domain = harmonic_domain
+                "harmonic_partner must be a harmonic space.")
+        self._harmonic_partner = harmonic_partner
 
         power_index = PowerIndexFactory.get_power_index(
-                        domain=self.harmonic_domain,
+                        domain=self.harmonic_partner,
                         distribution_strategy=distribution_strategy,
-                        log=log,
+                        logarithmic=logarithmic,
                         nbin=nbin,
                         binbounds=binbounds)
 
         config = power_index['config']
-        self._log = config['log']
+        self._logarithmic = config['logarithmic']
         self._nbin = config['nbin']
         self._binbounds = config['binbounds']
 
@@ -65,6 +97,22 @@ class PowerSpace(Space):
         self._k_array = power_index['k_array']
 
     def pre_cast(self, x, axes=None):
+        """Casts power spectra to discretized power spectra.
+        
+        This function takes an array or a function. If it is an array it does nothing,
+        otherwise it intepretes the function as power spectrum and evaluates it at every
+        k-mode.
+        Parameters
+        ----------
+        x : {array-like, function array-like -> array-like}
+            power spectrum given either in discretized form or implicitly as a function
+        axes : {tuple, int} *optional*
+            does nothing
+            (default : None)
+        Returns
+        -------
+        array-like : discretized power spectrum
+        """
         if callable(x):
             return x(self.kindex)
         else:
@@ -91,9 +139,9 @@ class PowerSpace(Space):
 
     def copy(self):
         distribution_strategy = self.pindex.distribution_strategy
-        return self.__class__(harmonic_domain=self.harmonic_domain,
+        return self.__class__(harmonic_partner=self.harmonic_partner,
                               distribution_strategy=distribution_strategy,
-                              log=self.log,
+                              logarithmic=self.logarithmic,
                               nbin=self.nbin,
                               binbounds=self.binbounds)
 
@@ -127,39 +175,87 @@ class PowerSpace(Space):
     # ---Added properties and methods---
 
     @property
-    def harmonic_domain(self):
-        return self._harmonic_domain
+    def harmonic_partner(self):
+        """Returns the Space of which this is the power space.
+        Returns
+        -------
+        Space : The harmonic Space of which this is the power space.
+        """
+        return self._harmonic_partner
 
     @property
-    def log(self):
-        return self._log
+    def logarithmic(self):
+        """Returns a True if logarithmic binning is used.
+        Returns
+        -------
+        Bool : True if for this PowerSpace logarithmic binning is used.
+        """
+        return self._logarithmic
 
     @property
     def nbin(self):
+        """Returns the number of power bins.
+        Returns
+        -------
+        int : The number of bins this space has.
+        """
         return self._nbin
 
     @property
     def binbounds(self):
+        """ Inner boundaries of the used bins of the default
+                indices.
+        Returns
+        -------
+        {list, array} : the inner boundaries of the used bins in the used scale, as they were
+        set in __init__ or computed.
+        """
+        # FIXME check wether this returns something sensible if 'None' was set in __init__
         return self._binbounds
 
     @property
     def pindex(self):
+    """Index of the Fourier grid points that belong to a specific power index
+    Returns
+    -------
+        distributed_data_object : Index of the Fourier grid points in a distributed_data_object.
+    """
         return self._pindex
 
     @property
     def kindex(self):
+    """Array of all k-vector lengths.
+    Returns
+    -------
+        ndarray : Array which states for each k-mode which power index it maps to (adjoint to pindex)
+    """
         return self._kindex
 
     @property
     def rho(self):
+    """Degeneracy factor of the individual k-vectors.
+    
+    ndarray : Array stating how many k-modes are mapped to one power index for every power index
+    """
         return self._rho
 
     @property
     def pundex(self):
+    """List of one k-mode per power bin which is in the bin.
+    Returns
+    -------
+    array-like : An array for which the n-th entry is an example one k-mode which belongs to the n-th power bin
+    """
         return self._pundex
 
     @property
     def k_array(self):
+    """This contains distances to zero for every k-mode of the harmonic partner.
+    
+    Returns
+    -------
+    array-like : An array containing distances to the zero mode for every k-mode of the harmonic partner.
+    """
         return self._k_array
 
     # ---Serialization---
@@ -168,13 +264,13 @@ class PowerSpace(Space):
         hdf5_group['kindex'] = self.kindex
         hdf5_group['rho'] = self.rho
         hdf5_group['pundex'] = self.pundex
-        hdf5_group['log'] = self.log
+        hdf5_group['logarithmic'] = self.logarithmic
         # Store nbin as string, since it can be None
         hdf5_group.attrs['nbin'] = str(self.nbin)
         hdf5_group.attrs['binbounds'] = str(self.binbounds)
 
         return {
-            'harmonic_domain': self.harmonic_domain,
+            'harmonic_partner': self.harmonic_partner,
             'pindex': self.pindex,
             'k_array': self.k_array
         }
@@ -188,8 +284,8 @@ class PowerSpace(Space):
         # call instructor so that classes are properly setup
         super(PowerSpace, new_ps).__init__()
         # set all values
-        new_ps._harmonic_domain = repository.get('harmonic_domain', hdf5_group)
-        new_ps._log = hdf5_group['log'][()]
+        new_ps._harmonic_partner = repository.get('harmonic_partner', hdf5_group)
+        new_ps._logarithmic = hdf5_group['logarithmic'][()]
         exec('new_ps._nbin = ' + hdf5_group.attrs['nbin'])
         exec('new_ps._binbounds = ' + hdf5_group.attrs['binbounds'])