field.py 25.8 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
    def __init__(self, domain, val):
Martin Reinecke's avatar
Martin Reinecke committed
50
        self._uni = None
51
52
53
        if not isinstance(domain, DomainTuple):
            raise TypeError("domain must be of type DomainTuple")
        if not isinstance(val, dobj.data_object):
Martin Reinecke's avatar
Martin Reinecke committed
54
            if np.isscalar(val):
Martin Reinecke's avatar
Martin Reinecke committed
55
56
                self._uni = val
                val = dobj.uniform_full(domain.shape, val)
Martin Reinecke's avatar
Martin Reinecke committed
57
58
            else:
                raise TypeError("val must be of type dobj.data_object")
59
60
61
62
        if domain.shape != val.shape:
            raise ValueError("mismatch between the shapes of val and domain")
        self._domain = domain
        self._val = val
63
        dobj.lock(self._val)
Martin Reinecke's avatar
Martin Reinecke committed
64

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

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

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

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

120
    def to_global_data(self):
Martin Reinecke's avatar
Martin Reinecke committed
121
122
123
124
125
126
127
128
129
130
131
132
        """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.
        """
133
134
        return dobj.to_global_data(self._val)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Theo Steininger's avatar
Theo Steininger committed
395
    def __neg__(self):
Martin Reinecke's avatar
Martin Reinecke committed
396
397
398
        if self._uni is None:
            return Field(self._domain, -self._val)
        return Field(self._domain, -self._uni)
csongor's avatar
csongor committed
399

Theo Steininger's avatar
Theo Steininger committed
400
    def __abs__(self):
Martin Reinecke's avatar
Martin Reinecke committed
401
402
403
        if self._uni is None:
            return Field(self._domain, abs(self._val))
        return Field(self._domain, abs(self._uni))
csongor's avatar
csongor committed
404

405
    def _contraction_helper(self, op, spaces):
Theo Steininger's avatar
Theo Steininger committed
406
        if spaces is None:
Martin Reinecke's avatar
Martin Reinecke committed
407
            return getattr(self._val, op)()
408

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

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

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

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

Theo Steininger's avatar
Theo Steininger committed
419
420
421
        # 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
422
        else:
Martin Reinecke's avatar
Martin Reinecke committed
423
            return_domain = tuple(dom
Martin Reinecke's avatar
Martin Reinecke committed
424
                                  for i, dom in enumerate(self._domain)
Theo Steininger's avatar
Theo Steininger committed
425
                                  if i not in spaces)
426

427
            return Field(DomainTuple.make(return_domain), data)
csongor's avatar
csongor committed
428

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

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

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

489
490
    def all(self, spaces=None):
        return self._contraction_helper('all', spaces)
csongor's avatar
csongor committed
491

492
493
    def any(self, spaces=None):
        return self._contraction_helper('any', spaces)
csongor's avatar
csongor committed
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
523
524
525
526
527
#     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
528

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

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

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

Theo Steininger's avatar
Theo Steininger committed
602
    def __repr__(self):
Philipp Arras's avatar
Philipp Arras committed
603
        return "<nifty5.Field>"
Theo Steininger's avatar
Theo Steininger committed
604
605

    def __str__(self):
Philipp Arras's avatar
Philipp Arras committed
606
        return "nifty5.Field instance\n- domain      = " + \
607
               self._domain.__str__() + \
Martin Reinecke's avatar
Martin Reinecke committed
608
               "\n- val         = " + repr(self._val)
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
609

610
611
612
    def isEquivalentTo(self, other):
        """Determines (as quickly as possible) whether `self`'s content is
        identical to `other`'s content."""
613
614
615
616
        if self is other:
            return True
        if not isinstance(other, Field):
            return False
617
        if self._domain is not other._domain:
618
619
620
            return False
        return (self._val == other._val).all()

Martin Reinecke's avatar
more    
Martin Reinecke committed
621
622
623
624
625
626
627
    def extract(self, dom):
        if dom is not self._domain:
            raise ValueError("domain mismatch")
        return self

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

Martin Reinecke's avatar
Martin Reinecke committed
629
    def positive_tanh(self):
Martin Reinecke's avatar
Martin Reinecke committed
630
631
632
        if self._uni is None:
            return 0.5*(1.+self.tanh())
        return Field(self._domain, 0.5*(1.+np.tanh(self._uni)))
Martin Reinecke's avatar
Martin Reinecke committed
633

634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
    def __add__(self, other):
        # if other is a field, make sure that the domains match
        if isinstance(other, Field):
            if other._domain is not self._domain:
                raise ValueError("domains are incompatible.")
            if self._uni is None:
                if other._uni is None:
                    return Field(self._domain, self._val+other._val)
                if other._uni == 0:
                    return self
                return Field(self._domain, self._val+other._uni)
            else:
                if self._uni == 0:
                    return other
                if other._uni is None:
                    return Field(self._domain, other._val+self._uni)
                return Field(self._domain, self._uni+other._uni)

        if np.isscalar(other):
            if self._uni is None:
                return Field(self._domain, self._val+other)
            return Field(self._domain, self._uni+other)
        if isinstance(other, (dobj.data_object, np.ndarray)):
            return Field(self._domain, self._val+other)
        return NotImplemented

    def __radd__(self, other):
        return self.__add__(other)

    def __sub__(self, other):
        # if other is a field, make sure that the domains match
        if isinstance(other, Field):
            if other._domain is not self._domain:
                raise ValueError("domains are incompatible.")
            if self._uni is None:
                if other._uni is None:
                    return Field(self._domain, self._val-other._val)
                if other._uni == 0:
                    return self
                return Field(self._domain, self._val-other._uni)
            else:
                if self._uni == 0:
                    return -other
                if other._uni is None:
                    return Field(self._domain, self._uni-other._val)
                return Field(self._domain, self._uni-other._uni)

        if np.isscalar(other):
            if self._uni is None:
                return Field(self._domain, self._val-other)
            return Field(self._domain, self._uni-other)
        if isinstance(other, (dobj.data_object, np.ndarray)):
            return Field(self._domain, self._val-other)
        return NotImplemented

    def __mul__(self, other):
        # if other is a field, make sure that the domains match
        if isinstance(other, Field):
            if other._domain is not self._domain:
                raise ValueError("domains are incompatible.")
            if self._uni is None:
                if other._uni is None:
                    return Field(self._domain, self._val*other._val)
                if other._uni == 1:
                    return self
                if other._uni == 0:
                    return other
                return Field(self._domain, self._val*other._uni)
            else:
                if self._uni == 1:
                    return other
                if self._uni == 0:
                    return self
                if other._uni is None:
                    return Field(self._domain, other._val*self._uni)
                return Field(self._domain, self._uni*other._uni)

        if np.isscalar(other):
            if self._uni is None:
                if other == 1:
                    return self
                if other == 0:
                    return Field(self._domain, other)
                return Field(self._domain, self._val*other)
            return Field(self._domain, self._uni*other)
        if isinstance(other, (dobj.data_object, np.ndarray)):
            return Field(self._domain, self._val*other)
        return NotImplemented


for op in ["__rsub__",
           "__rmul__",
726
727
728
729
           "__div__", "__rdiv__",
           "__truediv__", "__rtruediv__",
           "__floordiv__", "__rfloordiv__",
           "__pow__", "__rpow__",
730
731
732
           "__lt__", "__le__", "__gt__", "__ge__", "__eq__", "__ne__"]:
    def func(op):
        def func2(self, other):
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
733
734
            # if other is a field, make sure that the domains match
            if isinstance(other, Field):
735
                if other._domain is not self._domain:
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
736
                    raise ValueError("domains are incompatible.")
Martin Reinecke's avatar
Martin Reinecke committed
737
                tval = getattr(self._val, op)(other._val)
738
                return Field(self._domain, tval)
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
739

Martin Reinecke's avatar
fix    
Martin Reinecke committed
740
741
            if (np.isscalar(other) or
                    isinstance(other, (dobj.data_object, np.ndarray))):
Martin Reinecke's avatar
Martin Reinecke committed
742
                tval = getattr(self._val, op)(other)
743
                return Field(self._domain, tval)
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
744
745

            return NotImplemented
746
747
        return func2
    setattr(Field, op, func(op))
748
749
750
751
752
753
754
755
756

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
757
758
759
760

for f in ["sqrt", "exp", "log", "tanh"]:
    def func(f):
        def func2(self):
Martin Reinecke's avatar
Martin Reinecke committed
761
762
763
764
765
766
            if self._uni is None:
                fu = getattr(dobj, f)
                return Field(domain=self._domain, val=fu(self.val))
            else:
                fu = getattr(np, f)
                return Field(domain=self._domain, val=fu(self._uni))
Martin Reinecke's avatar
Martin Reinecke committed
767
768
        return func2
    setattr(Field, f, func(f))