Merge branch 'mr_docs' into 'NIFTy_5'

more docs

See merge request ift/nifty-dev!179

nifty5/linearization.py

@@ -187,6 +187,18 @@ class Linearization(object):
         return self.__mul__(other)
 
     def outer(self, other):
+        """Computes the outer product of this Linearization with a Field or
+        another Linearization
+
+        Parameters
+        ----------
+        other : Field or MultiField or Linearization
+
+        Returns
+        -------
+        Linearization
+            the outer product of self and other
+        """
         from .operators.outer_product_operator import OuterProduct
         if isinstance(other, Linearization):
             return self.new(
@@ -200,6 +212,18 @@ class Linearization(object):
                             OuterProduct(self._jac(self._val), other.domain))
 
     def vdot(self, other):
+        """Computes the inner product of this Linearization with a Field or
+        another Linearization
+
+        Parameters
+        ----------
+        other : Field or MultiField or Linearization
+
+        Returns
+        -------
+        Linearization
+            the inner product of self and other
+        """
         from .operators.simple_linear_operators import VdotOperator
         if isinstance(other, (Field, MultiField)):
             return self.new(
@@ -211,6 +235,19 @@ class Linearization(object):
             VdotOperator(other._val)(self._jac))
 
     def sum(self, spaces=None):
+        """Computes the (partial) sum over self
+
+        Parameters
+        ----------
+        spaces : None, int or list of int
+            - if None, sum over the entire domain
+            - else sum over the specified subspaces
+
+        Returns
+        -------
+        Linearization
+            the (partial) sum
+        """
         from .operators.contraction_operator import ContractionOperator
         if spaces is None:
             return self.new(
@@ -222,6 +259,19 @@ class Linearization(object):
                 ContractionOperator(self._jac.target, spaces)(self._jac))
 
     def integrate(self, spaces=None):
+        """Computes the (partial) integral over self
+
+        Parameters
+        ----------
+        spaces : None, int or list of int
+            - if None, integrate over the entire domain
+            - else integrate over the specified subspaces
+
+        Returns
+        -------
+        Linearization
+            the (partial) integral
+        """
         from .operators.contraction_operator import ContractionOperator
         if spaces is None:
             return self.new(
@@ -309,18 +359,72 @@ class Linearization(object):
 
     @staticmethod
     def make_var(field, want_metric=False):
+        """Converts a Field to a Linearization, with a unity Jacobian
+
+        Parameters
+        ----------
+        field : Field or Multifield
+            the field to be converted
+        want_metric : bool
+            If True, the metric will be computed for other Linearizations
+            derived from this one. Default: False.
+
+        Returns
+        -------
+        Linearization
+            the requested Linearization
+        """
         from .operators.scaling_operator import ScalingOperator
         return Linearization(field, ScalingOperator(1., field.domain),
                              want_metric=want_metric)
 
     @staticmethod
     def make_const(field, want_metric=False):
+        """Converts a Field to a Linearization, with a zero Jacobian
+
+        Parameters
+        ----------
+        field : Field or Multifield
+            the field to be converted
+        want_metric : bool
+            If True, the metric will be computed for other Linearizations
+            derived from this one. Default: False.
+
+        Returns
+        -------
+        Linearization
+            the requested Linearization
+
+        Notes
+        -----
+        The Jacobian is square and contains only zeroes.
+        """
         from .operators.simple_linear_operators import NullOperator
         return Linearization(field, NullOperator(field.domain, field.domain),
                              want_metric=want_metric)
 
     @staticmethod
     def make_const_empty_input(field, want_metric=False):
+        """Converts a Field to a Linearization, with a zero Jacobian
+
+        Parameters
+        ----------
+        field : Field or Multifield
+            the field to be converted
+        want_metric : bool
+            If True, the metric will be computed for other Linearizations
+            derived from this one. Default: False.
+
+        Returns
+        -------
+        Linearization
+            the requested Linearization
+
+        Notes
+        -----
+        The Jacobian has an empty input domain, i.e. its matrix representation
+        has 0 columns.
+        """
         from .operators.simple_linear_operators import NullOperator
         from .multi_domain import MultiDomain
         return Linearization(
@@ -329,6 +433,29 @@ class Linearization(object):
 
     @staticmethod
     def make_partial_var(field, constants, want_metric=False):
+        """Converts a MultiField to a Linearization, with a Jacobian that is
+        unity for some MultiField components and a zero matrix for others.
+
+        Parameters
+        ----------
+        field : Multifield
+            the field to be converted
+        constants : list of string
+            the MultiField components for which the Jacobian should be
+            a zero matrix.
+        want_metric : bool
+            If True, the metric will be computed for other Linearizations
+            derived from this one. Default: False.
+
+        Returns
+        -------
+        Linearization
+            the requested Linearization
+
+        Notes
+        -----
+        The Jacobian is square.
+        """
         from .operators.scaling_operator import ScalingOperator
         from .operators.block_diagonal_operator import BlockDiagonalOperator
         if len(constants) == 0:

nifty5/sugar.py

@@ -52,7 +52,8 @@ def PS_field(pspace, func):
 
     Returns
     -------
-    Field : a field defined on (pspace,) containing the computed function values
+    Field
+        A field defined on (pspace,) containing the computed function values
     """
     if not isinstance(pspace, PowerSpace):
         raise TypeError
@@ -209,6 +210,23 @@ def create_power_operator(domain, power_spectrum, space=None):
 
 
 def create_harmonic_smoothing_operator(domain, space, sigma):
+    """Creates an operator which smoothes a subspace of a harmonic domain.
+
+    Parameters
+    ----------
+    domain: DomainTuple
+        The total domain and target of the operator
+    space : int
+        the index of the subspace on which the operator acts.
+        This must be a harmonic space
+    sigma : float
+        The sigma of the Gaussian smoothing kernel
+
+    Returns
+    -------
+    DiagonalOperator
+        The requested smoothing operator
+    """
     kfunc = domain[space].get_fft_smoothing_kernel_function(sigma)
     return DiagonalOperator(kfunc(domain[space].get_k_length_array()), domain,
                             space)
@@ -226,7 +244,8 @@ def full(domain, val):
 
     Returns
     -------
-    Field / MultiField : the newly created uniform field
+    Field or MultiField
+        The newly created uniform field
     """
     if isinstance(domain, (dict, MultiDomain)):
         return MultiField.full(domain, val)
@@ -249,7 +268,8 @@ def from_random(random_type, domain, dtype=np.float64, **kwargs):
 
     Returns
     -------
-    Field / MultiField : the newly created random field
+    Field or MultiField
+        The newly created random field
     """
     if isinstance(domain, (dict, MultiDomain)):
         return MultiField.from_random(random_type, domain, dtype, **kwargs)
@@ -274,7 +294,8 @@ def from_global_data(domain, arr, sum_up=False):
 
     Returns
     -------
-    Field / MultiField : the newly created random field
+    Field or MultiField
+        The newly created random field
     """
     if isinstance(domain, (dict, MultiDomain)):
         return MultiField.from_global_data(domain, arr, sum_up)
@@ -294,7 +315,8 @@ def from_local_data(domain, arr):
 
     Returns
     -------
-    Field / MultiField : the newly created field
+    Field or MultiField
+        The newly created field
     """
     if isinstance(domain, (dict, MultiDomain)):
         return MultiField.from_local_data(domain, arr)
@@ -311,7 +333,8 @@ def makeDomain(domain):
 
     Returns
     -------
-    DomainTuple / MultiDomain : the newly created domain object
+    DomainTuple or MultiDomain
+        The newly created domain object
     """
     if isinstance(domain, (MultiDomain, dict)):
         return MultiDomain.make(domain)
@@ -319,6 +342,21 @@ def makeDomain(domain):
 
 
 def makeOp(input):
+    """Converts a Field or MultiField to a diagonal operator.
+
+    Parameters
+    ----------
+    input : None, Field or MultiField
+        - if None, None is returned.
+        - if Field, a DiagonalOperator with the coefficients given by this
+            Field is returned.
+        - if MultiField, a BlockDiagonalOperator with entries given by this
+            MultiField is returned.
+
+    Notes
+    -----
+    No volume factors are applied.
+    """
     if input is None:
         return None
     if isinstance(input, Field):
@@ -330,6 +368,14 @@ def makeOp(input):
 
 
 def domain_union(domains):
+    """Computes the union of multiple DomainTuples/MultiDomains.
+
+    Parameters
+    ----------
+    domains : list of DomainTuple or MultiDomain
+        - if DomainTuple, all entries must be equal
+        - if MultiDomain, there must not be any conflicting components
+    """
     if isinstance(domains[0], DomainTuple):
         if any(dom != domains[0] for dom in domains[1:]):
             raise ValueError("domain mismatch")