field.py 22 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
#
14
# Copyright(C) 2013-2019 Max-Planck-Society
Theo Steininger's avatar
Theo Steininger committed
15
#
16
# NIFTy is being developed at the Max-Planck-Institut fuer Astrophysik.
17

Martin Reinecke's avatar
Martin Reinecke committed
18
from functools import reduce
csongor's avatar
csongor committed
19
import numpy as np
20
21

from . import dobj, utilities
Martin Reinecke's avatar
Martin Reinecke committed
22
from .domain_tuple import DomainTuple
23

24

Martin Reinecke's avatar
Martin Reinecke committed
25
class Field(object):
Martin Reinecke's avatar
Martin Reinecke committed
26
27
    _scalar_dom = DomainTuple.scalar_domain()

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
    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
51
        if type(val) is not dobj.data_object:
Martin Reinecke's avatar
Martin Reinecke committed
52
            if np.isscalar(val):
Martin Reinecke's avatar
Martin Reinecke committed
53
                val = dobj.full(domain.shape, val)
Martin Reinecke's avatar
Martin Reinecke committed
54
55
            else:
                raise TypeError("val must be of type dobj.data_object")
56
        if domain.shape != val.shape:
Martin Reinecke's avatar
Martin Reinecke committed
57
            raise ValueError("shape mismatch between val and domain")
58
59
        self._domain = domain
        self._val = val
60
        dobj.lock(self._val)
Martin Reinecke's avatar
Martin Reinecke committed
61

Martin Reinecke's avatar
Martin Reinecke committed
62
63
64
65
    @staticmethod
    def scalar(val):
        return Field(Field._scalar_dom, val)

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

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

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

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

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

131
132
133
134
135
136
137
138
139
140
    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
141
142
    @property
    def local_data(self):
Martin Reinecke's avatar
Martin Reinecke committed
143
144
145
146
147
        """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
148
149
        return dobj.local_data(self._val)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

325
        return Field.from_local_data(self._domain, aout)
csongor's avatar
csongor committed
326

327
328
329
330
331
332
333
334
335
    def outer(self, x):
        """ Computes the outer product of 'self' with x.

        Parameters
        ----------
        x : Field

        Returns
        ----------
Philipp Arras's avatar
Philipp Arras committed
336
        Field, defined on the product space of self.domain and x.domain
337
338
339
340
341
342
343
        """
        if not isinstance(x, Field):
            raise TypeError("The multiplier must be an instance of " +
                            "the NIFTy field class")
        from .operators.outer_product_operator import OuterProduct
        return OuterProduct(self, x.domain)(x)

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

347
348
349
        Parameters
        ----------
        x : Field
Philipp Arras's avatar
Philipp Arras committed
350
            x must be defined on the same domain as `self`.
Theo Steininger's avatar
Theo Steininger committed
351

Martin Reinecke's avatar
Martin Reinecke committed
352
        spaces : None, int or tuple of int (default: None)
353
354
            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
355

356
357
        Returns
        -------
Martin Reinecke's avatar
Martin Reinecke committed
358
        float, complex, either scalar (for full dot products)
359
                              or Field (for partial dot products)
360
        """
361
        if not isinstance(x, Field):
362
363
            raise TypeError("The dot-partner must be an instance of " +
                            "the NIFTy field class")
Theo Steininger's avatar
Theo Steininger committed
364

Martin Reinecke's avatar
Martin Reinecke committed
365
        if x._domain != self._domain:
366
            raise ValueError("Domain mismatch")
Theo Steininger's avatar
Theo Steininger committed
367

Martin Reinecke's avatar
Martin Reinecke committed
368
        ndom = len(self._domain)
369
370
371
        spaces = utilities.parse_spaces(spaces, ndom)

        if len(spaces) == ndom:
Martin Reinecke's avatar
Martin Reinecke committed
372
            return dobj.vdot(self._val, x._val)
373
374
        # 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
375
        return (self.conjugate()*x).sum(spaces=spaces)
Theo Steininger's avatar
Theo Steininger committed
376

Martin Reinecke's avatar
Martin Reinecke committed
377
    def norm(self, ord=2):
Martin Reinecke's avatar
tweaks    
Martin Reinecke committed
378
        """ Computes the L2-norm of the field values.
csongor's avatar
csongor committed
379

Martin Reinecke's avatar
Martin Reinecke committed
380
381
382
383
        Parameters
        ----------
        ord : int, default=2
            accepted values: 1, 2, ..., np.inf
384
385
386
387

        Returns
        -------
        float
Martin Reinecke's avatar
Martin Reinecke committed
388
            The L2-norm of the field values.
389
        """
Martin Reinecke's avatar
Martin Reinecke committed
390
        return dobj.norm(self._val, ord)
391

Martin Reinecke's avatar
tweaks    
Martin Reinecke committed
392
    def conjugate(self):
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
393
        """ Returns the complex conjugate of the field.
Theo Steininger's avatar
Theo Steininger committed
394

395
396
        Returns
        -------
Martin Reinecke's avatar
Martin Reinecke committed
397
398
        Field
            The complex conjugated field.
csongor's avatar
csongor committed
399
        """
Martin Reinecke's avatar
Martin Reinecke committed
400
        if utilities.iscomplextype(self._val.dtype):
Martin Reinecke's avatar
Martin Reinecke committed
401
402
            return Field(self._domain, self._val.conjugate())
        return self
csongor's avatar
csongor committed
403

Theo Steininger's avatar
Theo Steininger committed
404
    # ---General unary/contraction methods---
405

Theo Steininger's avatar
Theo Steininger committed
406
    def __pos__(self):
407
        return self
408

Theo Steininger's avatar
Theo Steininger committed
409
    def __neg__(self):
Martin Reinecke's avatar
Martin Reinecke committed
410
        return Field(self._domain, -self._val)
csongor's avatar
csongor committed
411

Theo Steininger's avatar
Theo Steininger committed
412
    def __abs__(self):
Martin Reinecke's avatar
Martin Reinecke committed
413
        return Field(self._domain, abs(self._val))
csongor's avatar
csongor committed
414

415
    def _contraction_helper(self, op, spaces):
Theo Steininger's avatar
Theo Steininger committed
416
        if spaces is None:
Martin Reinecke's avatar
Martin Reinecke committed
417
            return getattr(self._val, op)()
418

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

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

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

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

Theo Steininger's avatar
Theo Steininger committed
429
430
431
        # 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
432
        else:
Martin Reinecke's avatar
Martin Reinecke committed
433
            return_domain = tuple(dom
Martin Reinecke's avatar
Martin Reinecke committed
434
                                  for i, dom in enumerate(self._domain)
Theo Steininger's avatar
Theo Steininger committed
435
                                  if i not in spaces)
436

437
            return Field(DomainTuple.make(return_domain), data)
csongor's avatar
csongor committed
438

439
    def sum(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
440
441
442
443
444
445
446
447
448
449
450
451
452
453
        """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.
        """
454
        return self._contraction_helper('sum', spaces)
csongor's avatar
csongor committed
455

456
    def integrate(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
        """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
474
475
476
        swgt = self.scalar_weight(spaces)
        if swgt is not None:
            res = self.sum(spaces)
Martin Reinecke's avatar
fixes    
Martin Reinecke committed
477
            res = res*swgt
Martin Reinecke's avatar
Martin Reinecke committed
478
            return res
479
480
481
        tmp = self.weight(1, spaces=spaces)
        return tmp.sum(spaces)

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

499
500
    def all(self, spaces=None):
        return self._contraction_helper('all', spaces)
csongor's avatar
csongor committed
501

502
503
    def any(self, spaces=None):
        return self._contraction_helper('any', spaces)
csongor's avatar
csongor committed
504

505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
#     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
538

539
    def mean(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
        """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.
        """
557
558
        if self.scalar_weight(spaces) is not None:
            return self._contraction_helper('mean', spaces)
Martin Reinecke's avatar
Martin Reinecke committed
559
        # MR FIXME: not very efficient
560
561
        # MR FIXME: do we need "spaces" here?
        tmp = self.weight(1, spaces)
Martin Reinecke's avatar
Martin Reinecke committed
562
        return tmp.sum(spaces)*(1./tmp.total_volume(spaces))
csongor's avatar
csongor committed
563

564
    def var(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
565
566
567
568
569
570
571
572
573
574
575
576
577
578
        """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.
        """
579
580
        if self.scalar_weight(spaces) is not None:
            return self._contraction_helper('var', spaces)
Martin Reinecke's avatar
Martin Reinecke committed
581
582
        # MR FIXME: not very efficient or accurate
        m1 = self.mean(spaces)
Martin Reinecke's avatar
Martin Reinecke committed
583
        if utilities.iscomplextype(self.dtype):
584
            sq = abs(self-m1)**2
Martin Reinecke's avatar
Martin Reinecke committed
585
        else:
586
587
            sq = (self-m1)**2
        return sq.mean(spaces)
csongor's avatar
csongor committed
588

589
    def std(self, spaces=None):
Martin Reinecke's avatar
Martin Reinecke committed
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
        """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.
        """
607
        from .sugar import sqrt
608
609
610
        if self.scalar_weight(spaces) is not None:
            return self._contraction_helper('std', spaces)
        return sqrt(self.var(spaces))
csongor's avatar
csongor committed
611

Theo Steininger's avatar
Theo Steininger committed
612
    def __repr__(self):
Philipp Arras's avatar
Philipp Arras committed
613
        return "<nifty5.Field>"
Theo Steininger's avatar
Theo Steininger committed
614
615

    def __str__(self):
Philipp Arras's avatar
Philipp Arras committed
616
        return "nifty5.Field instance\n- domain      = " + \
617
               self._domain.__str__() + \
Martin Reinecke's avatar
Martin Reinecke committed
618
               "\n- val         = " + repr(self._val)
Martin Reinecke's avatar
cleanup    
Martin Reinecke committed
619

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

    def unite(self, other):
Martin Reinecke's avatar
Martin Reinecke committed
626
627
628
629
        return self+other

    def flexible_addsub(self, other, neg):
        return self-other if neg else self+other
630

631
    def sigmoid(self):
Martin Reinecke's avatar
Martin Reinecke committed
632
633
        return 0.5*(1.+self.tanh())

Martin Reinecke's avatar
Martin Reinecke committed
634
635
    def clip(self, min=None, max=None):
        return Field(self._domain, dobj.clip(self._val, min, max))
636
637
638
639

    def one_over(self):
        return 1/self

Martin Reinecke's avatar
Martin Reinecke committed
640
641
642
643
    def _binary_op(self, other, op):
        # if other is a field, make sure that the domains match
        f = getattr(self._val, op)
        if isinstance(other, Field):
Martin Reinecke's avatar
Martin Reinecke committed
644
            if other._domain != self._domain:
Martin Reinecke's avatar
Martin Reinecke committed
645
646
647
648
649
                raise ValueError("domains are incompatible.")
            return Field(self._domain, f(other._val))
        if np.isscalar(other):
            return Field(self._domain, f(other))
        return NotImplemented
Martin Reinecke's avatar
Martin Reinecke committed
650

Martin Reinecke's avatar
Martin Reinecke committed
651

Martin Reinecke's avatar
Martin Reinecke committed
652
653
654
for op in ["__add__", "__radd__",
           "__sub__", "__rsub__",
           "__mul__", "__rmul__",
655
656
657
658
           "__div__", "__rdiv__",
           "__truediv__", "__rtruediv__",
           "__floordiv__", "__rfloordiv__",
           "__pow__", "__rpow__",
659
660
661
           "__lt__", "__le__", "__gt__", "__ge__", "__eq__", "__ne__"]:
    def func(op):
        def func2(self, other):
Martin Reinecke's avatar
Martin Reinecke committed
662
            return self._binary_op(other, op)
663
664
        return func2
    setattr(Field, op, func(op))
665
666
667
668
669
670
671
672
673

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
674

675
676
677
for f in ["sqrt", "exp", "log", "tanh",
          "sin", "cos", "tan", "cosh", "sinh",
          "absolute", "sinc", "sign"]:
Martin Reinecke's avatar
Martin Reinecke committed
678
679
    def func(f):
        def func2(self):
Martin Reinecke's avatar
Martin Reinecke committed
680
            return Field(self._domain, getattr(dobj, f)(self.val))
Martin Reinecke's avatar
Martin Reinecke committed
681
682
        return func2
    setattr(Field, f, func(f))