space.py 7.69 KB
Newer Older
1
2
# NIFTY (Numerical Information Field Theory) has been developed at the
# Max-Planck-Institute for Astrophysics.
Marco Selig's avatar
Marco Selig committed
3
##
4
# Copyright (C) 2013 Max-Planck-Society
Marco Selig's avatar
Marco Selig committed
5
##
6
7
# Author: Marco Selig
# Project homepage: <http://www.mpa-garching.mpg.de/ift/nifty/>
Marco Selig's avatar
Marco Selig committed
8
##
9
10
11
12
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
Marco Selig's avatar
Marco Selig committed
13
##
14
15
16
17
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
# See the GNU General Public License for more details.
Marco Selig's avatar
Marco Selig committed
18
##
19
20
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
Marco Selig's avatar
Marco Selig committed
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

"""
    ..                  __   ____   __
    ..                /__/ /   _/ /  /_
    ..      __ ___    __  /  /_  /   _/  __   __
    ..    /   _   | /  / /   _/ /  /   /  / /  /
    ..   /  / /  / /  / /  /   /  /_  /  /_/  /
    ..  /__/ /__/ /__/ /__/    \___/  \___   /  core
    ..                               /______/

    .. The NIFTY project homepage is http://www.mpa-garching.mpg.de/ift/nifty/

    NIFTY [#]_, "Numerical Information Field Theory", is a versatile
    library designed to enable the development of signal inference algorithms
    that operate regardless of the underlying spatial grid and its resolution.
    Its object-oriented framework is written in Python, although it accesses
    libraries written in Cython, C++, and C for efficiency.

    NIFTY offers a toolkit that abstracts discretized representations of
    continuous spaces, fields in these spaces, and operators acting on fields
    into classes. Thereby, the correct normalization of operations on fields is
    taken care of automatically without concerning the user. This allows for an
    abstract formulation and programming of inference algorithms, including
    those derived within information field theory. Thus, NIFTY permits its user
Marco Selig's avatar
Marco Selig committed
45
    to rapidly prototype algorithms in 1D and then apply the developed code in
Marco Selig's avatar
Marco Selig committed
46
47
48
49
50
    higher-dimensional settings of real world problems. The set of spaces on
    which NIFTY operates comprises point sets, n-dimensional regular grids,
    spherical spaces, their harmonic counterparts, and product spaces
    constructed as combinations of those.

51
52
53
54
55
56
57
    References
    ----------
    .. [#] Selig et al., "NIFTY -- Numerical Information Field Theory --
        a versatile Python library for signal inference",
        `A&A, vol. 554, id. A26 <http://dx.doi.org/10.1051/0004-6361/201321236>`_,
        2013; `arXiv:1301.4499 <http://www.arxiv.org/abs/1301.4499>`_

Marco Selig's avatar
Marco Selig committed
58
59
60
61
62
63
    Class & Feature Overview
    ------------------------
    The NIFTY library features three main classes: **spaces** that represent
    certain grids, **fields** that are defined on spaces, and **operators**
    that apply to fields.

64
65
    .. Overview of all (core) classes:
    ..
Marco Selig's avatar
Marco Selig committed
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
    .. - switch
    .. - notification
    .. - _about
    .. - random
    .. - space
    ..     - point_space
    ..     - rg_space
    ..     - lm_space
    ..     - gl_space
    ..     - hp_space
    ..     - nested_space
    .. - field
    .. - operator
    ..     - diagonal_operator
    ..         - power_operator
    ..     - projection_operator
    ..     - vecvec_operator
    ..     - response_operator
    .. - probing
    ..     - trace_probing
    ..     - diagonal_probing

88
89
    Overview of the main classes and functions:

Marco Selig's avatar
Marco Selig committed
90
91
    .. automodule:: nifty

92
93
94
95
96
97
98
99
100
101
102
103
104
105
    - :py:class:`space`
        - :py:class:`point_space`
        - :py:class:`rg_space`
        - :py:class:`lm_space`
        - :py:class:`gl_space`
        - :py:class:`hp_space`
        - :py:class:`nested_space`
    - :py:class:`field`
    - :py:class:`operator`
        - :py:class:`diagonal_operator`
            - :py:class:`power_operator`
        - :py:class:`projection_operator`
        - :py:class:`vecvec_operator`
        - :py:class:`response_operator`
Marco Selig's avatar
Marco Selig committed
106

107
        .. currentmodule:: nifty.nifty_tools
Marco Selig's avatar
Marco Selig committed
108

109
110
        - :py:class:`invertible_operator`
        - :py:class:`propagator_operator`
Marco Selig's avatar
Marco Selig committed
111

112
        .. currentmodule:: nifty.nifty_explicit
Marco Selig's avatar
Marco Selig committed
113

114
        - :py:class:`explicit_operator`
Marco Selig's avatar
Marco Selig committed
115

116
    .. automodule:: nifty
Marco Selig's avatar
Marco Selig committed
117

118
119
120
    - :py:class:`probing`
        - :py:class:`trace_probing`
        - :py:class:`diagonal_probing`
Marco Selig's avatar
Marco Selig committed
121

122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
        .. currentmodule:: nifty.nifty_explicit

        - :py:class:`explicit_probing`

    .. currentmodule:: nifty.nifty_tools

    - :py:class:`conjugate_gradient`
    - :py:class:`steepest_descent`

    .. currentmodule:: nifty.nifty_explicit

    - :py:func:`explicify`

    .. currentmodule:: nifty.nifty_power

    - :py:func:`weight_power`,
      :py:func:`smooth_power`,
      :py:func:`infer_power`,
      :py:func:`interpolate_power`
Marco Selig's avatar
Marco Selig committed
141
142
143

"""
from __future__ import division
144
145
146

import abc

Marco Selig's avatar
Marco Selig committed
147
148
import numpy as np

149
from nifty.domain_object import DomainObject
Theo Steininger's avatar
Theo Steininger committed
150

151

152
class Space(DomainObject):
Marco Selig's avatar
Marco Selig committed
153
    """
Theo Steininger's avatar
Theo Steininger committed
154
155
156
157
158
159
160
        ..                            __             __
        ..                          /__/           /  /_
        ..      ______    ______    __   __ ___   /   _/
        ..    /   _   | /   _   | /  / /   _   | /  /
        ..   /  /_/  / /  /_/  / /  / /  / /  / /  /_
        ..  /   ____/  \______/ /__/ /__/ /__/  \___/  space class
        .. /__/
Marco Selig's avatar
Marco Selig committed
161

Theo Steininger's avatar
Theo Steininger committed
162
        NIFTY subclass for unstructured spaces.
Marco Selig's avatar
Marco Selig committed
163

Theo Steininger's avatar
Theo Steininger committed
164
165
        Unstructured spaces are lists of values without any geometrical
        information.
Marco Selig's avatar
Marco Selig committed
166
167
168

        Parameters
        ----------
Theo Steininger's avatar
Theo Steininger committed
169
170
        num : int
            Number of points.
171
        dtype : numpy.dtype, *optional*
Theo Steininger's avatar
Theo Steininger committed
172
            Data type of the field values (default: None).
Marco Selig's avatar
Marco Selig committed
173

Theo Steininger's avatar
Theo Steininger committed
174
        Attributes
Marco Selig's avatar
Marco Selig committed
175
        ----------
Theo Steininger's avatar
Theo Steininger committed
176
177
        para : numpy.ndarray
            Array containing the number of points.
178
        dtype : numpy.dtype
Theo Steininger's avatar
Theo Steininger committed
179
180
181
182
183
184
            Data type of the field values.
        discrete : bool
            Parameter captioning the fact that a :py:class:`point_space` is
            always discrete.
        vol : numpy.ndarray
            Pixel volume of the :py:class:`point_space`, which is always 1.
Marco Selig's avatar
Marco Selig committed
185
    """
186

187
    def __init__(self, dtype=np.dtype('float')):
Theo Steininger's avatar
Theo Steininger committed
188
189
        """
            Sets the attributes for a point_space class instance.
Marco Selig's avatar
Marco Selig committed
190

Theo Steininger's avatar
Theo Steininger committed
191
192
193
194
            Parameters
            ----------
            num : int
                Number of points.
195
            dtype : numpy.dtype, *optional*
Theo Steininger's avatar
Theo Steininger committed
196
                Data type of the field values (default: numpy.float64).
Marco Selig's avatar
Marco Selig committed
197

Theo Steininger's avatar
Theo Steininger committed
198
199
200
201
            Returns
            -------
            None.
        """
202

203
        # parse dtype
204
205
206
        casted_dtype = np.result_type(dtype, np.float64)
        if casted_dtype != dtype:
            self.Logger.warning("Input dtype reset to: %s" % str(casted_dtype))
207

208
209
        super(Space, self).__init__(dtype=casted_dtype)
        self._ignore_for_hash += ['_global_id']
210

211
212
213
    @abc.abstractproperty
    def harmonic(self):
        raise NotImplementedError
214

215
    @abc.abstractproperty
216
    def total_volume(self):
217
218
        raise NotImplementedError(
            "There is no generic volume for the Space base class.")
219

220
221
222
    @abc.abstractmethod
    def copy(self):
        return self.__class__(dtype=self.dtype)
223

224
    def get_distance_array(self, distribution_strategy):
225
        raise NotImplementedError(
226
227
            "There is no generic distance structure for Space base class.")

228
    def get_fft_smoothing_kernel_function(self, sigma):
229
230
        raise NotImplementedError(
            "There is no generic co-smoothing kernel for Space base class.")
231

232
233
    def hermitian_decomposition(self, x, axes=None,
                                preserve_gaussian_variance=False):
234
235
        raise NotImplementedError

236
    def __repr__(self):
Theo Steininger's avatar
Theo Steininger committed
237
238
        string = ""
        string += str(type(self)) + "\n"
239
        string += "dtype: " + str(self.dtype) + "\n"
Theo Steininger's avatar
Theo Steininger committed
240
        return string