space.py 6.18 KB
Newer Older
1
2
3
4
5
# NIFTy
# Copyright (C) 2017  Theo Steininger
#
# Author: Theo Steininger
#
6
7
8
9
# 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.
10
#
11
12
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
13
14
15
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
16
# You should have received a copy of the GNU General Public License
17
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
Marco Selig's avatar
Marco Selig committed
18

19
20
import abc

21
from nifty.domain_object import DomainObject
Theo Steininger's avatar
Theo Steininger committed
22

23

24
class Space(DomainObject):
25
    def __init__(self):
Theo Steininger's avatar
Theo Steininger committed
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
        """ The abstract base class for all NIFTy spaces.

        An instance of a space contains information about the manifolds
        geometry and enhances the functionality of DomainObject by methods that
        are needed for powerspectrum analysis and smoothing.

        Parameters
        ----------
        None

        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.
        total_volume : np.float
            The total volume of the space.
        shape : tuple of np.ints
            The shape of the space's data array.

        Raises
        ------
        TypeError
            Raised if instantiated directly.

        Notes
        -----
        `Space` is an abstract base class. In order to allow for instantiation
        the methods `get_distance_array`, `total_volume` and `copy` must be
        implemented as well as the abstract methods inherited from
        `DomainObject`.
Marco Selig's avatar
Marco Selig committed
58

59
        """
60

Martin Reinecke's avatar
Martin Reinecke committed
61
        super(Space, self).__init__()
62

63
64
    @abc.abstractproperty
    def harmonic(self):
Theo Steininger's avatar
Theo Steininger committed
65
66
        """ Returns True if this space is a harmonic space.

67
68
        Raises
        ------
Theo Steininger's avatar
Theo Steininger committed
69
70
71
        NotImplementedError
            If called for this abstract class.

72
        """
Theo Steininger's avatar
Theo Steininger committed
73

74
        raise NotImplementedError
75

76
    @abc.abstractproperty
77
    def total_volume(self):
Theo Steininger's avatar
Theo Steininger committed
78
79
        """ Returns the total volume of the space.

80
81
        Returns
        -------
Theo Steininger's avatar
Theo Steininger committed
82
83
84
        float
            A real number representing the sum of all pixel volumes.

85
86
        Raises
        ------
Theo Steininger's avatar
Theo Steininger committed
87
88
89
        NotImplementedError
            If called for this abstract class.

90
        """
91
92
        raise NotImplementedError(
            "There is no generic volume for the Space base class.")
93

94
95
    @abc.abstractmethod
    def copy(self):
Theo Steininger's avatar
Theo Steininger committed
96
97
        """ Returns a copy of this Space instance.

98
99
        Returns
        -------
Theo Steininger's avatar
Theo Steininger committed
100
101
102
        Space
            A copy of this instance.

103
        """
Theo Steininger's avatar
Theo Steininger committed
104

Martin Reinecke's avatar
Martin Reinecke committed
105
        return self.__class__()
106

107
    def get_distance_array(self, distribution_strategy):
Theo Steininger's avatar
Theo Steininger committed
108
109
110
111
112
113
114
115
116
117
118
        """ The distances of the pixel to zero.

        This returns an array that gives for each pixel its distance to the
        center of the manifolds grid.

        Parameters
        ----------
        distribution_strategy : str
            The distribution_strategy which shall be used the returned
            distributed_data_object.

119
120
        Returns
        -------
Theo Steininger's avatar
Theo Steininger committed
121
122
123
        distributed_data_object
            A d2o containing the distances

124
125
        Raises
        ------
Theo Steininger's avatar
Theo Steininger committed
126
127
128
        NotImplementedError
            If called for this abstract class.

129
        """
Theo Steininger's avatar
Theo Steininger committed
130

131
        raise NotImplementedError(
132
133
            "There is no generic distance structure for Space base class.")

134
    def get_fft_smoothing_kernel_function(self, sigma):
Theo Steininger's avatar
Theo Steininger committed
135
136
137
138
139
140
141
142
        """ This method returns a smoothing kernel function.

        This method, which is only implemented for harmonic spaces, helps
        smoothing fields that live in a position space that has this space as
        its harmonic space. The returned function multiplies field values of a
        field with a zero centered Gaussian which corresponds to a convolution
        with a Gaussian kernel and sigma standard deviation in position space.

143
144
        Parameters
        ----------
Theo Steininger's avatar
Theo Steininger committed
145
146
147
148
149
150
151
152
        sigma : float
            A real number representing a physical scale on which the smoothing
            takes place. The smoothing is defined with respect to the real
            physical field and points that are closer together than one sigma
            are blurred together. Mathematically sigma is the standard
            deviation of a convolution with a normalized, zero-centered
            Gaussian that takes place in position space.

153
154
        Returns
        -------
Theo Steininger's avatar
Theo Steininger committed
155
156
157
158
        function (array-like -> array-like)
            A smoothing operation that multiplies values with a Gaussian
            kernel.

159
160
        Raises
        ------
Theo Steininger's avatar
Theo Steininger committed
161
162
163
        NotImplementedError :
            If called for this abstract class.

164
        """
Theo Steininger's avatar
Theo Steininger committed
165

166
167
        raise NotImplementedError(
            "There is no generic co-smoothing kernel for Space base class.")
168

Theo Steininger's avatar
Theo Steininger committed
169
    def hermitian_decomposition(self, x, axes,
170
                                preserve_gaussian_variance=False):
Theo Steininger's avatar
Theo Steininger committed
171
172
173
174
175
176
177
        """ Decomposes x into its hermitian and anti-hermitian constituents.

        This method decomposes a field's array x into its hermitian and
        antihermitian part, which corresponds to  real and imaginary part
        in a corresponding harmonic partner space. This is an internal function
        that is mainly used for power-synthesizing and -analyzing Fields.

178
179
        Parameters
        ----------
Theo Steininger's avatar
Theo Steininger committed
180
181
182
183
184
        x : distributed_data_object
            The field's val object.
        axes : tuple of ints
            Specifies the axes of x which correspond to this space.

185
186
        preserve_gaussian_variance : bool *optional*
            FIXME: figure out what this does
Theo Steininger's avatar
Theo Steininger committed
187

188
189
        Returns
        -------
Theo Steininger's avatar
Theo Steininger committed
190
191
192
193
        (distributed_data_object, distributed_data_object)
            A tuple of two distributed_data_objects, the first being the
            hermitian and the second the anti-hermitian part of x.

194
195
        Raises
        ------
Theo Steininger's avatar
Theo Steininger committed
196
197
198
        NotImplementedError
            If called for this abstract class.

199
        """
Theo Steininger's avatar
Theo Steininger committed
200

201
202
        raise NotImplementedError

203
    def __repr__(self):
Theo Steininger's avatar
Theo Steininger committed
204
205
206
        string = ""
        string += str(type(self)) + "\n"
        return string