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
from __future__ import absolute_import, division, print_function
20

csongor's avatar
csongor committed
21
import numpy as np
22
23
24

from . import dobj, utilities
from .compat import *
Martin Reinecke's avatar
Martin Reinecke committed
25
from .domain_tuple import DomainTuple
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
    ----------
36
37
    domain : DomainTuple
        the domain of the new Field
Theo Steininger's avatar
Theo Steininger committed
38

39
40
41
    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
42
43
44
45

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

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

63
64
65
66
67
68
69
    # 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")

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

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

Martin Reinecke's avatar
Martin Reinecke committed
113
114
    @staticmethod
    def from_local_data(domain, arr):
115
        return Field(DomainTuple.make(domain),
Martin Reinecke's avatar
Martin Reinecke committed
116
                     dobj.from_local_data(domain.shape, arr))
Martin Reinecke's avatar
Martin Reinecke committed
117

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

128
129
130
131
132
133
134
135
136
137
    def to_global_data_rw(self):
        """Returns a modifiable array containing the full data of the field.

        Returns
        -------
        numpy.ndarray : array containing all field entries, which can be
            modified. Its shape is identical to `self.shape`.
        """
        return dobj.to_global_data_rw(self._val)

Martin Reinecke's avatar
Martin Reinecke committed
138
139
    @property
    def local_data(self):
Martin Reinecke's avatar
Martin Reinecke committed
140
141
142
143
144
        """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
145
146
        return dobj.local_data(self._val)

Martin Reinecke's avatar
Martin Reinecke committed
147
    def cast_domain(self, new_domain):
Martin Reinecke's avatar
Martin Reinecke committed
148
149
150
151
152
153
154
155
156
157
158
159
160
        """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`.
        """
161
        return Field(DomainTuple.make(new_domain), self._val)
162

Martin Reinecke's avatar
Martin Reinecke committed
163
164
    @staticmethod
    def from_random(random_type, domain, dtype=np.float64, **kwargs):
165
166
167
168
        """ Draws a random field with the given parameters.

        Parameters
        ----------
Martin Reinecke's avatar
Martin Reinecke committed
169
170
        random_type : 'pm1', 'normal', or 'uniform'
            The random distribution to use.
Martin Reinecke's avatar
Martin Reinecke committed
171
        domain : DomainTuple
172
173
174
            The domain of the output random field
        dtype : type
            The datatype of the output random field
Theo Steininger's avatar
Theo Steininger committed
175

176
177
        Returns
        -------
Martin Reinecke's avatar
Martin Reinecke committed
178
        Field
Martin Reinecke's avatar
Martin Reinecke committed
179
            The newly created Field.
180
        """
Martin Reinecke's avatar
Martin Reinecke committed
181
        domain = DomainTuple.make(domain)
Martin Reinecke's avatar
Martin Reinecke committed
182
183
184
        return Field(domain=domain,
                     val=dobj.from_random(random_type, dtype=dtype,
                                          shape=domain.shape, **kwargs))
185

Theo Steininger's avatar
Theo Steininger committed
186
187
    @property
    def val(self):
Martin Reinecke's avatar
Martin Reinecke committed
188
189
190
191
192
193
        """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.
194
        """
Martin Reinecke's avatar
Martin Reinecke committed
195
        return self._val
csongor's avatar
csongor committed
196

Martin Reinecke's avatar
Martin Reinecke committed
197
198
    @property
    def dtype(self):
Martin Reinecke's avatar
Martin Reinecke committed
199
        """type : the data type of the field's entries"""
Martin Reinecke's avatar
Martin Reinecke committed
200
201
        return self._val.dtype

Martin Reinecke's avatar
Martin Reinecke committed
202
203
    @property
    def domain(self):
Martin Reinecke's avatar
Martin Reinecke committed
204
        """DomainTuple : the field's domain"""
Martin Reinecke's avatar
Martin Reinecke committed
205
206
        return self._domain

207
208
    @property
    def shape(self):
Martin Reinecke's avatar
Martin Reinecke committed
209
        """tuple of int : the concatenated shapes of all sub-domains"""
Martin Reinecke's avatar
Martin Reinecke committed
210
        return self._domain.shape
csongor's avatar
csongor committed
211

212
    @property
Martin Reinecke's avatar
Martin Reinecke committed
213
    def size(self):
Martin Reinecke's avatar
Martin Reinecke committed
214
        """int : total number of pixels in the field"""
Martin Reinecke's avatar
Martin Reinecke committed
215
        return self._domain.size
csongor's avatar
csongor committed
216

Theo Steininger's avatar
Theo Steininger committed
217
218
    @property
    def real(self):
Martin Reinecke's avatar
Martin Reinecke committed
219
        """Field : The real part of the field"""
Martin Reinecke's avatar
Martin Reinecke committed
220
221
222
        if utilities.iscomplextype(self.dtype):
            return Field(self._domain, self._val.real)
        return self
Theo Steininger's avatar
Theo Steininger committed
223
224
225

    @property
    def imag(self):
Martin Reinecke's avatar
Martin Reinecke committed
226
        """Field : The imaginary part of the field"""
Martin Reinecke's avatar
Martin Reinecke committed
227
        if not utilities.iscomplextype(self.dtype):
228
            raise ValueError(".imag called on a non-complex Field")
Martin Reinecke's avatar
Martin Reinecke committed
229
        return Field(self._domain, self._val.imag)
Theo Steininger's avatar
Theo Steininger committed
230

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

        if spaces is None:
Martin Reinecke's avatar
Martin Reinecke committed
250
            spaces = range(len(self._domain))
Martin Reinecke's avatar
Martin Reinecke committed
251
        res = 1.
252
        for i in spaces:
Martin Reinecke's avatar
Martin Reinecke committed
253
            tmp = self._domain[i].scalar_dvol
254
255
256
257
258
            if tmp is None:
                return None
            res *= tmp
        return res

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

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

283
    def weight(self, power=1, spaces=None):
Theo Steininger's avatar
Theo Steininger committed
284
        """ Weights the pixels of `self` with their invidual pixel-volume.
285
286
287
288

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

Martin Reinecke's avatar
Martin Reinecke committed
291
292
293
        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
294

295
296
        Returns
        -------
Martin Reinecke's avatar
Martin Reinecke committed
297
        Field
Theo Steininger's avatar
Theo Steininger committed
298
            The weighted field.
299
        """
300
        aout = self.local_data.copy()
csongor's avatar
csongor committed
301

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

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

322
        return Field.from_local_data(self._domain, aout)
csongor's avatar
csongor committed
323

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

327
328
329
        Parameters
        ----------
        x : Field
330
            x must live on the same domain as `self`.
Theo Steininger's avatar
Theo Steininger committed
331

Martin Reinecke's avatar
Martin Reinecke committed
332
        spaces : None, int or tuple of int (default: None)
333
334
            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
335

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

345
        if x._domain is not self._domain:
346
            raise ValueError("Domain mismatch")
Theo Steininger's avatar
Theo Steininger committed
347

Martin Reinecke's avatar
Martin Reinecke committed
348
        ndom = len(self._domain)
349
350
351
        spaces = utilities.parse_spaces(spaces, ndom)

        if len(spaces) == ndom:
Martin Reinecke's avatar
Martin Reinecke committed
352
            return dobj.vdot(self._val, x._val)
353
354
        # 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
355
        return (self.conjugate()*x).sum(spaces=spaces)
Theo Steininger's avatar
Theo Steininger committed
356

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

Theo Steininger's avatar
Theo Steininger committed
360
361
        Returns
        -------
Martin Reinecke's avatar
Martin Reinecke committed
362
        float
Martin Reinecke's avatar
tweaks    
Martin Reinecke committed
363
            The L2-norm of the field values.
csongor's avatar
csongor committed
364
        """
365
        return np.sqrt(abs(self.vdot(x=self)))
csongor's avatar
csongor committed
366

367
368
369
370
371
372
373
374
375
376
    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
377
    def conjugate(self):
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
378
        """ Returns the complex conjugate of the field.
Theo Steininger's avatar
Theo Steininger committed
379

380
381
        Returns
        -------
Martin Reinecke's avatar
Martin Reinecke committed
382
383
        Field
            The complex conjugated field.
csongor's avatar
csongor committed
384
        """
Martin Reinecke's avatar
Martin Reinecke committed
385
        if utilities.iscomplextype(self._val.dtype):
Martin Reinecke's avatar
Martin Reinecke committed
386
387
            return Field(self._domain, self._val.conjugate())
        return self
csongor's avatar
csongor committed
388

Theo Steininger's avatar
Theo Steininger committed
389
    # ---General unary/contraction methods---
390

Theo Steininger's avatar
Theo Steininger committed
391
    def __pos__(self):
392
        return self
393

Theo Steininger's avatar
Theo Steininger committed
394
    def __neg__(self):
Martin Reinecke's avatar
Martin Reinecke committed
395
        return Field(self._domain, -self._val)
csongor's avatar
csongor committed
396

Theo Steininger's avatar
Theo Steininger committed
397
    def __abs__(self):
Martin Reinecke's avatar
Martin Reinecke committed
398
        return Field(self._domain, abs(self._val))
csongor's avatar
csongor committed
399

400
    def _contraction_helper(self, op, spaces):
Theo Steininger's avatar
Theo Steininger committed
401
        if spaces is None:
Martin Reinecke's avatar
Martin Reinecke committed
402
            return getattr(self._val, op)()
403

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

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

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

Martin Reinecke's avatar
stage1    
Martin Reinecke committed
411
        # perform the contraction on the data
Martin Reinecke's avatar
Martin Reinecke committed
412
        data = getattr(self._val, op)(axis=axes_list)
csongor's avatar
csongor committed
413

Theo Steininger's avatar
Theo Steininger committed
414
415
416
        # 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
417
        else:
Martin Reinecke's avatar
Martin Reinecke committed
418
            return_domain = tuple(dom
Martin Reinecke's avatar
Martin Reinecke committed
419
                                  for i, dom in enumerate(self._domain)
Theo Steininger's avatar
Theo Steininger committed
420
                                  if i not in spaces)
421

422
            return Field(DomainTuple.make(return_domain), data)
csongor's avatar
csongor committed
423

424
    def sum(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
425
426
427
428
429
430
431
432
433
434
435
436
437
438
        """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.
        """
439
        return self._contraction_helper('sum', spaces)
csongor's avatar
csongor committed
440

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

467
    def prod(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
468
469
470
471
472
473
474
475
476
477
478
479
480
481
        """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.
        """
482
        return self._contraction_helper('prod', spaces)
csongor's avatar
csongor committed
483

484
485
    def all(self, spaces=None):
        return self._contraction_helper('all', spaces)
csongor's avatar
csongor committed
486

487
488
    def any(self, spaces=None):
        return self._contraction_helper('any', spaces)
csongor's avatar
csongor committed
489

490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
#     def min(self, spaces=None):
#         """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.
#         """
#         return self._contraction_helper('min', spaces)
#
#     def max(self, spaces=None):
#         """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.
#         """
#         return self._contraction_helper('max', spaces)
csongor's avatar
csongor committed
523

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

549
    def var(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
550
551
552
553
554
555
556
557
558
559
560
561
562
563
        """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.
        """
564
565
        if self.scalar_weight(spaces) is not None:
            return self._contraction_helper('var', spaces)
Martin Reinecke's avatar
Martin Reinecke committed
566
567
        # MR FIXME: not very efficient or accurate
        m1 = self.mean(spaces)
Martin Reinecke's avatar
Martin Reinecke committed
568
        if utilities.iscomplextype(self.dtype):
569
            sq = abs(self-m1)**2
Martin Reinecke's avatar
Martin Reinecke committed
570
        else:
571
572
            sq = (self-m1)**2
        return sq.mean(spaces)
csongor's avatar
csongor committed
573

574
    def std(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
        """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.
        """
592
        from .sugar import sqrt
593
594
595
        if self.scalar_weight(spaces) is not None:
            return self._contraction_helper('std', spaces)
        return sqrt(self.var(spaces))
csongor's avatar
csongor committed
596

Theo Steininger's avatar
Theo Steininger committed
597
    def __repr__(self):
Philipp Arras's avatar
Philipp Arras committed
598
        return "<nifty5.Field>"
Theo Steininger's avatar
Theo Steininger committed
599
600

    def __str__(self):
Philipp Arras's avatar
Philipp Arras committed
601
        return "nifty5.Field instance\n- domain      = " + \
602
               self._domain.__str__() + \
Martin Reinecke's avatar
Martin Reinecke committed
603
               "\n- val         = " + repr(self._val)
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
604

Martin Reinecke's avatar
more    
Martin Reinecke committed
605
606
607
608
609
610
611
    def extract(self, dom):
        if dom is not self._domain:
            raise ValueError("domain mismatch")
        return self

    def unite(self, other):
        return self + other
612

Martin Reinecke's avatar
Martin Reinecke committed
613
    def positive_tanh(self):
Martin Reinecke's avatar
Martin Reinecke committed
614
615
616
617
618
619
        return 0.5*(1.+self.tanh())


for op in ["__add__", "__radd__",
           "__sub__", "__rsub__",
           "__mul__", "__rmul__",
620
621
622
623
           "__div__", "__rdiv__",
           "__truediv__", "__rtruediv__",
           "__floordiv__", "__rfloordiv__",
           "__pow__", "__rpow__",
624
625
626
           "__lt__", "__le__", "__gt__", "__ge__", "__eq__", "__ne__"]:
    def func(op):
        def func2(self, other):
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
627
628
            # if other is a field, make sure that the domains match
            if isinstance(other, Field):
629
                if other._domain is not self._domain:
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
630
                    raise ValueError("domains are incompatible.")
Martin Reinecke's avatar
Martin Reinecke committed
631
                tval = getattr(self._val, op)(other._val)
632
                return Field(self._domain, tval)
633
            if np.isscalar(other):
Martin Reinecke's avatar
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
            return NotImplemented
637
638
        return func2
    setattr(Field, op, func(op))
639
640
641
642
643
644
645
646
647

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))
Martin Reinecke's avatar
Martin Reinecke committed
648
649
650
651

for f in ["sqrt", "exp", "log", "tanh"]:
    def func(f):
        def func2(self):
Martin Reinecke's avatar
Martin Reinecke committed
652
653
            fu = getattr(dobj, f)
            return Field(domain=self._domain, val=fu(self.val))
Martin Reinecke's avatar
Martin Reinecke committed
654
655
        return func2
    setattr(Field, f, func(f))