field.py 21.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 .compat 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
24
from . import dobj
25

26

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

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

33
34
    Parameters
    ----------
35
36
    domain : DomainTuple
        the domain of the new Field
Theo Steininger's avatar
Theo Steininger committed
37

38
39
40
    val : data_object
        This object's global shape must match the domain shape
        After construction, the object will no longer be writeable!
Martin Reinecke's avatar
Martin Reinecke committed
41
42
43
44

    Notes
    -----
    If possible, do not invoke the constructor directly, but use one of the
45
    many convenience functions for Field construction!
46
    """
47

48
49
50
51
52
53
54
55
56
    def __init__(self, domain, val):
        if not isinstance(domain, DomainTuple):
            raise TypeError("domain must be of type DomainTuple")
        if not isinstance(val, dobj.data_object):
            raise TypeError("val must be of type dobj.data_object")
        if domain.shape != val.shape:
            raise ValueError("mismatch between the shapes of val and domain")
        self._domain = domain
        self._val = val
57
        dobj.lock(self._val)
Martin Reinecke's avatar
Martin Reinecke committed
58

59
60
61
62
63
64
65
    # 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")

66
    @staticmethod
67
    def full(domain, val):
Martin Reinecke's avatar
Martin Reinecke committed
68
69
70
71
72
73
74
75
76
77
78
79
80
81
        """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
        """
82
83
        if not np.isscalar(val):
            raise TypeError("val must be a scalar")
84
85
86
87
        if not (np.isreal(val) or np.iscomplex(val)):
            raise TypeError("need arithmetic scalar")
        domain = DomainTuple.make(domain)
        return Field(domain, dobj.full(domain.shape, fill_value=val))
88

89
    @staticmethod
90
    def from_global_data(domain, arr, sum_up=False):
Martin Reinecke's avatar
Martin Reinecke committed
91
92
93
94
95
96
97
98
99
        """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`.
100
101
102
103
104
        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
105
        """
106
107
        return Field(DomainTuple.make(domain),
                     dobj.from_global_data(arr, sum_up))
108

Martin Reinecke's avatar
Martin Reinecke committed
109
110
    @staticmethod
    def from_local_data(domain, arr):
111
112
        return Field(DomainTuple.make(domain),
            dobj.from_local_data(domain.shape, arr))
Martin Reinecke's avatar
Martin Reinecke committed
113

114
    def to_global_data(self):
Martin Reinecke's avatar
Martin Reinecke committed
115
116
117
118
119
120
121
122
123
124
125
126
        """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.
        """
127
128
        return dobj.to_global_data(self._val)

Martin Reinecke's avatar
Martin Reinecke committed
129
130
    @property
    def local_data(self):
Martin Reinecke's avatar
Martin Reinecke committed
131
132
133
134
135
        """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
136
137
        return dobj.local_data(self._val)

Martin Reinecke's avatar
Martin Reinecke committed
138
    def cast_domain(self, new_domain):
Martin Reinecke's avatar
Martin Reinecke committed
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
        """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.
        """
156
        return Field(DomainTuple.make(new_domain), self._val)
157

Martin Reinecke's avatar
Martin Reinecke committed
158
159
    @staticmethod
    def from_random(random_type, domain, dtype=np.float64, **kwargs):
160
161
162
163
        """ Draws a random field with the given parameters.

        Parameters
        ----------
Martin Reinecke's avatar
Martin Reinecke committed
164
165
        random_type : 'pm1', 'normal', or 'uniform'
            The random distribution to use.
Martin Reinecke's avatar
Martin Reinecke committed
166
        domain : DomainTuple
167
168
169
            The domain of the output random field
        dtype : type
            The datatype of the output random field
Theo Steininger's avatar
Theo Steininger committed
170

171
172
        Returns
        -------
Martin Reinecke's avatar
Martin Reinecke committed
173
        Field
Martin Reinecke's avatar
Martin Reinecke committed
174
            The newly created Field.
175
        """
Martin Reinecke's avatar
Martin Reinecke committed
176
        domain = DomainTuple.make(domain)
Martin Reinecke's avatar
Martin Reinecke committed
177
178
179
        return Field(domain=domain,
                     val=dobj.from_random(random_type, dtype=dtype,
                                          shape=domain.shape, **kwargs))
180

Theo Steininger's avatar
Theo Steininger committed
181
182
    @property
    def val(self):
Martin Reinecke's avatar
Martin Reinecke committed
183
184
185
186
187
188
        """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.
189
        """
Martin Reinecke's avatar
Martin Reinecke committed
190
        return self._val
csongor's avatar
csongor committed
191

Martin Reinecke's avatar
Martin Reinecke committed
192
193
    @property
    def dtype(self):
Martin Reinecke's avatar
Martin Reinecke committed
194
        """type : the data type of the field's entries"""
Martin Reinecke's avatar
Martin Reinecke committed
195
196
        return self._val.dtype

Martin Reinecke's avatar
Martin Reinecke committed
197
198
    @property
    def domain(self):
Martin Reinecke's avatar
Martin Reinecke committed
199
        """DomainTuple : the field's domain"""
Martin Reinecke's avatar
Martin Reinecke committed
200
201
        return self._domain

202
203
    @property
    def shape(self):
Martin Reinecke's avatar
Martin Reinecke committed
204
        """tuple of int : the concatenated shapes of all sub-domains"""
Martin Reinecke's avatar
Martin Reinecke committed
205
        return self._domain.shape
csongor's avatar
csongor committed
206

207
    @property
Martin Reinecke's avatar
Martin Reinecke committed
208
    def size(self):
Martin Reinecke's avatar
Martin Reinecke committed
209
        """int : total number of pixels in the field"""
Martin Reinecke's avatar
Martin Reinecke committed
210
        return self._domain.size
csongor's avatar
csongor committed
211

Theo Steininger's avatar
Theo Steininger committed
212
213
    @property
    def real(self):
Martin Reinecke's avatar
Martin Reinecke committed
214
        """Field : The real part of the field"""
215
        if not np.issubdtype(self.dtype, np.complexfloating):
216
            return self
Martin Reinecke's avatar
Martin Reinecke committed
217
        return Field(self._domain, self.val.real)
Theo Steininger's avatar
Theo Steininger committed
218
219
220

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

226
    def scalar_weight(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
227
228
229
230
231
232
233
234
235
236
237
238
239
240
        """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.
        """
241
        if np.isscalar(spaces):
Martin Reinecke's avatar
Martin Reinecke committed
242
            return self._domain[spaces].scalar_dvol
243
244

        if spaces is None:
Martin Reinecke's avatar
Martin Reinecke committed
245
            spaces = range(len(self._domain))
Martin Reinecke's avatar
Martin Reinecke committed
246
        res = 1.
247
        for i in spaces:
Martin Reinecke's avatar
Martin Reinecke committed
248
            tmp = self._domain[i].scalar_dvol
249
250
251
252
253
            if tmp is None:
                return None
            res *= tmp
        return res

Martin Reinecke's avatar
Martin Reinecke committed
254
    def total_volume(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
255
256
257
258
259
260
261
262
263
264
265
266
267
        """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
268
        if np.isscalar(spaces):
Martin Reinecke's avatar
Martin Reinecke committed
269
            return self._domain[spaces].total_volume
Martin Reinecke's avatar
Martin Reinecke committed
270
271
272
273
274

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

278
    def weight(self, power=1, spaces=None):
Theo Steininger's avatar
Theo Steininger committed
279
        """ Weights the pixels of `self` with their invidual pixel-volume.
280
281
282
283

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

Martin Reinecke's avatar
Martin Reinecke committed
286
287
288
        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
289

290
291
        Returns
        -------
Martin Reinecke's avatar
Martin Reinecke committed
292
        Field
Theo Steininger's avatar
Theo Steininger committed
293
            The weighted field.
294
        """
295
        aout = self.local_data.copy()
csongor's avatar
csongor committed
296

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

299
300
        fct = 1.
        for ind in spaces:
Martin Reinecke's avatar
Martin Reinecke committed
301
            wgt = self._domain[ind].dvol
302
303
304
            if np.isscalar(wgt):
                fct *= wgt
            else:
Martin Reinecke's avatar
Martin Reinecke committed
305
                new_shape = np.ones(len(self.shape), dtype=np.int)
Martin Reinecke's avatar
Martin Reinecke committed
306
307
                new_shape[self._domain.axes[ind][0]:
                          self._domain.axes[ind][-1]+1] = wgt.shape
308
                wgt = wgt.reshape(new_shape)
Martin Reinecke's avatar
Martin Reinecke committed
309
310
                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
311
                    wgt = dobj.local_data(dobj.from_global_data(wgt))
312
                aout *= wgt**power
313
        fct = fct**power
Martin Reinecke's avatar
Martin Reinecke committed
314
        if fct != 1.:
315
            aout *= fct
316

317
        return Field.from_local_data(self._domain, aout)
csongor's avatar
csongor committed
318

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

322
323
324
        Parameters
        ----------
        x : Field
325
            x must live on the same domain as `self`.
Theo Steininger's avatar
Theo Steininger committed
326

Martin Reinecke's avatar
Martin Reinecke committed
327
        spaces : None, int or tuple of int (default: None)
328
329
            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
330

331
332
        Returns
        -------
Martin Reinecke's avatar
Martin Reinecke committed
333
        float, complex, either scalar (for full dot products)
334
                              or Field (for partial dot products)
335
        """
336
        if not isinstance(x, Field):
337
338
            raise TypeError("The dot-partner must be an instance of " +
                            "the NIFTy field class")
Theo Steininger's avatar
Theo Steininger committed
339

340
        if x._domain is not self._domain:
341
            raise ValueError("Domain mismatch")
Theo Steininger's avatar
Theo Steininger committed
342

Martin Reinecke's avatar
Martin Reinecke committed
343
        ndom = len(self._domain)
344
345
346
        spaces = utilities.parse_spaces(spaces, ndom)

        if len(spaces) == ndom:
Martin Reinecke's avatar
Martin Reinecke committed
347
            return dobj.vdot(self.val, x.val)
348
349
        # 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
350
        return (self.conjugate()*x).sum(spaces=spaces)
Theo Steininger's avatar
Theo Steininger committed
351

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

Theo Steininger's avatar
Theo Steininger committed
355
356
        Returns
        -------
Martin Reinecke's avatar
Martin Reinecke committed
357
        float
Martin Reinecke's avatar
tweaks    
Martin Reinecke committed
358
            The L2-norm of the field values.
csongor's avatar
csongor committed
359
        """
360
        return np.sqrt(abs(self.vdot(x=self)))
csongor's avatar
csongor committed
361

362
363
364
365
366
367
368
369
370
371
    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
372
    def conjugate(self):
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
373
        """ Returns the complex conjugate of the field.
Theo Steininger's avatar
Theo Steininger committed
374

375
376
        Returns
        -------
Martin Reinecke's avatar
Martin Reinecke committed
377
378
        Field
            The complex conjugated field.
csongor's avatar
csongor committed
379
        """
Martin Reinecke's avatar
Martin Reinecke committed
380
        return Field(self._domain, self.val.conjugate())
csongor's avatar
csongor committed
381

Theo Steininger's avatar
Theo Steininger committed
382
    # ---General unary/contraction methods---
383

Theo Steininger's avatar
Theo Steininger committed
384
    def __pos__(self):
385
        return self
386

Theo Steininger's avatar
Theo Steininger committed
387
    def __neg__(self):
388
        return Field(self._domain, -self.val)
csongor's avatar
csongor committed
389

Theo Steininger's avatar
Theo Steininger committed
390
    def __abs__(self):
391
        return Field(self._domain, abs(self.val))
csongor's avatar
csongor committed
392

393
    def _contraction_helper(self, op, spaces):
Theo Steininger's avatar
Theo Steininger committed
394
        if spaces is None:
395
            return getattr(self.val, op)()
396

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

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

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

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

Theo Steininger's avatar
Theo Steininger committed
407
408
409
        # 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
410
        else:
Martin Reinecke's avatar
Martin Reinecke committed
411
            return_domain = tuple(dom
Martin Reinecke's avatar
Martin Reinecke committed
412
                                  for i, dom in enumerate(self._domain)
Theo Steininger's avatar
Theo Steininger committed
413
                                  if i not in spaces)
414

415
            return Field(DomainTuple.make(return_domain), data)
csongor's avatar
csongor committed
416

417
    def sum(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
418
419
420
421
422
423
424
425
426
427
428
429
430
431
        """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.
        """
432
        return self._contraction_helper('sum', spaces)
csongor's avatar
csongor committed
433

434
    def integrate(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
        """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
452
453
454
455
456
        swgt = self.scalar_weight(spaces)
        if swgt is not None:
            res = self.sum(spaces)
            res *= swgt
            return res
457
458
459
        tmp = self.weight(1, spaces=spaces)
        return tmp.sum(spaces)

460
    def prod(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
461
462
463
464
465
466
467
468
469
470
471
472
473
474
        """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.
        """
475
        return self._contraction_helper('prod', spaces)
csongor's avatar
csongor committed
476

477
478
    def all(self, spaces=None):
        return self._contraction_helper('all', spaces)
csongor's avatar
csongor committed
479

480
481
    def any(self, spaces=None):
        return self._contraction_helper('any', spaces)
csongor's avatar
csongor committed
482

483
    def min(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
484
485
486
487
488
489
490
491
492
493
494
495
496
497
        """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.
        """
498
        return self._contraction_helper('min', spaces)
csongor's avatar
csongor committed
499

500
    def max(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
501
502
503
504
505
506
507
508
509
510
511
512
513
514
        """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.
        """
515
        return self._contraction_helper('max', spaces)
csongor's avatar
csongor committed
516

517
    def mean(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
        """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.
        """
535
536
        if self.scalar_weight(spaces) is not None:
            return self._contraction_helper('mean', spaces)
Martin Reinecke's avatar
Martin Reinecke committed
537
        # MR FIXME: not very efficient
538
539
        # MR FIXME: do we need "spaces" here?
        tmp = self.weight(1, spaces)
Martin Reinecke's avatar
Martin Reinecke committed
540
        return tmp.sum(spaces)*(1./tmp.total_volume(spaces))
csongor's avatar
csongor committed
541

542
    def var(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
543
544
545
546
547
548
549
550
551
552
553
554
555
556
        """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.
        """
557
558
        if self.scalar_weight(spaces) is not None:
            return self._contraction_helper('var', spaces)
Martin Reinecke's avatar
Martin Reinecke committed
559
560
561
        # MR FIXME: not very efficient or accurate
        m1 = self.mean(spaces)
        if np.issubdtype(self.dtype, np.complexfloating):
562
            sq = abs(self-m1)**2
Martin Reinecke's avatar
Martin Reinecke committed
563
        else:
564
565
            sq = (self-m1)**2
        return sq.mean(spaces)
csongor's avatar
csongor committed
566

567
    def std(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
        """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.
        """
585
        from .sugar import sqrt
586
587
588
        if self.scalar_weight(spaces) is not None:
            return self._contraction_helper('std', spaces)
        return sqrt(self.var(spaces))
csongor's avatar
csongor committed
589

Theo Steininger's avatar
Theo Steininger committed
590
    def __repr__(self):
Philipp Arras's avatar
Philipp Arras committed
591
        return "<nifty5.Field>"
Theo Steininger's avatar
Theo Steininger committed
592
593

    def __str__(self):
Philipp Arras's avatar
Philipp Arras committed
594
        return "nifty5.Field instance\n- domain      = " + \
595
               self._domain.__str__() + \
596
               "\n- val         = " + repr(self.val)
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
597

598
599
600
    def isEquivalentTo(self, other):
        """Determines (as quickly as possible) whether `self`'s content is
        identical to `other`'s content."""
601
602
603
604
        if self is other:
            return True
        if not isinstance(other, Field):
            return False
605
        if self._domain is not other._domain:
606
607
608
            return False
        return (self._val == other._val).all()

609
610
611
612
613
    def isSubsetOf(self, other):
        """Identical to `Field.isEquivalentTo()`. This method is provided for
        easier interoperability with `MultiField`."""
        return self.isEquivalentTo(other)

614

615
616
617
618
619
620
621
for op in ["__add__", "__radd__",
           "__sub__", "__rsub__",
           "__mul__", "__rmul__",
           "__div__", "__rdiv__",
           "__truediv__", "__rtruediv__",
           "__floordiv__", "__rfloordiv__",
           "__pow__", "__rpow__",
622
623
624
           "__lt__", "__le__", "__gt__", "__ge__", "__eq__", "__ne__"]:
    def func(op):
        def func2(self, other):
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
625
626
            # if other is a field, make sure that the domains match
            if isinstance(other, Field):
627
                if other._domain is not self._domain:
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
628
629
                    raise ValueError("domains are incompatible.")
                tval = getattr(self.val, op)(other.val)
630
                return Field(self._domain, tval)
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
631

Martin Reinecke's avatar
fix    
Martin Reinecke committed
632
633
            if (np.isscalar(other) or
                    isinstance(other, (dobj.data_object, np.ndarray))):
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
634
                tval = getattr(self.val, op)(other)
635
                return Field(self._domain, tval)
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
636

Martin Reinecke's avatar
fix    
Martin Reinecke committed
637
            raise TypeError("should not arrive here")
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
638
            return NotImplemented
639
640
        return func2
    setattr(Field, op, func(op))
641
642
643
644
645
646
647
648
649

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))