diff --git a/docs/generate.sh b/docs/generate.sh index 3d9a5a2cd055378f77edf495bd7502501676e3bc..7ffc2cb909144274417b359d138c249225f66ce4 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 c12a6d96c34d173a6c1b0ace403a0d4a5e0db3e9..5e2e85cde8f543a165a681cdc1354cbb922b0538 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 2ad7ce616c7e80f27497b40e3669a9b2611e0b92..df154d75040983b8b77813b6bd9a5c212b89f438 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -23,8 +23,8 @@ Contents ift Gallery - start installation + start code Indices and tables diff --git a/nifty4/domains/domain.py b/nifty4/domains/domain.py index c8f22c8fd31ecab247caaf63eb0e6eae2f13ae93..0a8633772357b61e8d3b87dd721fe3a7cfcdc957 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 cea771c10f20cac98ffa464b433fac8cecbae788..927b9186fa20111c3f34f370ff1f8b4a2adbaa01 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 0dbee2adff2239f0ec1fce28f47fe42b9fb56e85..ca56f07a1c3602d7087346c6fd690c36fe24394e 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 466d0f058e6ed862e886dd9ebd6728abeab3851f..b90d8ad9d338d10f52c7ba46576745dfc0aecad2 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 3350175b432b01ea66690204b16801c1a156f6e6..eae9d6ce08d5042e3912f187ce8dedde2dd323bf 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 131297c1d1b04d74dee9d1a42cca319cb10d2a18..a81ddf94d8ad3b2cc51444e34d51c506c580096b 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 6c8cd6d1875d6b5576a454260b6c993704e8c9e1..2dccd75e9e0cd7d26c62f9f9202c274f607b4540 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 0993eb1cec9d3ff347a520af6e5dd5579bbebf10..9a00fe3835ca3128408f303bb36d84e928553204 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