space.py 6.03 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
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
58
    """ 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`.

    """
59

60
    def __init__(self):
Theo Steininger's avatar
Theo Steininger committed
61

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

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

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

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

75
        raise NotImplementedError
76

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

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

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

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

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

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

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

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

108
    def get_distance_array(self, distribution_strategy):
Theo Steininger's avatar
Theo Steininger committed
109
110
111
112
113
114
115
116
117
118
119
        """ 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.

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

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

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

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

135
    def get_fft_smoothing_kernel_function(self, sigma):
Theo Steininger's avatar
Theo Steininger committed
136
137
138
139
140
141
142
143
        """ 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.

144
145
        Parameters
        ----------
Theo Steininger's avatar
Theo Steininger committed
146
147
148
149
150
151
152
153
        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.

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

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

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

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

Theo Steininger's avatar
Theo Steininger committed
170
    def hermitian_decomposition(self, x, axes,
171
                                preserve_gaussian_variance=False):
Theo Steininger's avatar
Theo Steininger committed
172
173
174
175
176
177
178
        """ 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.

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

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

189
190
        Returns
        -------
Theo Steininger's avatar
Theo Steininger committed
191
192
193
194
        (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.

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

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

202
203
        raise NotImplementedError

204
    def __repr__(self):
205
        return str(type(self)) + "\n"