field.py 22.3 KB
Newer Older
1
2
3
4
5
6
7
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.
#
# 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.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
Theo Steininger's avatar
Theo Steininger committed
13
#
Martin Reinecke's avatar
Martin Reinecke committed
14
# Copyright(C) 2013-2018 Max-Planck-Society
Theo Steininger's avatar
Theo Steininger committed
15
16
17
#
# NIFTy is being developed at the Max-Planck-Institut fuer Astrophysik
# and financially supported by the Studienstiftung des deutschen Volkes.
18

19
20
from __future__ import (absolute_import, division, print_function)
from builtins import *
csongor's avatar
csongor committed
21
import numpy as np
Martin Reinecke's avatar
Martin Reinecke committed
22
from . import utilities
Martin Reinecke's avatar
Martin Reinecke committed
23
from .domain_tuple import DomainTuple
Martin Reinecke's avatar
Martin Reinecke committed
24
from functools import reduce
25
from . import dobj
26

27

Martin Reinecke's avatar
Martin Reinecke committed
28
class Field(object):
Theo Steininger's avatar
Theo Steininger committed
29
30
    """ The discrete representation of a continuous field over multiple spaces.

Martin Reinecke's avatar
Martin Reinecke committed
31
    In NIFTy, Fields are used to store data arrays and carry all the needed
32
    metainformation (i.e. the domain) for operators to be able to work on them.
Theo Steininger's avatar
Theo Steininger committed
33

34
35
    Parameters
    ----------
Martin Reinecke's avatar
Martin Reinecke committed
36
    domain : None, DomainTuple, tuple of Domain, or Domain
Theo Steininger's avatar
Theo Steininger committed
37

38
    val : Field, data_object or scalar
39
        The values the array should contain after init. A scalar input will
Martin Reinecke's avatar
Martin Reinecke committed
40
41
        fill the whole array with this scalar. If a data_object is provided,
        its dimensions must match the domain's.
Theo Steininger's avatar
Theo Steininger committed
42

43
    dtype : type
Martin Reinecke's avatar
updates    
Martin Reinecke committed
44
        A numpy.type. Most common are float and complex.
Martin Reinecke's avatar
Martin Reinecke committed
45
46
47
48
49

    Notes
    -----
    If possible, do not invoke the constructor directly, but use one of the
    many convenience functions for Field conatruction!
50
    """
51

52
    def __init__(self, domain=None, val=None, dtype=None):
Martin Reinecke's avatar
Martin Reinecke committed
53
        self._domain = self._infer_domain(domain=domain, val=val)
54

Martin Reinecke's avatar
Martin Reinecke committed
55
        dtype = self._infer_dtype(dtype=dtype, val=val)
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
56
        if isinstance(val, Field):
Martin Reinecke's avatar
Martin Reinecke committed
57
            if self._domain != val._domain:
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
58
                raise ValueError("Domain mismatch")
59
60
            self._val = val._val

Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
61
        elif (np.isscalar(val)):
Martin Reinecke's avatar
Martin Reinecke committed
62
            self._val = dobj.full(self._domain.shape, dtype=dtype,
63
                                  fill_value=val)
64
        elif isinstance(val, dobj.data_object):
Martin Reinecke's avatar
Martin Reinecke committed
65
            if self._domain.shape == val.shape:
66
67
68
69
                if dtype == val.dtype:
                    self._val = val
                else:
                    self._val = dobj.from_object(val, dtype, True, True)
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
70
71
72
73
            else:
                raise ValueError("Shape mismatch")
        else:
            raise TypeError("unknown source type")
csongor's avatar
csongor committed
74

75
        dobj.lock(self._val)
Martin Reinecke's avatar
Martin Reinecke committed
76

77
78
79
80
81
82
83
    # prevent implicit conversion to bool
    def __nonzero__(self):
        raise TypeError("Field does not support implicit conversion to bool")

    def __bool__(self):
        raise TypeError("Field does not support implicit conversion to bool")

84
    @staticmethod
85
    def full(domain, val):
Martin Reinecke's avatar
Martin Reinecke committed
86
87
88
89
90
91
92
93
94
95
96
97
98
99
        """Creates a Field with a given domain, filled with a constant value.

        Parameters
        ----------
        domain : Domain, tuple of Domain, or DomainTuple
            domain of the new Field
        val : float/complex/int scalar
            fill value. Data type of the field is inferred from val.

        Returns
        -------
        Field
            the newly created field
        """
100
101
        if not np.isscalar(val):
            raise TypeError("val must be a scalar")
102
        return Field(DomainTuple.make(domain), val)
103

104
    @staticmethod
105
    def from_global_data(domain, arr, sum_up=False):
Martin Reinecke's avatar
Martin Reinecke committed
106
107
108
109
110
111
112
113
114
        """Returns a Field constructed from `domain` and `arr`.

        Parameters
        ----------
        domain : DomainTuple, tuple of Domain, or Domain
            the domain of the new Field
        arr : numpy.ndarray
            The data content to be used for the new Field.
            Its shape must match the shape of `domain`.
115
116
117
118
119
        sum_up : bool, optional
            If True, the contents of `arr` are summed up over all MPI tasks
            (if any), and the sum is used as data content.
            If False, the contens of `arr` are used directly, and must be
            identical on all MPI tasks.
Martin Reinecke's avatar
Martin Reinecke committed
120
        """
121
        return Field(domain, dobj.from_global_data(arr, sum_up))
122

Martin Reinecke's avatar
Martin Reinecke committed
123
124
125
126
127
    @staticmethod
    def from_local_data(domain, arr):
        domain = DomainTuple.make(domain)
        return Field(domain, dobj.from_local_data(domain.shape, arr))

128
    def to_global_data(self):
Martin Reinecke's avatar
Martin Reinecke committed
129
130
131
132
133
134
135
136
137
138
139
140
        """Returns an array containing the full data of the field.

        Returns
        -------
        numpy.ndarray : array containing all field entries.
            Its shape is identical to `self.shape`.

        Notes
        -----
        Do not write to the returned array! Depending on whether MPI is
        active or not, this may or may not change the field's data content.
        """
141
142
        return dobj.to_global_data(self._val)

Martin Reinecke's avatar
Martin Reinecke committed
143
144
    @property
    def local_data(self):
Martin Reinecke's avatar
Martin Reinecke committed
145
146
147
148
149
        """numpy.ndarray : locally residing field data

        Returns a handle to the part of the array data residing on the local
        task (or to the entore array if MPI is not active).
        """
Martin Reinecke's avatar
Martin Reinecke committed
150
151
        return dobj.local_data(self._val)

Martin Reinecke's avatar
Martin Reinecke committed
152
    def cast_domain(self, new_domain):
Martin Reinecke's avatar
Martin Reinecke committed
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
        """Returns a field with the same data, but a different domain

        Parameters
        ----------
        new_domain : Domain, tuple of Domain, or DomainTuple
            The domain for the returned field. Must be shape-compatible to
            `self`.

        Returns
        -------
        Field
            Field living on `new_domain`, but with the same data as `self`.

        Notes
        -----
        No copy is made. If needed, use an additional copy() invocation.
        """
Martin Reinecke's avatar
Martin Reinecke committed
170
171
        return Field(new_domain, self._val)

Martin Reinecke's avatar
Martin Reinecke committed
172
    @staticmethod
Martin Reinecke's avatar
tweaks    
Martin Reinecke committed
173
    def _infer_domain(domain, val=None):
174
        if domain is None:
175
            if isinstance(val, Field):
Martin Reinecke's avatar
Martin Reinecke committed
176
                return val._domain
Martin Reinecke's avatar
tweaks    
Martin Reinecke committed
177
            if np.isscalar(val):
178
                return DomainTuple.make(())  # empty domain tuple
Martin Reinecke's avatar
tweaks    
Martin Reinecke committed
179
            raise TypeError("could not infer domain from value")
Martin Reinecke's avatar
Martin Reinecke committed
180
        return DomainTuple.make(domain)
181

Martin Reinecke's avatar
Martin Reinecke committed
182
183
    @staticmethod
    def _infer_dtype(dtype, val):
Martin Reinecke's avatar
Martin Reinecke committed
184
185
186
187
188
        if dtype is not None:
            return dtype
        if val is None:
            raise ValueError("could not infer dtype")
        return np.result_type(val)
189

Martin Reinecke's avatar
Martin Reinecke committed
190
191
    @staticmethod
    def from_random(random_type, domain, dtype=np.float64, **kwargs):
192
193
194
195
        """ Draws a random field with the given parameters.

        Parameters
        ----------
Martin Reinecke's avatar
Martin Reinecke committed
196
197
        random_type : 'pm1', 'normal', or 'uniform'
            The random distribution to use.
Martin Reinecke's avatar
Martin Reinecke committed
198
        domain : DomainTuple
199
200
201
            The domain of the output random field
        dtype : type
            The datatype of the output random field
Theo Steininger's avatar
Theo Steininger committed
202

203
204
        Returns
        -------
Martin Reinecke's avatar
Martin Reinecke committed
205
        Field
Martin Reinecke's avatar
Martin Reinecke committed
206
            The newly created Field.
207
        """
Martin Reinecke's avatar
Martin Reinecke committed
208
        domain = DomainTuple.make(domain)
Martin Reinecke's avatar
Martin Reinecke committed
209
210
211
        return Field(domain=domain,
                     val=dobj.from_random(random_type, dtype=dtype,
                                          shape=domain.shape, **kwargs))
212

Theo Steininger's avatar
Theo Steininger committed
213
214
    @property
    def val(self):
Martin Reinecke's avatar
Martin Reinecke committed
215
216
217
218
219
220
        """dobj.data_object : the data object storing the field's entries

        Notes
        -----
        This property is intended for low-level, internal use only. Do not use
        from outside of NIFTy's core; there should be better alternatives.
221
        """
Martin Reinecke's avatar
Martin Reinecke committed
222
        return self._val
csongor's avatar
csongor committed
223

Martin Reinecke's avatar
Martin Reinecke committed
224
225
    @property
    def dtype(self):
Martin Reinecke's avatar
Martin Reinecke committed
226
        """type : the data type of the field's entries"""
Martin Reinecke's avatar
Martin Reinecke committed
227
228
        return self._val.dtype

Martin Reinecke's avatar
Martin Reinecke committed
229
230
    @property
    def domain(self):
Martin Reinecke's avatar
Martin Reinecke committed
231
        """DomainTuple : the field's domain"""
Martin Reinecke's avatar
Martin Reinecke committed
232
233
        return self._domain

234
235
    @property
    def shape(self):
Martin Reinecke's avatar
Martin Reinecke committed
236
        """tuple of int : the concatenated shapes of all sub-domains"""
Martin Reinecke's avatar
Martin Reinecke committed
237
        return self._domain.shape
csongor's avatar
csongor committed
238

239
    @property
Martin Reinecke's avatar
Martin Reinecke committed
240
    def size(self):
Martin Reinecke's avatar
Martin Reinecke committed
241
        """int : total number of pixels in the field"""
Martin Reinecke's avatar
Martin Reinecke committed
242
        return self._domain.size
csongor's avatar
csongor committed
243

Theo Steininger's avatar
Theo Steininger committed
244
245
    @property
    def real(self):
Martin Reinecke's avatar
Martin Reinecke committed
246
        """Field : The real part of the field"""
247
        if not np.issubdtype(self.dtype, np.complexfloating):
248
            return self
Martin Reinecke's avatar
Martin Reinecke committed
249
        return Field(self._domain, self.val.real)
Theo Steininger's avatar
Theo Steininger committed
250
251
252

    @property
    def imag(self):
Martin Reinecke's avatar
Martin Reinecke committed
253
        """Field : The imaginary part of the field"""
254
255
        if not np.issubdtype(self.dtype, np.complexfloating):
            raise ValueError(".imag called on a non-complex Field")
Martin Reinecke's avatar
Martin Reinecke committed
256
        return Field(self._domain, self.val.imag)
Theo Steininger's avatar
Theo Steininger committed
257

258
    def scalar_weight(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
259
260
261
262
263
264
265
266
267
268
269
270
271
272
        """Returns the uniform volume element for a sub-domain of `self`.

        Parameters
        ----------
        spaces : int, tuple of int or None
            indices of the sub-domains of the field's domain to be considered.
            If `None`, the entire domain is used.

        Returns
        -------
        float or None
            if the requested sub-domain has a uniform volume element, it is
            returned. Otherwise, `None` is returned.
        """
273
        if np.isscalar(spaces):
Martin Reinecke's avatar
Martin Reinecke committed
274
            return self._domain[spaces].scalar_dvol
275
276

        if spaces is None:
Martin Reinecke's avatar
Martin Reinecke committed
277
            spaces = range(len(self._domain))
Martin Reinecke's avatar
Martin Reinecke committed
278
        res = 1.
279
        for i in spaces:
Martin Reinecke's avatar
Martin Reinecke committed
280
            tmp = self._domain[i].scalar_dvol
281
282
283
284
285
            if tmp is None:
                return None
            res *= tmp
        return res

Martin Reinecke's avatar
Martin Reinecke committed
286
    def total_volume(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
287
288
289
290
291
292
293
294
295
296
297
298
299
        """Returns the total volume of a sub-domain of `self`.

        Parameters
        ----------
        spaces : int, tuple of int or None
            indices of the sub-domains of the field's domain to be considered.
            If `None`, the entire domain is used.

        Returns
        -------
        float
            the total volume of the requested sub-domain.
        """
Martin Reinecke's avatar
Martin Reinecke committed
300
        if np.isscalar(spaces):
Martin Reinecke's avatar
Martin Reinecke committed
301
            return self._domain[spaces].total_volume
Martin Reinecke's avatar
Martin Reinecke committed
302
303
304
305
306

        if spaces is None:
            spaces = range(len(self._domain))
        res = 1.
        for i in spaces:
Martin Reinecke's avatar
Martin Reinecke committed
307
            res *= self._domain[i].total_volume
Martin Reinecke's avatar
Martin Reinecke committed
308
309
        return res

310
    def weight(self, power=1, spaces=None):
Theo Steininger's avatar
Theo Steininger committed
311
        """ Weights the pixels of `self` with their invidual pixel-volume.
312
313
314
315

        Parameters
        ----------
        power : number
Theo Steininger's avatar
Theo Steininger committed
316
            The pixels get weighted with the volume-factor**power.
Theo Steininger's avatar
Theo Steininger committed
317

Martin Reinecke's avatar
Martin Reinecke committed
318
319
320
        spaces : None, int or tuple of int
            Determines on which sub-domain the operation takes place.
            If None, the entire domain is used.
Theo Steininger's avatar
Theo Steininger committed
321

322
323
        Returns
        -------
Martin Reinecke's avatar
Martin Reinecke committed
324
        Field
Theo Steininger's avatar
Theo Steininger committed
325
            The weighted field.
326
        """
327
        aout = self.local_data.copy()
csongor's avatar
csongor committed
328

Martin Reinecke's avatar
Martin Reinecke committed
329
        spaces = utilities.parse_spaces(spaces, len(self._domain))
csongor's avatar
csongor committed
330

331
332
        fct = 1.
        for ind in spaces:
Martin Reinecke's avatar
Martin Reinecke committed
333
            wgt = self._domain[ind].dvol
334
335
336
            if np.isscalar(wgt):
                fct *= wgt
            else:
Martin Reinecke's avatar
Martin Reinecke committed
337
                new_shape = np.ones(len(self.shape), dtype=np.int)
Martin Reinecke's avatar
Martin Reinecke committed
338
339
                new_shape[self._domain.axes[ind][0]:
                          self._domain.axes[ind][-1]+1] = wgt.shape
340
                wgt = wgt.reshape(new_shape)
Martin Reinecke's avatar
Martin Reinecke committed
341
342
                if dobj.distaxis(self._val) >= 0 and ind == 0:
                    # we need to distribute the weights along axis 0
Martin Reinecke's avatar
fixes    
Martin Reinecke committed
343
                    wgt = dobj.local_data(dobj.from_global_data(wgt))
344
                aout *= wgt**power
345
        fct = fct**power
Martin Reinecke's avatar
Martin Reinecke committed
346
        if fct != 1.:
347
            aout *= fct
348

349
        return Field.from_local_data(self._domain, aout)
csongor's avatar
csongor committed
350

Martin Reinecke's avatar
Martin Reinecke committed
351
    def vdot(self, x=None, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
352
        """ Computes the dot product of 'self' with x.
Theo Steininger's avatar
Theo Steininger committed
353

354
355
356
        Parameters
        ----------
        x : Field
357
            x must live on the same domain as `self`.
Theo Steininger's avatar
Theo Steininger committed
358

Martin Reinecke's avatar
Martin Reinecke committed
359
        spaces : None, int or tuple of int (default: None)
360
361
            The dot product is only carried out over the sub-domains in this
            tuple. If None, it is carried out over all sub-domains.
Theo Steininger's avatar
Theo Steininger committed
362

363
364
        Returns
        -------
Martin Reinecke's avatar
Martin Reinecke committed
365
        float, complex, either scalar (for full dot products)
366
                              or Field (for partial dot products)
367
        """
368
        if not isinstance(x, Field):
369
370
            raise TypeError("The dot-partner must be an instance of " +
                            "the NIFTy field class")
Theo Steininger's avatar
Theo Steininger committed
371

Martin Reinecke's avatar
Martin Reinecke committed
372
        if x._domain != self._domain:
373
            raise ValueError("Domain mismatch")
Theo Steininger's avatar
Theo Steininger committed
374

Martin Reinecke's avatar
Martin Reinecke committed
375
        ndom = len(self._domain)
376
377
378
        spaces = utilities.parse_spaces(spaces, ndom)

        if len(spaces) == ndom:
Martin Reinecke's avatar
Martin Reinecke committed
379
            return dobj.vdot(self.val, x.val)
380
381
        # If we arrive here, we have to do a partial dot product.
        # For the moment, do this the explicit, non-optimized way
Martin Reinecke's avatar
Martin Reinecke committed
382
        return (self.conjugate()*x).sum(spaces=spaces)
Theo Steininger's avatar
Theo Steininger committed
383

Theo Steininger's avatar
Theo Steininger committed
384
    def norm(self):
Martin Reinecke's avatar
tweaks    
Martin Reinecke committed
385
        """ Computes the L2-norm of the field values.
csongor's avatar
csongor committed
386

Theo Steininger's avatar
Theo Steininger committed
387
388
        Returns
        -------
Martin Reinecke's avatar
Martin Reinecke committed
389
        float
Martin Reinecke's avatar
tweaks    
Martin Reinecke committed
390
            The L2-norm of the field values.
csongor's avatar
csongor committed
391
        """
392
        return np.sqrt(abs(self.vdot(x=self)))
csongor's avatar
csongor committed
393

394
395
396
397
398
399
400
401
402
403
    def squared_norm(self):
        """ Computes the square of the L2-norm of the field values.

        Returns
        -------
        float
            The square of the L2-norm of the field values.
        """
        return abs(self.vdot(x=self))

Martin Reinecke's avatar
tweaks    
Martin Reinecke committed
404
    def conjugate(self):
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
405
        """ Returns the complex conjugate of the field.
Theo Steininger's avatar
Theo Steininger committed
406

407
408
        Returns
        -------
Martin Reinecke's avatar
Martin Reinecke committed
409
410
        Field
            The complex conjugated field.
csongor's avatar
csongor committed
411
        """
Martin Reinecke's avatar
Martin Reinecke committed
412
        return Field(self._domain, self.val.conjugate())
csongor's avatar
csongor committed
413

Theo Steininger's avatar
Theo Steininger committed
414
    # ---General unary/contraction methods---
415

Theo Steininger's avatar
Theo Steininger committed
416
    def __pos__(self):
417
        return self
418

Theo Steininger's avatar
Theo Steininger committed
419
    def __neg__(self):
420
        return Field(self._domain, -self.val)
csongor's avatar
csongor committed
421

Theo Steininger's avatar
Theo Steininger committed
422
    def __abs__(self):
423
        return Field(self._domain, abs(self.val))
csongor's avatar
csongor committed
424

425
    def _contraction_helper(self, op, spaces):
Theo Steininger's avatar
Theo Steininger committed
426
        if spaces is None:
427
            return getattr(self.val, op)()
428

Martin Reinecke's avatar
Martin Reinecke committed
429
        spaces = utilities.parse_spaces(spaces, len(self._domain))
csongor's avatar
csongor committed
430

Martin Reinecke's avatar
Martin Reinecke committed
431
        axes_list = tuple(self._domain.axes[sp_index] for sp_index in spaces)
432

Martin Reinecke's avatar
Martin Reinecke committed
433
        if len(axes_list) > 0:
Theo Steininger's avatar
Theo Steininger committed
434
            axes_list = reduce(lambda x, y: x+y, axes_list)
csongor's avatar
csongor committed
435

Martin Reinecke's avatar
stage1    
Martin Reinecke committed
436
        # perform the contraction on the data
437
        data = getattr(self.val, op)(axis=axes_list)
csongor's avatar
csongor committed
438

Theo Steininger's avatar
Theo Steininger committed
439
440
441
        # check if the result is scalar or if a result_field must be constr.
        if np.isscalar(data):
            return data
csongor's avatar
csongor committed
442
        else:
Martin Reinecke's avatar
Martin Reinecke committed
443
            return_domain = tuple(dom
Martin Reinecke's avatar
Martin Reinecke committed
444
                                  for i, dom in enumerate(self._domain)
Theo Steininger's avatar
Theo Steininger committed
445
                                  if i not in spaces)
446

447
            return Field(domain=return_domain, val=data)
csongor's avatar
csongor committed
448

449
    def sum(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
450
451
452
453
454
455
456
457
458
459
460
461
462
463
        """Sums up over the sub-domains given by `spaces`.

        Parameters
        ----------
        spaces : None, int or tuple of int (default: None)
            The summation is only carried out over the sub-domains in this
            tuple. If None, it is carried out over all sub-domains.

        Returns
        -------
        Field or scalar
            The result of the summation. If it is carried out over the entire
            domain, this is a scalar, otherwise a Field.
        """
464
        return self._contraction_helper('sum', spaces)
csongor's avatar
csongor committed
465

466
    def integrate(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
        """Integrates over the sub-domains given by `spaces`.

        Integration is performed by summing over `self` multiplied by its
        volume factors.

        Parameters
        ----------
        spaces : None, int or tuple of int (default: None)
            The summation is only carried out over the sub-domains in this
            tuple. If None, it is carried out over all sub-domains.

        Returns
        -------
        Field or scalar
            The result of the integration. If it is carried out over the
            entire domain, this is a scalar, otherwise a Field.
        """
Martin Reinecke's avatar
Martin Reinecke committed
484
485
486
487
488
        swgt = self.scalar_weight(spaces)
        if swgt is not None:
            res = self.sum(spaces)
            res *= swgt
            return res
489
490
491
        tmp = self.weight(1, spaces=spaces)
        return tmp.sum(spaces)

492
    def prod(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
493
494
495
496
497
498
499
500
501
502
503
504
505
506
        """Computes the product over the sub-domains given by `spaces`.

        Parameters
        ----------
        spaces : None, int or tuple of int (default: None)
            The operation is only carried out over the sub-domains in this
            tuple. If None, it is carried out over all sub-domains.

        Returns
        -------
        Field or scalar
            The result of the product. If it is carried out over the entire
            domain, this is a scalar, otherwise a Field.
        """
507
        return self._contraction_helper('prod', spaces)
csongor's avatar
csongor committed
508

509
510
    def all(self, spaces=None):
        return self._contraction_helper('all', spaces)
csongor's avatar
csongor committed
511

512
513
    def any(self, spaces=None):
        return self._contraction_helper('any', spaces)
csongor's avatar
csongor committed
514

515
    def min(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
516
517
518
519
520
521
522
523
524
525
526
527
528
529
        """Determines the minimum over the sub-domains given by `spaces`.

        Parameters
        ----------
        spaces : None, int or tuple of int (default: None)
            The operation is only carried out over the sub-domains in this
            tuple. If None, it is carried out over all sub-domains.

        Returns
        -------
        Field or scalar
            The result of the operation. If it is carried out over the entire
            domain, this is a scalar, otherwise a Field.
        """
530
        return self._contraction_helper('min', spaces)
csongor's avatar
csongor committed
531

532
    def max(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
533
534
535
536
537
538
539
540
541
542
543
544
545
546
        """Determines the maximum over the sub-domains given by `spaces`.

        Parameters
        ----------
        spaces : None, int or tuple of int (default: None)
            The operation is only carried out over the sub-domains in this
            tuple. If None, it is carried out over all sub-domains.

        Returns
        -------
        Field or scalar
            The result of the operation. If it is carried out over the entire
            domain, this is a scalar, otherwise a Field.
        """
547
        return self._contraction_helper('max', spaces)
csongor's avatar
csongor committed
548

549
    def mean(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
        """Determines the mean over the sub-domains given by `spaces`.

        ``x.mean(spaces)`` is equivalent to
        ``x.integrate(spaces)/x.total_volume(spaces)``.

        Parameters
        ----------
        spaces : None, int or tuple of int (default: None)
            The operation is only carried out over the sub-domains in this
            tuple. If None, it is carried out over all sub-domains.

        Returns
        -------
        Field or scalar
            The result of the operation. If it is carried out over the entire
            domain, this is a scalar, otherwise a Field.
        """
567
568
        if self.scalar_weight(spaces) is not None:
            return self._contraction_helper('mean', spaces)
Martin Reinecke's avatar
Martin Reinecke committed
569
        # MR FIXME: not very efficient
570
571
        # MR FIXME: do we need "spaces" here?
        tmp = self.weight(1, spaces)
Martin Reinecke's avatar
Martin Reinecke committed
572
        return tmp.sum(spaces)*(1./tmp.total_volume(spaces))
csongor's avatar
csongor committed
573

574
    def var(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
575
576
577
578
579
580
581
582
583
584
585
586
587
588
        """Determines the variance over the sub-domains given by `spaces`.

        Parameters
        ----------
        spaces : None, int or tuple of int (default: None)
            The operation is only carried out over the sub-domains in this
            tuple. If None, it is carried out over all sub-domains.

        Returns
        -------
        Field or scalar
            The result of the operation. If it is carried out over the entire
            domain, this is a scalar, otherwise a Field.
        """
589
590
        if self.scalar_weight(spaces) is not None:
            return self._contraction_helper('var', spaces)
Martin Reinecke's avatar
Martin Reinecke committed
591
592
593
        # MR FIXME: not very efficient or accurate
        m1 = self.mean(spaces)
        if np.issubdtype(self.dtype, np.complexfloating):
594
            sq = abs(self-m1)**2
Martin Reinecke's avatar
Martin Reinecke committed
595
        else:
596
597
            sq = (self-m1)**2
        return sq.mean(spaces)
csongor's avatar
csongor committed
598

599
    def std(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
        """Determines the standard deviation over the sub-domains given by
        `spaces`.

        ``x.std(spaces)`` is equivalent to ``sqrt(x.var(spaces))``.

        Parameters
        ----------
        spaces : None, int or tuple of int (default: None)
            The operation is only carried out over the sub-domains in this
            tuple. If None, it is carried out over all sub-domains.

        Returns
        -------
        Field or scalar
            The result of the operation. If it is carried out over the entire
            domain, this is a scalar, otherwise a Field.
        """
617
        from .sugar import sqrt
618
619
620
        if self.scalar_weight(spaces) is not None:
            return self._contraction_helper('std', spaces)
        return sqrt(self.var(spaces))
csongor's avatar
csongor committed
621

Theo Steininger's avatar
Theo Steininger committed
622
    def __repr__(self):
Philipp Arras's avatar
Philipp Arras committed
623
        return "<nifty5.Field>"
Theo Steininger's avatar
Theo Steininger committed
624
625

    def __str__(self):
Philipp Arras's avatar
Philipp Arras committed
626
        return "nifty5.Field instance\n- domain      = " + \
627
               self._domain.__str__() + \
628
               "\n- val         = " + repr(self.val)
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
629

630
631
632
    def isEquivalentTo(self, other):
        """Determines (as quickly as possible) whether `self`'s content is
        identical to `other`'s content."""
633
634
635
636
637
638
639
640
        if self is other:
            return True
        if not isinstance(other, Field):
            return False
        if self._domain != other._domain:
            return False
        return (self._val == other._val).all()

641
642
643
644
645
    def isSubsetOf(self, other):
        """Identical to `Field.isEquivalentTo()`. This method is provided for
        easier interoperability with `MultiField`."""
        return self.isEquivalentTo(other)

646

647
648
649
650
651
652
653
for op in ["__add__", "__radd__",
           "__sub__", "__rsub__",
           "__mul__", "__rmul__",
           "__div__", "__rdiv__",
           "__truediv__", "__rtruediv__",
           "__floordiv__", "__rfloordiv__",
           "__pow__", "__rpow__",
654
655
656
           "__lt__", "__le__", "__gt__", "__ge__", "__eq__", "__ne__"]:
    def func(op):
        def func2(self, other):
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
657
658
659
660
661
            # if other is a field, make sure that the domains match
            if isinstance(other, Field):
                if other._domain != self._domain:
                    raise ValueError("domains are incompatible.")
                tval = getattr(self.val, op)(other.val)
662
                return Field(self._domain, tval)
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
663

Martin Reinecke's avatar
fix    
Martin Reinecke committed
664
665
            if (np.isscalar(other) or
                    isinstance(other, (dobj.data_object, np.ndarray))):
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
666
                tval = getattr(self.val, op)(other)
667
                return Field(self._domain, tval)
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
668

Martin Reinecke's avatar
fix    
Martin Reinecke committed
669
            raise TypeError("should not arrive here")
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
670
            return NotImplemented
671
672
        return func2
    setattr(Field, op, func(op))
673
674
675
676
677
678
679
680
681

for op in ["__iadd__", "__isub__", "__imul__", "__idiv__",
           "__itruediv__", "__ifloordiv__", "__ipow__"]:
    def func(op):
        def func2(self, other):
            raise TypeError(
                "In-place operations are deliberately not supported")
        return func2
    setattr(Field, op, func(op))