field.py 21.7 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 52
    def __init__(self, domain, val):
        if not isinstance(domain, DomainTuple):
            raise TypeError("domain must be of type DomainTuple")
        if not isinstance(val, dobj.data_object):
Martin Reinecke's avatar
Martin Reinecke committed
53 54 55 56
            if np.isscalar(val):
                val = dobj.from_local_data((), np.full((), val))
            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 91
        if not (np.isreal(val) or np.iscomplex(val)):
            raise TypeError("need arithmetic scalar")
        domain = DomainTuple.make(domain)
        return Field(domain, dobj.full(domain.shape, fill_value=val))
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 126 127 128 129 130
        """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.
        """
131 132
        return dobj.to_global_data(self._val)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

379 380
        Returns
        -------
Martin Reinecke's avatar
Martin Reinecke committed
381 382
        Field
            The complex conjugated field.
csongor's avatar
csongor committed
383
        """
Martin Reinecke's avatar
Martin Reinecke committed
384
        return Field(self._domain, self._val.conjugate())
csongor's avatar
csongor committed
385

Theo Steininger's avatar
Theo Steininger committed
386
    # ---General unary/contraction methods---
387

Theo Steininger's avatar
Theo Steininger committed
388
    def __pos__(self):
389
        return self
390

Theo Steininger's avatar
Theo Steininger committed
391
    def __neg__(self):
Martin Reinecke's avatar
Martin Reinecke committed
392
        return Field(self._domain, -self._val)
csongor's avatar
csongor committed
393

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

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

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

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

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

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

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

419
            return Field(DomainTuple.make(return_domain), data)
csongor's avatar
csongor committed
420

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

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

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

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

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

487 488 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
#     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
520

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

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

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

Theo Steininger's avatar
Theo Steininger committed
594
    def __repr__(self):
Philipp Arras's avatar
Philipp Arras committed
595
        return "<nifty5.Field>"
Theo Steininger's avatar
Theo Steininger committed
596 597

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

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

Martin Reinecke's avatar
more  
Martin Reinecke committed
613 614 615 616 617 618 619
    def extract(self, dom):
        if dom is not self._domain:
            raise ValueError("domain mismatch")
        return self

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

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

Martin Reinecke's avatar
fix  
Martin Reinecke committed
638 639
            if (np.isscalar(other) or
                    isinstance(other, (dobj.data_object, np.ndarray))):
Martin Reinecke's avatar
Martin Reinecke committed
640
                tval = getattr(self._val, op)(other)
641
                return Field(self._domain, tval)
Martin Reinecke's avatar
cleanup  
Martin Reinecke committed
642 643

            return NotImplemented
644 645
        return func2
    setattr(Field, op, func(op))
646 647 648 649 650 651 652 653 654

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
655 656 657 658 659 660 661 662

for f in ["sqrt", "exp", "log", "tanh"]:
    def func(f):
        def func2(self):
            fu = getattr(dobj, f)
            return Field(domain=self._domain, val=fu(self.val))
        return func2
    setattr(Field, f, func(f))