Commit 1a790855 authored by Martin Reinecke's avatar Martin Reinecke
Browse files

doc tweaks

parent eb3a20e3
Pipeline #25043 passed with stages
in 6 minutes and 40 seconds
rm -rf docs/build docs/source/mod rm -rf docs/build docs/source/mod
#sphinx-apidoc -l -e -d 2 -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 #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/ sphinx-build -b html docs/source/ docs/build/
...@@ -4,17 +4,14 @@ NIFTy's domain classes ...@@ -4,17 +4,14 @@ NIFTy's domain classes
.. currentmodule:: nifty4 .. currentmodule:: nifty4
**Abstract base class** Abstract base class
-------------------
:class:`Domain` is the abstract ancestor for all of NIFTy's domains. :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 Domains can be either *structured* (i.e. there is geometrical information
associated with them, like position in space and volume factors), 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). ...@@ -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 Unstructured domains can be described by instances of NIFTy's
:class:`UnstructuredDomain` class. :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. In contrast to unstructured domains, these domains have an assigned geometry.
NIFTy requires these domains to provide the volume elements of their grid cells. NIFTy requires these domains to provide the volume elements of their grid cells.
The additional methods are described in the abstract class The additional methods are described in the abstract class
:class:`StructuredDomain`. :class:`StructuredDomain`.
.. toctree::
:maxdepth: 1
StructuredDomain <../mod/nifty4.domains.structured_domain>
NIFTy comes with several concrete subclasses of :class:`StructuredDomain`. NIFTy comes with several concrete subclasses of :class:`StructuredDomain`.
:class:`RGSpace` represents a regular Cartesian grid with an arbitrary :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. ...@@ -52,13 +40,3 @@ This domain can be constructed to represent either position or harmonic space.
contains spherical harmonic coefficients. contains spherical harmonic coefficients.
:class:`PowerSpace` is used to describe one-dimensional power spectra. :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>
...@@ -23,8 +23,8 @@ Contents ...@@ -23,8 +23,8 @@ Contents
ift ift
Gallery <http://wwwmpa.mpa-garching.mpg.de/ift/nifty/gallery/> Gallery <http://wwwmpa.mpa-garching.mpg.de/ift/nifty/gallery/>
start
installation installation
start
code code
Indices and tables Indices and tables
......
...@@ -52,12 +52,12 @@ class Domain(with_metaclass( ...@@ -52,12 +52,12 @@ class Domain(with_metaclass(
Parameters Parameters
---------- ----------
x: Domain x : Domain
The domain `self` is compared to. The domain `self` is compared to.
Returns 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 if self is x: # shortcut for simple case
return True return True
...@@ -74,22 +74,17 @@ class Domain(with_metaclass( ...@@ -74,22 +74,17 @@ class Domain(with_metaclass(
@abc.abstractproperty @abc.abstractproperty
def shape(self): def shape(self):
"""The shape of the array-like object required to store information """tuple of ints: number of pixels along each axis
living on the domain.
Returns The shape of the array-like object required to store information
------- living on the domain.
tuple of ints: shape of the required array-like object
""" """
raise NotImplementedError raise NotImplementedError
@abc.abstractproperty @abc.abstractproperty
def size(self): def size(self):
"""Number of data elements associated with this domain. """int: total number of pixels.
Equivalent to the products over all entries in the domain's shape.
Returns Equivalent to the products over all entries in the domain's shape.
-------
int: number of data elements
""" """
raise NotImplementedError raise NotImplementedError
...@@ -83,14 +83,12 @@ class GLSpace(StructuredDomain): ...@@ -83,14 +83,12 @@ class GLSpace(StructuredDomain):
@property @property
def nlat(self): def nlat(self):
""" Number of latitudinal bins (or rings) that are used for this """int : number of rings in this domain"""
pixelization.
"""
return self._nlat return self._nlat
@property @property
def nlon(self): def nlon(self):
"""Number of longitudinal bins that are used for this pixelization.""" """int : pixels per ring in this domain"""
return self._nlon return self._nlon
def get_default_codomain(self): def get_default_codomain(self):
...@@ -101,7 +99,7 @@ class GLSpace(StructuredDomain): ...@@ -101,7 +99,7 @@ class GLSpace(StructuredDomain):
Returns Returns
------- -------
LMSpace LMSpace
The parter domain The partner domain
""" """
from .. import LMSpace from .. import LMSpace
return LMSpace(lmax=self._nlat-1, mmax=self._nlon//2) return LMSpace(lmax=self._nlat-1, mmax=self._nlon//2)
......
...@@ -61,7 +61,7 @@ class HPSpace(StructuredDomain): ...@@ -61,7 +61,7 @@ class HPSpace(StructuredDomain):
@property @property
def nside(self): def nside(self):
"""Returns the nside of the corresponding HEALPix pixelization.""" """int : HEALPix Nside parameter of this domain"""
return self._nside return self._nside
def get_default_codomain(self): def get_default_codomain(self):
...@@ -71,7 +71,7 @@ class HPSpace(StructuredDomain): ...@@ -71,7 +71,7 @@ class HPSpace(StructuredDomain):
Returns Returns
------- -------
LMSpace LMSpace
The parter domain The partner domain
Notes Notes
----- -----
......
...@@ -110,15 +110,19 @@ class LMSpace(StructuredDomain): ...@@ -110,15 +110,19 @@ class LMSpace(StructuredDomain):
@property @property
def lmax(self): def lmax(self):
""" Returns the maximum :math:`l` value of any spherical harmonic """int : maximum allowed :math:`l`
coefficient :math:`a_{lm}` that is represented in this Space.
The maximum :math:`l` value of any spherical harmonic
coefficient :math:`a_{lm}` that is represented in this domain.
""" """
return self._lmax return self._lmax
@property @property
def mmax(self): def mmax(self):
""" Returns the maximum :math:`m` value of any spherical harmonic """int : maximum allowed :math:`m`
coefficient :math:`a_{lm}` that is represented in this Space.
The maximum :math:`m` value of any spherical harmonic
coefficient :math:`a_{lm}` that is represented in this domain.
""" """
return self._mmax return self._mmax
...@@ -130,7 +134,7 @@ class LMSpace(StructuredDomain): ...@@ -130,7 +134,7 @@ class LMSpace(StructuredDomain):
Returns Returns
------- -------
GLSpace GLSpace
The parter domain The partner domain
""" """
from .. import GLSpace from .. import GLSpace
return GLSpace(self.lmax+1, self.mmax*2+1) return GLSpace(self.lmax+1, self.mmax*2+1)
......
...@@ -30,19 +30,19 @@ class PowerSpace(StructuredDomain): ...@@ -30,19 +30,19 @@ class PowerSpace(StructuredDomain):
Parameters Parameters
---------- ----------
harmonic_partner : StructuredDomain harmonic_partner : StructuredDomain
The harmonic dmain of which this is the power space. The harmonic domain of which this is the power space.
binbounds : None, or tuple of float binbounds : None, or tuple of float (default: None)
if None: if None:
There will be as many bins as there are distinct k-vector lengths There will be as many bins as there are distinct k-vector lengths
in the harmonic partner space. 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: else:
the bin bounds requested for this PowerSpace. The array the bin bounds requested for this PowerSpace. The array
must be sorted and strictly ascending. The first entry is the right 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 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, of the last bin, i.e. thee will be `len(binbounds)+1` bins in
with the first and last bins reaching to -+infinity, respectively. total, with the first and last bins reaching to -+infinity,
(default : None) respectively.
""" """
_powerIndexCache = {} _powerIndexCache = {}
...@@ -191,6 +191,7 @@ class PowerSpace(StructuredDomain): ...@@ -191,6 +191,7 @@ class PowerSpace(StructuredDomain):
@property @property
def harmonic(self): def harmonic(self):
"""bool : Always False for this class."""
return False return False
@property @property
...@@ -209,12 +210,15 @@ class PowerSpace(StructuredDomain): ...@@ -209,12 +210,15 @@ class PowerSpace(StructuredDomain):
@property @property
def harmonic_partner(self): 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 return self._harmonic_partner
@property @property
def binbounds(self): 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. `None` is used to indicate natural binning.
""" """
...@@ -222,12 +226,13 @@ class PowerSpace(StructuredDomain): ...@@ -222,12 +226,13 @@ class PowerSpace(StructuredDomain):
@property @property
def pindex(self): def pindex(self):
"""Returns a data object having the shape of the harmonic partner """data_object : bin indices
space containing the indices of the power bin a pixel belongs to.
Bin index for every pixel in the harmonic partner.
""" """
return self._pindex return self._pindex
@property @property
def k_lengths(self): 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 return self._k_lengths
...@@ -67,7 +67,7 @@ class StructuredDomain(Domain): ...@@ -67,7 +67,7 @@ class StructuredDomain(Domain):
@abc.abstractproperty @abc.abstractproperty
def harmonic(self): def harmonic(self):
""" Returns True iff this domain is a harmonic domain.""" """bool : True iff this domain is a harmonic domain."""
raise NotImplementedError raise NotImplementedError
def get_k_length_array(self): def get_k_length_array(self):
......
...@@ -29,8 +29,8 @@ class EndomorphicOperator(LinearOperator): ...@@ -29,8 +29,8 @@ class EndomorphicOperator(LinearOperator):
@property @property
def target(self): def target(self):
""" """DomainTuple : returns :attr:`domain`
DomainTuple
Returns `self.domain`, because this is also the target domain Returns `self.domain`, because this is also the target domain
for endomorphic operators.""" for endomorphic operators."""
return self.domain return self.domain
...@@ -56,41 +56,33 @@ class LinearOperator(with_metaclass( ...@@ -56,41 +56,33 @@ class LinearOperator(with_metaclass(
@abc.abstractproperty @abc.abstractproperty
def domain(self): def domain(self):
""" """DomainTuple : the operator's input domain
DomainTuple
The domain on which the Operator's input Field lives. The domain on which the Operator's input Field lives."""
Every Operator which inherits from the abstract LinearOperator
base class must have this attribute.
"""
raise NotImplementedError raise NotImplementedError
@abc.abstractproperty @abc.abstractproperty
def target(self): def target(self):
""" """DomainTuple : the operator's output domain
DomainTuple
The domain on which the Operator's output Field lives. The domain on which the Operator's output Field lives."""
Every Operator which inherits from the abstract LinearOperator
base class must have this attribute.
"""
raise NotImplementedError raise NotImplementedError
@property @property
def inverse(self): def inverse(self):
""" """LinearOperator : the inverse of `self`
LinearOperator
Returns a LinearOperator object which behaves as if it were Returns a LinearOperator object which behaves as if it were
the inverse of this operator. the inverse of this operator."""
"""
from .inverse_operator import InverseOperator from .inverse_operator import InverseOperator
return InverseOperator(self) return InverseOperator(self)
@property @property
def adjoint(self): def adjoint(self):
""" """LinearOperator : the adjoint of `self`
LinearOperator
Returns a LinearOperator object which behaves as if it were Returns a LinearOperator object which behaves as if it were
the adjoint of this operator. the adjoint of this operator."""
"""
from .adjoint_operator import AdjointOperator from .adjoint_operator import AdjointOperator
return AdjointOperator(self) return AdjointOperator(self)
...@@ -137,20 +129,17 @@ class LinearOperator(with_metaclass( ...@@ -137,20 +129,17 @@ class LinearOperator(with_metaclass(
@abc.abstractproperty @abc.abstractproperty
def capability(self): def capability(self):
""" Specifies the application modes supported by this operator """int : the supported operation modes
Returns Returns the suppoerted subset of :attr:`TIMES`, :attr:`ADJOINT_TIMES`,
------- :attr:`INVERSE_TIMES`, and :attr:`ADJOINT_INVERSE_TIMES`,
int joined together by the "|" operator.
This is any subset of LinearOperator.{TIMES, ADJOINT_TIMES,
INVERSE_TIMES, ADJOINT_INVERSE_TIMES, INVERSE_ADJOINT_TIMES},
joined together by the "|" operator.
""" """
raise NotImplementedError raise NotImplementedError
@abc.abstractmethod @abc.abstractmethod
def apply(self, x, mode): 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 Parameters
---------- ----------
...@@ -175,7 +164,7 @@ class LinearOperator(with_metaclass( ...@@ -175,7 +164,7 @@ class LinearOperator(with_metaclass(
raise NotImplementedError raise NotImplementedError
def __call__(self, x): def __call__(self, x):
"""Same as times()""" """Same as :meth:`times`"""
return self.apply(x, self.TIMES) return self.apply(x, self.TIMES)
def times(self, x): def times(self, x):
...@@ -244,7 +233,7 @@ class LinearOperator(with_metaclass( ...@@ -244,7 +233,7 @@ class LinearOperator(with_metaclass(
return self.apply(x, self.ADJOINT_INVERSE_TIMES) return self.apply(x, self.ADJOINT_INVERSE_TIMES)
def inverse_adjoint_times(self, x): 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) return self.apply(x, self.ADJOINT_INVERSE_TIMES)
def _check_mode(self, mode): def _check_mode(self, mode):
...@@ -262,7 +251,9 @@ class LinearOperator(with_metaclass( ...@@ -262,7 +251,9 @@ class LinearOperator(with_metaclass(
raise ValueError("The operator's and field's domains don't match.") raise ValueError("The operator's and field's domains don't match.")
def draw_sample(self): 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. covariance given by the operator.
Returns Returns
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment