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

doc tweaks

parent eb3a20e3
Pipeline #25043 passed with stages
in 6 minutes and 40 seconds
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/
......@@ -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>
......@@ -23,8 +23,8 @@ Contents
ift
Gallery <http://wwwmpa.mpa-garching.mpg.de/ift/nifty/gallery/>
start
installation
start
code
Indices and tables
......
......@@ -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
......@@ -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)
......
......@@ -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
-----
......
......@@ -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)
......
......@@ -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
......@@ -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):
......
......@@ -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
......@@ -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
......
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