Skip to content

GitLab

Commit b7122aa0 authored by Martin Reinecke's avatar Martin Reinecke
Browse files

documentation revamp

parent 2797621a
Pipeline #19534 passed with stage
in 4 minutes and 7 seconds
Hide whitespace changes
Inline Side-by-side
Showing with 155 additions and 386 deletions
nifty/__init__.py
View file @ b7122aa0
......@@ -6,6 +6,8 @@ from .field import Field
from .domain_tuple import DomainTuple
from .domain_object import DomainObject
from .random import Random
from .basic_arithmetics import *
......
nifty/domain_object.py
View file @ b7122aa0
......@@ -28,15 +28,6 @@ class DomainObject(with_metaclass(
This holds all the information and functionality a field needs to know
about its domain and how the data of the field are stored.
Attributes
----------
dim : int
Number of pixel-dimensions of the underlying data object.
shape : tuple
Shape of the array that stores the degrees of freedom for any field
on this domain.
"""
def __init__(self):
......@@ -54,7 +45,7 @@ class DomainObject(with_metaclass(
return result_hash
def __eq__(self, x):
""" Checks if two domain_objects are equal.
"""Checks if two domain_objects are equal.
Parameters
----------
......@@ -63,9 +54,7 @@ class DomainObject(with_metaclass(
Returns
-------
bool
True if `self` and x describe the same manifold.
bool: True iff `self` and x describe the same manifold.
"""
if self is x: # shortcut for simple case
return True
......@@ -81,22 +70,13 @@ class DomainObject(with_metaclass(
@abc.abstractproperty
def shape(self):
""" The domain-object's shape contribution to the underlying array.
"""The domain-object's shape contribution to the underlying array.
Returns
-------
tuple of ints
The shape of the underlying array-like object.
Raises
------
NotImplementedError
If called for this abstract class.
tuple of ints: shape of the underlying array-like object
"""
raise NotImplementedError(
"There is no generic shape for DomainObject.")
raise NotImplementedError
@abc.abstractproperty
def dim(self):
......@@ -104,55 +84,29 @@ class DomainObject(with_metaclass(
Returns
-------
int
An Integer representing the number of pixels the discretized
manifold has.
Raises
------
NotImplementedError
If called for this abstract class.
int: number of pixels
"""
raise NotImplementedError(
"There is no generic dim for DomainObject.")
raise NotImplementedError
@abc.abstractmethod
def scalar_dvol(self):
""" Returns the volume factors of this domain as a floating
"""Returns the volume factors of this domain as a floating
point scalar, if the volume factors are all identical, otherwise
returns None.
Returns
-------
float or None
Volume factor
Raises
------
NotImplementedError
If called for this abstract class.
float or None: Volume factor
"""
raise NotImplementedError(
"There is no generic scalar_dvol method for DomainObject.")
raise NotImplementedError
def dvol(self):
""" Returns the volume factors of this domain, either as a floating
"""Returns the volume factors of this domain, either as a floating
point scalar (if the volume factors are all identical) or as a
floating point array with a shape of `self.shape`.
Returns
-------
float or numpy.ndarray(dtype=float)
Volume factors
Raises
------
NotImplementedError
If called for this abstract class.
float or numpy.ndarray(dtype=float): Volume factors
"""
return self.scalar_dvol()
nifty/spaces/gl_space.py
View file @ b7122aa0
......@@ -22,58 +22,35 @@ from .space import Space
class GLSpace(Space):
"""
.. __
.. / /
.. ____ __ / /
.. / _ / / /
.. / /_/ / / /_
.. \___ / \___/ space class
.. /______/
NIFTY subclass for Gauss-Legendre pixelizations [#]_ of the two-sphere.
Parameters
----------
nlat : int
Number of latitudinal bins (or rings) that are used for this
pixelization.
nlon : int, *optional*
Number of longitudinal bins that are used for this pixelization.
Attributes
----------
dim : np.int
Total number of dimensionality, i.e. the number of pixels.
harmonic : bool
Specifies whether the space is a signal or harmonic space.
nlat : int
Number of latitudinal bins (or rings) that are used for this
pixelization.
nlon : int
Number of longitudinal bins that are used for this pixelization.
shape : tuple of np.ints
The shape of the space's data array.
Raises
------
ValueError
If input `nlat` or `nlon` is invalid.
See Also
--------
hp_space : A class for the HEALPix discretization of the sphere [#]_.
lm_space : A class for spherical harmonic components.
References
----------
.. [#] M. Reinecke and D. Sverre Seljebotn, 2013, "Libsharp - spherical
harmonic transforms revisited";
`arXiv:1303.4945 <http://www.arxiv.org/abs/1303.4945>`_
.. [#] K.M. Gorski et al., 2005, "HEALPix: A Framework for
High-Resolution Discretization and Fast Analysis of Data
Distributed on the Sphere", *ApJ* 622..759G.
"""NIFTY subclass for Gauss-Legendre pixelizations [#]_ of the two-sphere.
Parameters
----------
nlat : int
Number of latitudinal bins (or rings) that are used for this
pixelization.
nlon : int, *optional*
Number of longitudinal bins that are used for this pixelization.
Default value is 2*nlat + 1.
Raises
------
ValueError
If input `nlat` or `nlon` is invalid.
See Also
--------
hp_space : A class for the HEALPix discretization of the sphere [#]_.
lm_space : A class for spherical harmonic components.
References
----------
.. [#] M. Reinecke and D. Sverre Seljebotn, 2013, "Libsharp - spherical
harmonic transforms revisited";
`arXiv:1303.4945 <http://www.arxiv.org/abs/1303.4945>`_
.. [#] K.M. Gorski et al., 2005, "HEALPix: A Framework for
High-Resolution Discretization and Fast Analysis of Data
Distributed on the Sphere", *ApJ* 622..759G.
"""
# ---Overwritten properties and methods---
......@@ -82,8 +59,15 @@ class GLSpace(Space):
super(GLSpace, self).__init__()
self._needed_for_hash += ["_nlat", "_nlon"]
self._nlat = self._parse_nlat(nlat)
self._nlon = self._parse_nlon(nlon)
self._nlat = int(nlat)
if self._nlat < 1:
raise ValueError("nlat must be a positive number.")
if nlon is None:
self._nlon = 2*self._nlat - 1
else:
self._nlon = int(nlon)
if self._nlon < 1:
raise ValueError("nlon must be a positive number.")
self._dvol = None
# ---Mandatory properties and methods---
......@@ -114,8 +98,6 @@ class GLSpace(Space):
self._dvol = GL_weights(self.nlat, self.nlon)
return np.repeat(self._dvol, self.nlon)
# ---Added properties and methods---
@property
def nlat(self):
""" Number of latitudinal bins (or rings) that are used for this
......@@ -125,25 +107,9 @@ class GLSpace(Space):
@property
def nlon(self):
""" Number of longitudinal bins that are used for this pixelization.
"""
"""Number of longitudinal bins that are used for this pixelization."""
return self._nlon
def _parse_nlat(self, nlat):
nlat = int(nlat)
if nlat < 1:
raise ValueError("nlat must be a positive number.")
return nlat
def _parse_nlon(self, nlon):
if nlon is None:
nlon = 2 * self.nlat - 1
else:
nlon = int(nlon)
if nlon < 1:
raise ValueError("nlon must be a positive number.")
return nlon
def get_default_codomain(self):
from .. import LMSpace
return LMSpace(lmax=self.nlat-1, mmax=(self.nlon-1)//2)
......
nifty/spaces/hp_space.py
View file @ b7122aa0
......@@ -22,65 +22,41 @@ from .space import Space
class HPSpace(Space):
"""NIFTY subclass for HEALPix discretizations of the two-sphere [#]_.
Parameters
----------
nside : int
The corresponding HEALPix Nside parameter. Must be a positive integer
and typically is a power of 2.
Raises
------
ValueError
If given `nside` < 1.
See Also
--------
GLSpace : A class for the Gauss-Legendre discretization of the
sphere [#]_.
LMSpace : A class for spherical harmonic components.
References
----------
.. [#] K.M. Gorski et al., 2005, "HEALPix: A Framework for
High-Resolution Discretization and Fast Analysis of Data
Distributed on the Sphere", *ApJ* 622..759G.
.. [#] M. Reinecke and D. Sverre Seljebotn, 2013, "Libsharp - spherical
harmonic transforms revisited";
`arXiv:1303.4945 <http://www.arxiv.org/abs/1303.4945>`_
"""
.. __
.. / /
.. / /___ ______
.. / _ | / _ |
.. / / / / / /_/ /
.. /__/ /__/ / ____/ space class
.. /__/
NIFTY subclass for HEALPix discretizations of the two-sphere [#]_.
Parameters
----------
nside : int
The corresponding HEALPix pixelization. The total number of pixels
is 12*nside**2.
Attributes
----------
dim : np.int
Total number of dimensionality, i.e. the number of pixels.
harmonic : bool
Specifies whether the space is a signal or harmonic space.
nside : int
The corresponding HEALPix pixelization. The total number of pixels
is 12*nside**2.
shape : tuple of np.ints
The shape of the space's data array.
Raises
------
ValueError
If given `nside` < 1.
See Also
--------
gl_space : A class for the Gauss-Legendre discretization of the
sphere [#]_.
lm_space : A class for spherical harmonic components.
References
----------
.. [#] K.M. Gorski et al., 2005, "HEALPix: A Framework for
High-Resolution Discretization and Fast Analysis of Data
Distributed on the Sphere", *ApJ* 622..759G.
.. [#] M. Reinecke and D. Sverre Seljebotn, 2013, "Libsharp - spherical
harmonic transforms revisited";
`arXiv:1303.4945 <http://www.arxiv.org/abs/1303.4945>`_
"""
# ---Overwritten properties and methods---
def __init__(self, nside):
super(HPSpace, self).__init__()
self._needed_for_hash += ["_nside"]
self._nside = self._parse_nside(nside)
# ---Mandatory properties and methods---
self._nside = int(nside)
if self._nside < 1:
raise ValueError("nside must be >=1.")
def __repr__(self):
return ("HPSpace(nside=%r)" % self.nside)
......@@ -100,21 +76,11 @@ class HPSpace(Space):
def scalar_dvol(self):
return np.pi / (3*self._nside*self._nside)
# ---Added properties and methods---
@property
def nside(self):
""" Returns the nside of the corresponding HEALPix pixelization.
The total number of pixels is 12*nside**2
"""
"""Returns the nside of the corresponding HEALPix pixelization."""
return self._nside
def _parse_nside(self, nside):
nside = int(nside)
if nside < 1:
raise ValueError("nside must be >=1.")
return nside
def get_default_codomain(self):
from .. import LMSpace
return LMSpace(lmax=2*self.nside)
......
nifty/spaces/lm_space.py
View file @ b7122aa0
......@@ -22,61 +22,38 @@ from .space import Space
class LMSpace(Space):
"""
.. __
.. / /
.. / / __ ____ ___
.. / / / _ _ |
.. / /_ / / / / / /
.. \___/ /__/ /__/ /__/ space class
NIFTY subclass for spherical harmonics components, for representations
of fields on the two-sphere.
Parameters
----------
lmax : int
The maximal :math:`l` value of any spherical harmonics
:math:`Y_{lm}` that is represented in this Space.
Attributes
----------
lmax : int
The maximal :math:`l` value of any spherical harmonics
:math:`Y_{lm}` that is represented in this Space.
mmax : int
The maximal :math:`m` value of any spherical harmonic
:math:`Y_{lm}` that is represented in this Space.
dim : np.int
Total number of dimensionality, i.e. the number of pixels.
harmonic : bool
Specifies whether the space is a signal or harmonic space.
shape : tuple of np.ints
The shape of the space's data array.
See Also
--------
hp_space : A class for the HEALPix discretization of the sphere [#]_.
gl_space : A class for the Gauss-Legendre discretization of the
sphere [#]_.
Raises
------
ValueError
If given lmax is negative.
Notes
-----
This implementation implicitly sets the mmax parameter to lmax.
References
----------
.. [#] K.M. Gorski et al., 2005, "HEALPix: A Framework for
High-Resolution Discretization and Fast Analysis of Data
Distributed on the Sphere", *ApJ* 622..759G.
.. [#] M. Reinecke and D. Sverre Seljebotn, 2013, "Libsharp - spherical
harmonic transforms revisited";
`arXiv:1303.4945 <http://www.arxiv.org/abs/1303.4945>`_
"""NIFTY subclass for spherical harmonics components, for representations
of fields on the two-sphere.
Parameters
----------
lmax : int
The maximum :math:`l` value of any spherical harmonics
:math:`Y_{lm}` that is represented in this Space.
See Also
--------
HPSpace : A class for the HEALPix discretization of the sphere [#]_.
GLSpace : A class for the Gauss-Legendre discretization of the
sphere [#]_.
Raises
------
ValueError
If given lmax is negative.
Notes
-----
This implementation implicitly sets the mmax parameter to lmax.
References
----------
.. [#] K.M. Gorski et al., 2005, "HEALPix: A Framework for
High-Resolution Discretization and Fast Analysis of Data
Distributed on the Sphere", *ApJ* 622..759G.
.. [#] M. Reinecke and D. Sverre Seljebotn, 2013, "Libsharp - spherical
harmonic transforms revisited";
`arXiv:1303.4945 <http://www.arxiv.org/abs/1303.4945>`_
"""
def __init__(self, lmax):
......@@ -140,25 +117,17 @@ class LMSpace(Space):
@property
def lmax(self):
""" Returns the maximal :math:`l` value of any spherical harmonics
""" Returns the maximum :math:`l` value of any spherical harmonic
:math:`Y_{lm}` that is represented in this Space.
"""
return self._lmax
@property
def mmax(self):
""" Returns the maximal :math:`m` value of any spherical harmonic
:math:`Y_{lm}` that is represented in this Space. As :math:`m` goes
from :math:`-l` to :math:`l` for every :math:`l` this just returns the
same as lmax.
See Also
--------
lmax : Returns the maximal :math:`l`-value of the spherical harmonics
being used.
""" Returns the maximum :math:`m` value of any spherical harmonic
:math:`Y_{lm}` that is represented in this Space.
Currently this is identical to lmax.
"""
return self._lmax
def _parse_lmax(self, lmax):
......
nifty/spaces/power_space.py
View file @ b7122aa0
......@@ -18,12 +18,11 @@
import numpy as np
from .space import Space
from functools import reduce
from .. import dobj
class PowerSpace(Space):
""" NIFTY class for spaces of power spectra.
"""NIFTY class for spaces of power spectra.
Parameters
----------
......@@ -43,28 +42,10 @@ class PowerSpace(Space):
with the first and last bins reaching to -+infinity, respectively.
(default : None)
Attributes
----------
pindex : data object
This holds the information which pixel of the harmonic partner gets
mapped to which power bin
k_lengths : numpy.ndarray
Sorted array of all k-modes.
dim : np.int
Total number of dimensionality, i.e. the number of pixels.
harmonic : bool
Always False for this space.
shape : tuple of np.ints
The shape of the space's data array.
binbounds : tuple or None
Boundaries between the power spectrum bins; None is used to indicate
natural binning
Notes
-----
A power space is the result of a projection of a harmonic space where
k-modes of equal length get mapped to one power index.
"""
_powerIndexCache = {}
......@@ -163,7 +144,7 @@ class PowerSpace(Space):
temp_rho = dobj.bincount(temp_pindex.ravel())
assert not np.any(temp_rho == 0), "empty bins detected"
temp_k_lengths = np.bincount(temp_pindex.ravel(),
weights=k_length_array.ravel()) \
weights=k_length_array.ravel()) \
/ temp_rho
temp_dvol = temp_rho*pdvol
self._powerIndexCache[key] = (binbounds,
......@@ -209,23 +190,24 @@ class PowerSpace(Space):
@property
def harmonic_partner(self):
""" Returns the Space of which this is the power space.
"""
"""Returns the Space of which this is the power space."""
return self._harmonic_partner
@property
def binbounds(self):
"""Returns the boundaries between the power spectrum bins as a tuple.
None is used to indicate natural binning.
"""
return self._binbounds
@property
def pindex(self):
""" A data object having the shape of the harmonic partner
"""Returns a data object having the shape of the harmonic partner
space containing the indices of the power bin a pixel belongs to.
"""
return self._pindex
@property
def k_lengths(self):
""" Sorted array of all k-modes.
"""
"""Returns a sorted array of all k-modes."""
return self._k_lengths
nifty/spaces/rg_space.py
View file @ b7122aa0
......@@ -16,18 +16,6 @@
# NIFTy is being developed at the Max-Planck-Institut fuer Astrophysik
# and financially supported by the Studienstiftung des deutschen Volkes.
"""
.. __ ____ __
.. /__/ / _/ / /_
.. __ ___ __ / /_ / _/ __ __
.. / _ | / / / _/ / / / / / /
.. / / / / / / / / / /_ / /_/ /
.. /__/ /__/ /__/ /__/ \___/ \___ / rg
.. /______/
NIFTY submodule for regular Cartesian grids.
"""
from __future__ import division
from builtins import range
from functools import reduce
......@@ -36,47 +24,24 @@ from .space import Space
class RGSpace(Space):
"""NIFTY subclass for spaces of regular Cartesian grids.
Parameters
----------
shape : {int, numpy.ndarray}
Number of grid points or numbers of gridpoints along each axis.
distances : {float, numpy.ndarray}, *optional*
Distance between two grid points along each axis
(default: None).
If distances==None:
if harmonic==True, all distances will be set to 1
if harmonic==False, the distance along each axis will be
set to the inverse of the number of points along that
axis.
harmonic : bool, *optional*
Whether the space represents a grid in position or harmonic space.
(default: False).
"""
.. _____ _______
.. / __/ / _ /
.. / / / /_/ /
.. /__/ \____ / space class
.. /______/
NIFTY subclass for spaces of regular Cartesian grids.
Parameters