From 1a7908555fd4d18f11f8328efaf3451c967c650e Mon Sep 17 00:00:00 2001
From: Martin Reinecke <martin@mpa-garching.mpg.de>
Date: Fri, 16 Feb 2018 20:44:25 +0100
Subject: [PATCH] doc tweaks
---
docs/generate.sh | 4 +-
docs/source/concepts/domains.rst | 34 +++-----------
docs/source/index.rst | 2 +-
nifty4/domains/domain.py | 19 +++-----
nifty4/domains/gl_space.py | 8 ++--
nifty4/domains/hp_space.py | 4 +-
nifty4/domains/lm_space.py | 14 +++---
nifty4/domains/power_space.py | 27 ++++++-----
nifty4/domains/structured_domain.py | 2 +-
nifty4/operators/endomorphic_operator.py | 8 ++--
nifty4/operators/linear_operator.py | 57 ++++++++++--------------
11 files changed, 75 insertions(+), 104 deletions(-)
diff --git a/docs/generate.sh b/docs/generate.sh
index 3d9a5a2cd..7ffc2cb90 100755
--- a/docs/generate.sh
+++ b/docs/generate.sh
@@ -1,4 +1,4 @@
rm -rf docs/build docs/source/mod
-#sphinx-apidoc -l -e -d 2 -o docs/source/mod nifty4
-python docs/better_apidoc.py -l -e -d 3 -t docs/generation-templates -o docs/source/mod nifty4
+sphinx-apidoc -l -e -d 2 -o docs/source/mod nifty4
+#python docs/better_apidoc.py -l -e -d 3 -t docs/generation-templates -o docs/source/mod nifty4
sphinx-build -b html docs/source/ docs/build/
diff --git a/docs/source/concepts/domains.rst b/docs/source/concepts/domains.rst
index c12a6d96c..5e2e85cde 100644
--- a/docs/source/concepts/domains.rst
+++ b/docs/source/concepts/domains.rst
@@ -4,17 +4,14 @@ NIFTy's domain classes
.. currentmodule:: nifty4
-**Abstract base class**
+Abstract base class
+-------------------
:class:`Domain` is the abstract ancestor for all of NIFTy's domains.
-.. toctree::
- :maxdepth: 1
- Domain <../mod/nifty4.domains.domain>
-
-
-**Unstructured domains**
+Unstructured domains
+--------------------
Domains can be either *structured* (i.e. there is geometrical information
associated with them, like position in space and volume factors),
@@ -23,24 +20,15 @@ or *unstructured* (meaning that the data points have no associated manifold).
Unstructured domains can be described by instances of NIFTy's
:class:`UnstructuredDomain` class.
-.. toctree::
- :maxdepth: 1
-
- UnstructuredDomain <../mod/nifty4.domains.unstructured_domain>
-
-**Structured domains**
+Structured domains
+------------------
In contrast to unstructured domains, these domains have an assigned geometry.
NIFTy requires these domains to provide the volume elements of their grid cells.
The additional methods are described in the abstract class
:class:`StructuredDomain`.
-.. toctree::
- :maxdepth: 1
-
- StructuredDomain <../mod/nifty4.domains.structured_domain>
-
NIFTy comes with several concrete subclasses of :class:`StructuredDomain`.
:class:`RGSpace` represents a regular Cartesian grid with an arbitrary
@@ -52,13 +40,3 @@ This domain can be constructed to represent either position or harmonic space.
contains spherical harmonic coefficients.
:class:`PowerSpace` is used to describe one-dimensional power spectra.
-
-.. toctree::
- :maxdepth: 1
-
- RGSpace <../mod/nifty4.domains.rg_space>
- HPSpace <../mod/nifty4.domains.hp_space>
- GLSpace <../mod/nifty4.domains.gl_space>
- LMSpace <../mod/nifty4.domains.lm_space>
-
- PowerSpace <../mod/nifty4.domains.power_space>
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 2ad7ce616..df154d750 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -23,8 +23,8 @@ Contents
ift
Gallery <http://wwwmpa.mpa-garching.mpg.de/ift/nifty/gallery/>
- start
installation
+ start
code
Indices and tables
diff --git a/nifty4/domains/domain.py b/nifty4/domains/domain.py
index c8f22c8fd..0a8633772 100644
--- a/nifty4/domains/domain.py
+++ b/nifty4/domains/domain.py
@@ -52,12 +52,12 @@ class Domain(with_metaclass(
Parameters
----------
- x: Domain
+ x : Domain
The domain `self` is compared to.
Returns
-------
- bool: True iff `self` and x describe the same domain.
+ bool : True iff `self` and x describe the same domain.
"""
if self is x: # shortcut for simple case
return True
@@ -74,22 +74,17 @@ class Domain(with_metaclass(
@abc.abstractproperty
def shape(self):
- """The shape of the array-like object required to store information
- living on the domain.
+ """tuple of ints: number of pixels along each axis
- Returns
- -------
- tuple of ints: shape of the required array-like object
+ The shape of the array-like object required to store information
+ living on the domain.
"""
raise NotImplementedError
@abc.abstractproperty
def size(self):
- """Number of data elements associated with this domain.
- Equivalent to the products over all entries in the domain's shape.
+ """int: total number of pixels.
- Returns
- -------
- int: number of data elements
+ Equivalent to the products over all entries in the domain's shape.
"""
raise NotImplementedError
diff --git a/nifty4/domains/gl_space.py b/nifty4/domains/gl_space.py
index cea771c10..927b9186f 100644
--- a/nifty4/domains/gl_space.py
+++ b/nifty4/domains/gl_space.py
@@ -83,14 +83,12 @@ class GLSpace(StructuredDomain):
@property
def nlat(self):
- """ Number of latitudinal bins (or rings) that are used for this
- pixelization.
- """
+ """int : number of rings in this domain"""
return self._nlat
@property
def nlon(self):
- """Number of longitudinal bins that are used for this pixelization."""
+ """int : pixels per ring in this domain"""
return self._nlon
def get_default_codomain(self):
@@ -101,7 +99,7 @@ class GLSpace(StructuredDomain):
Returns
-------
LMSpace
- The parter domain
+ The partner domain
"""
from .. import LMSpace
return LMSpace(lmax=self._nlat-1, mmax=self._nlon//2)
diff --git a/nifty4/domains/hp_space.py b/nifty4/domains/hp_space.py
index 0dbee2adf..ca56f07a1 100644
--- a/nifty4/domains/hp_space.py
+++ b/nifty4/domains/hp_space.py
@@ -61,7 +61,7 @@ class HPSpace(StructuredDomain):
@property
def nside(self):
- """Returns the nside of the corresponding HEALPix pixelization."""
+ """int : HEALPix Nside parameter of this domain"""
return self._nside
def get_default_codomain(self):
@@ -71,7 +71,7 @@ class HPSpace(StructuredDomain):
Returns
-------
LMSpace
- The parter domain
+ The partner domain
Notes
-----
diff --git a/nifty4/domains/lm_space.py b/nifty4/domains/lm_space.py
index 466d0f058..b90d8ad9d 100644
--- a/nifty4/domains/lm_space.py
+++ b/nifty4/domains/lm_space.py
@@ -110,15 +110,19 @@ class LMSpace(StructuredDomain):
@property
def lmax(self):
- """ Returns the maximum :math:`l` value of any spherical harmonic
- coefficient :math:`a_{lm}` that is represented in this Space.
+ """int : maximum allowed :math:`l`
+
+ The maximum :math:`l` value of any spherical harmonic
+ coefficient :math:`a_{lm}` that is represented in this domain.
"""
return self._lmax
@property
def mmax(self):
- """ Returns the maximum :math:`m` value of any spherical harmonic
- coefficient :math:`a_{lm}` that is represented in this Space.
+ """int : maximum allowed :math:`m`
+
+ The maximum :math:`m` value of any spherical harmonic
+ coefficient :math:`a_{lm}` that is represented in this domain.
"""
return self._mmax
@@ -130,7 +134,7 @@ class LMSpace(StructuredDomain):
Returns
-------
GLSpace
- The parter domain
+ The partner domain
"""
from .. import GLSpace
return GLSpace(self.lmax+1, self.mmax*2+1)
diff --git a/nifty4/domains/power_space.py b/nifty4/domains/power_space.py
index 3350175b4..eae9d6ce0 100644
--- a/nifty4/domains/power_space.py
+++ b/nifty4/domains/power_space.py
@@ -30,19 +30,19 @@ class PowerSpace(StructuredDomain):
Parameters
----------
harmonic_partner : StructuredDomain
- The harmonic dmain of which this is the power space.
- binbounds : None, or tuple of float
+ The harmonic domain of which this is the power space.
+ binbounds : None, or tuple of float (default: None)
if None:
There will be as many bins as there are distinct k-vector lengths
in the harmonic partner space.
- The "binbounds" property of the PowerSpace will also be None.
+ The `binbounds` property of the PowerSpace will also be None.
else:
the bin bounds requested for this PowerSpace. The array
must be sorted and strictly ascending. The first entry is the right
boundary of the first bin, and the last entry is the left boundary
- of the last bin, i.e. thee will be len(binbounds)+1 bins in total,
- with the first and last bins reaching to -+infinity, respectively.
- (default : None)
+ of the last bin, i.e. thee will be `len(binbounds)+1` bins in
+ total, with the first and last bins reaching to -+infinity,
+ respectively.
"""
_powerIndexCache = {}
@@ -191,6 +191,7 @@ class PowerSpace(StructuredDomain):
@property
def harmonic(self):
+ """bool : Always False for this class."""
return False
@property
@@ -209,12 +210,15 @@ class PowerSpace(StructuredDomain):
@property
def harmonic_partner(self):
- """Returns the Space of which this is the power space."""
+ """StructuredDomain : the harmonic domain associated with `self`."""
return self._harmonic_partner
@property
def binbounds(self):
- """Returns the boundaries between the power spectrum bins as a tuple.
+ """None or tuple of float : inner bin boundaries
+
+ The boundaries between bins, starting with the right boundary of the
+ first bin, up to the left boundary of the last bin.
`None` is used to indicate natural binning.
"""
@@ -222,12 +226,13 @@ class PowerSpace(StructuredDomain):
@property
def pindex(self):
- """Returns a data object having the shape of the harmonic partner
- space containing the indices of the power bin a pixel belongs to.
+ """data_object : bin indices
+
+ Bin index for every pixel in the harmonic partner.
"""
return self._pindex
@property
def k_lengths(self):
- """Returns a sorted array of all k-modes."""
+ """numpy.ndarray(float) : sorted array of all k-vector lengths."""
return self._k_lengths
diff --git a/nifty4/domains/structured_domain.py b/nifty4/domains/structured_domain.py
index 131297c1d..a81ddf94d 100644
--- a/nifty4/domains/structured_domain.py
+++ b/nifty4/domains/structured_domain.py
@@ -67,7 +67,7 @@ class StructuredDomain(Domain):
@abc.abstractproperty
def harmonic(self):
- """ Returns True iff this domain is a harmonic domain."""
+ """bool : True iff this domain is a harmonic domain."""
raise NotImplementedError
def get_k_length_array(self):
diff --git a/nifty4/operators/endomorphic_operator.py b/nifty4/operators/endomorphic_operator.py
index 6c8cd6d18..2dccd75e9 100644
--- a/nifty4/operators/endomorphic_operator.py
+++ b/nifty4/operators/endomorphic_operator.py
@@ -29,8 +29,8 @@ class EndomorphicOperator(LinearOperator):
@property
def target(self):
- """
- DomainTuple
- Returns `self.domain`, because this is also the target domain
- for endomorphic operators."""
+ """DomainTuple : returns :attr:`domain`
+
+ Returns `self.domain`, because this is also the target domain
+ for endomorphic operators."""
return self.domain
diff --git a/nifty4/operators/linear_operator.py b/nifty4/operators/linear_operator.py
index 0993eb1ce..9a00fe383 100644
--- a/nifty4/operators/linear_operator.py
+++ b/nifty4/operators/linear_operator.py
@@ -56,41 +56,33 @@ class LinearOperator(with_metaclass(
@abc.abstractproperty
def domain(self):
- """
- DomainTuple
- The domain on which the Operator's input Field lives.
- Every Operator which inherits from the abstract LinearOperator
- base class must have this attribute.
- """
+ """DomainTuple : the operator's input domain
+
+ The domain on which the Operator's input Field lives."""
raise NotImplementedError
@abc.abstractproperty
def target(self):
- """
- DomainTuple
- The domain on which the Operator's output Field lives.
- Every Operator which inherits from the abstract LinearOperator
- base class must have this attribute.
- """
+ """DomainTuple : the operator's output domain
+
+ The domain on which the Operator's output Field lives."""
raise NotImplementedError
@property
def inverse(self):
- """
- LinearOperator
- Returns a LinearOperator object which behaves as if it were
- the inverse of this operator.
- """
+ """LinearOperator : the inverse of `self`
+
+ Returns a LinearOperator object which behaves as if it were
+ the inverse of this operator."""
from .inverse_operator import InverseOperator
return InverseOperator(self)
@property
def adjoint(self):
- """
- LinearOperator
- Returns a LinearOperator object which behaves as if it were
- the adjoint of this operator.
- """
+ """LinearOperator : the adjoint of `self`
+
+ Returns a LinearOperator object which behaves as if it were
+ the adjoint of this operator."""
from .adjoint_operator import AdjointOperator
return AdjointOperator(self)
@@ -137,20 +129,17 @@ class LinearOperator(with_metaclass(
@abc.abstractproperty
def capability(self):
- """ Specifies the application modes supported by this operator
+ """int : the supported operation modes
- Returns
- -------
- int
- This is any subset of LinearOperator.{TIMES, ADJOINT_TIMES,
- INVERSE_TIMES, ADJOINT_INVERSE_TIMES, INVERSE_ADJOINT_TIMES},
- joined together by the "|" operator.
+ Returns the suppoerted subset of :attr:`TIMES`, :attr:`ADJOINT_TIMES`,
+ :attr:`INVERSE_TIMES`, and :attr:`ADJOINT_INVERSE_TIMES`,
+ joined together by the "|" operator.
"""
raise NotImplementedError
@abc.abstractmethod
def apply(self, x, mode):
- """ Applies the Operator to a given Field, in a specified mode.
+ """ Applies the Operator to a given `x`, in a specified `mode`.
Parameters
----------
@@ -175,7 +164,7 @@ class LinearOperator(with_metaclass(
raise NotImplementedError
def __call__(self, x):
- """Same as times()"""
+ """Same as :meth:`times`"""
return self.apply(x, self.TIMES)
def times(self, x):
@@ -244,7 +233,7 @@ class LinearOperator(with_metaclass(
return self.apply(x, self.ADJOINT_INVERSE_TIMES)
def inverse_adjoint_times(self, x):
- """Same as adjoint_inverse_times()"""
+ """Same as :meth:`adjoint_inverse_times`"""
return self.apply(x, self.ADJOINT_INVERSE_TIMES)
def _check_mode(self, mode):
@@ -262,7 +251,9 @@ class LinearOperator(with_metaclass(
raise ValueError("The operator's and field's domains don't match.")
def draw_sample(self):
- """ Generates a sample from a Gaussian distribution with zero mean and
+ """Generate a zero-mean sample
+
+ Generates a sample from a Gaussian distribution with zero mean and
covariance given by the operator.
Returns
--
GitLab