Fields¶

The purpose of the field class is to represent discretized fields over a predefined space. Each field instance has three attributes val, domain and target, referencing the array of its values, the space instance over which it is defined and the space instance which serves as the codomain for transformations.

In this way, a field instance is not only a simple array of values, but is also carrying information about the geometry of its domain. Calling field methods invokes the appropriate methods of the respective space without any additional input from the user. The scalar product for instance, computed by field.dot(), weights the field values automatically with the correct volume factors and performs autonomously necessary basis transformations should the two fields be defined on different domains.

Furthermore, NIFTy overloads standard operations for fields in order to support a transparent implementation of algorithms. Thus, it is possible to combine field instances by plus, minus, times or divide operations and to apply trigonometric, exponential, and logarithmic functions componentwise to fields in their current domain.

Field class & operations¶

The field class¶

class nifty.field(domain, val=None, target=None, **kwargs)

Basic NIFTy class for fields.

Parameters : Other Parameters: domain : space The space wherein valid arguments live. val : {scalar, ndarray}, optional Defines field values, either to be given by a number interpreted as a constant array, or as an arbitrary array consistent with the space defined in domain or to be drawn from a random distribution controlled by kwargs. target : space, optional The space wherein the operator output lives (default: domain). random : string Indicates that the field values should be drawn from a certain distribution using a pseudo-random number generator. Supported distributions are: “pm1” (uniform distribution over {+1,-1} or {+1,+i,-1,-i} “gau” (normal distribution with zero-mean and a given standard deviation or variance) “syn” (synthesizes from a given power spectrum) “uni” (uniform distribution over [vmin,vmax[) dev : scalar Sets the standard deviation of the Gaussian distribution (default=1). var : scalar Sets the variance of the Gaussian distribution, outranking the dev parameter (default=1). spec : {scalar, list, array, field, function} Specifies a power spectrum from which the field values should be synthesized (default=1). Can be given as a constant, or as an array with indvidual entries per mode. log : bool Flag specifying if the spectral binning is performed on logarithmic scale or not; if set, the number of used bins is set automatically (if not given otherwise); by default no binning is done (default: None). nbin : integer Number of used spectral bins; if given log is set to False; integers below the minimum of 3 induce an automatic setting; by default no binning is done (default: None). binbounds : {list, array} User specific inner boundaries of the bins, which are preferred over the above parameters; by default no binning is done (default: None). vmin : scalar Sets the lower limit for the uniform distribution. vmax : scalar Sets the upper limit for the uniform distribution.

Attributes

 domain space The space wherein valid arguments live. val {scalar, ndarray}, optional Defines field values, either to be given by a number interpreted as a constant array, or as an arbitrary array consistent with the space defined in domain or to be drawn from a random distribution controlled by the keyword arguments. target space, optional The space wherein the operator output lives (default: domain).

Methods

 argmax([split]) Returns the index of the maximum field value. argmin([split]) Returns the index of the minimum field value. cast_domain(newdomain[, newtarget, force]) Casts the domain of the field. conjugate() Computes the complex conjugate of the field. dim([split]) Computes the (array) dimension of the underlying space. dot([x]) Computes the inner product of the field with a given object implying the correct volume factor needed to reflect the discretization of the continuous fields. hat() Translates the field into a diagonal operator. inverse_hat() Translates the inverted field into a diagonal operator. max([ignore]) Returns the maximum of the field values. mean(**kwargs) Returns the mean of the field values. med(**kwargs) Returns the median of the field values. min([ignore]) Returns the minimum of the field values. norm([q]) Computes the Lq-norm of the field values. plot(**kwargs) Plots the field values using matplotlib routines. power(**kwargs) Computes the power spectrum of the field values. pseudo_dot([x]) Computes the pseudo inner product of the field with a given object implying the correct volume factor needed to reflect the discretization of the continuous fields. set_target([newtarget]) Resets the codomain of the field. set_val(newval) Resets the field values. smooth([sigma, overwrite]) Smoothes the field by convolution with a Gaussian kernel. std(**kwargs) Returns the standard deviation of the field values. tensor_dot([x]) Computes the tensor product of a field defined on a arbitrary domain with a given object defined on another arbitrary domain. transform([target, overwrite]) Computes the transform of the field using the appropriate conjugate transformation. var(**kwargs) Returns the variance of the field values. weight([power, overwrite]) Returns the field values, weighted with the volume factors to a given power.
argmax(split=True, **kwargs)

Returns the index of the maximum field value.

Parameters : split : bool Whether to split (unravel) the flat index or not; does not apply to multiple indices along some axis (default: True). ind : {integer, tuple, array} Index of the maximum field value being an integer for one-dimensional fields, a tuple for multi-dimensional fields, and an array in case maxima along some axis are requested.

np.argmax, np.argmin

argmin(split=True, **kwargs)

Returns the index of the minimum field value.

Parameters : split : bool Whether to split (unravel) the flat index or not; does not apply to multiple indices along some axis (default: True). ind : {integer, tuple, array} Index of the minimum field value being an integer for one-dimensional fields, a tuple for multi-dimensional fields, and an array in case minima along some axis are requested.

np.argmax, np.argmin

cast_domain(newdomain, newtarget=None, force=True)

Casts the domain of the field.

Parameters : newdomain : space New space wherein the field should live. newtarget : space, optional Space wherein the transform of the field should live. When not given, target will automatically be the codomain of the newly casted domain (default=None). force : bool, optional Whether to force reshaping of the field if necessary or not (default=True) Nothing :
conjugate()

Computes the complex conjugate of the field.

Returns : cc : field The complex conjugated field.
dim(split=False)

Computes the (array) dimension of the underlying space.

Parameters : split : bool Sets the output to be either split up per axis or in form of total number of field entries in all dimensions (default=False) dim : {scalar, ndarray} Dimension of space.
dot(x=None)

Computes the inner product of the field with a given object implying the correct volume factor needed to reflect the discretization of the continuous fields.

Parameters : x : {scalar, ndarray, field}, optional The object with which the inner product is computed (default=None). dot : scalar The result of the inner product.
hat()

Translates the field into a diagonal operator.

Returns : D : operator The new diagonal operator instance.
inverse_hat()

Translates the inverted field into a diagonal operator.

Returns : D : operator The new diagonal operator instance.
max(ignore=False, **kwargs)

Returns the maximum of the field values.

Parameters : ignore : bool Whether to ignore NANs or not (default: False). amax : {scalar, ndarray} Maximum field value.

np.amax, np.nanmax

mean(**kwargs)

Returns the mean of the field values.

Returns : mean : scalar Mean field value.

np.mean

med(**kwargs)

Returns the median of the field values.

Returns : med : scalar Median field value.

np.median

min(ignore=False, **kwargs)

Returns the minimum of the field values.

Parameters : ignore : bool Whether to ignore NANs or not (default: False). amin : {scalar, ndarray} Minimum field value.

np.amin, np.nanmin

norm(q=None)

Computes the Lq-norm of the field values.

Parameters : q : scalar Parameter q of the Lq-norm (default: 2). norm : scalar The Lq-norm of the field values.
plot(**kwargs)

Plots the field values using matplotlib routines.

Other Parameters:

title : string

Title of the plot (default= “”).

vmin : scalar

Minimum value displayed (default=min(x)).

vmax : scalar

Maximum value displayed (default=max(x)).

power : bool

Whether to plot the power spectrum or the array (default=None).

unit : string

The unit of the field values (default=””).

norm : scalar

A normalization (default=None).

cmap : cmap

A color map (default=None).

cbar : bool

Whether to show the color bar or not (default=True).

other : {scalar, ndarray, field}

Object or tuple of objects to be added (default=None).

legend : bool

Whether to show the legend or not (default=False).

mono : bool

Whether to plot the monopol of the power spectrum or not (default=True).

save : string, optional

Valid file name where the figure is to be stored, by default the figure is not saved (default: False).

error : {scalar, ndarray, field}

object indicating some confidence intervall (default=None).

iter : scalar

Number of iterations (default: 0).

kindex : scalar

The spectral index per irreducible band (default=None).

log : bool, optional

Flag specifying if the spectral binning is performed on logarithmic scale or not; if set, the number of used bins is set automatically (if not given otherwise); by default no binning is done (default: None).

nbin : integer, optional

Number of used spectral bins; if given log is set to False; integers below the minimum of 3 induce an automatic setting; by default no binning is done (default: None).

binbounds : {list, array}, optional

User specific inner boundaries of the bins, which are preferred over the above parameters; by default no binning is done (default: None). vmin : {scalar, list, ndarray, field}, optional Lower limit of the uniform distribution if random == "uni" (default: 0).

Notes

The applicability of the keyword arguments depends on the respective space on which the field is defined. Confer to the corresponding get_plot() method.

power(**kwargs)

Computes the power spectrum of the field values.

Returns : Other Parameters: spec : ndarray Returns the power spectrum. pindex : ndarray, optional Specifies the indexing array for the distribution of indices in conjugate space (default: None). kindex : numpy.ndarray, optional Scale corresponding to each band in the power spectrum (default: None). rho : scalar Number of degrees of freedom per irreducible band (default=None). log : bool, optional Flag specifying if the spectral binning is performed on logarithmic scale or not; if set, the number of used bins is set automatically (if not given otherwise); by default no binning is done (default: None). nbin : integer, optional Number of used spectral bins; if given log is set to False; integers below the minimum of 3 induce an automatic setting; by default no binning is done (default: None). binbounds : {list, array}, optional User specific inner boundaries of the bins, which are preferred over the above parameters; by default no binning is done (default: None). vmin : {scalar, list, ndarray, field}, optional Lower limit of the uniform distribution if random == "uni" (default: 0). iter : scalar Number of iterations (default: 0)
pseudo_dot(x=1, **kwargs)

Computes the pseudo inner product of the field with a given object implying the correct volume factor needed to reflect the discretization of the continuous fields. This method specifically handles the inner products of fields defined over a nested_space.

Parameters : Returns : x : {scalar, ndarray, field}, optional The object with which the inner product is computed (default=None). pot : ndarray The result of the pseudo inner product. target : space, optional space wherein the transform of the output field should live (default: None).

Examples

Pseudo inner product of a field defined over a nested space with a simple field defined over a rg_space.

>>> from nifty import *
>>> space = rg_space(2)
>>> nspace = nested_space([space,space])
>>> nval = array([[1,2],[3,4]])
>>> nfield = nifty.field(domain = nspace, val = nval)
>>> val = array([1,1])
>>> nfield.pseudo_dot(x=val).val
array([ 1.5,  3.5])

set_target(newtarget=None)

Resets the codomain of the field.

Parameters : newtarget : space The new space wherein the transform of the field should live. (default=None).
set_val(newval)

Resets the field values.

Parameters : newval : {scalar, ndarray} New field values either as a constant or an arbitrary array.
smooth(sigma=0, overwrite=False, **kwargs)

Smoothes the field by convolution with a Gaussian kernel.

Parameters : Returns : sigma : scalar, optional standard deviation of the Gaussian kernel specified in units of length in position space (default: 0) overwrite : bool, optional Whether to overwrite the field or not (default: False). field : field, optional If overwrite is False, the transformed field is returned. Otherwise, nothing is returned. iter : scalar Number of iterations (default: 0)
std(**kwargs)

Returns the standard deviation of the field values.

Returns : std : scalar Standard deviation of the field values.

np.std

tensor_dot(x=None, **kwargs)

Computes the tensor product of a field defined on a arbitrary domain with a given object defined on another arbitrary domain.

Parameters : Returns : x : {scalar, ndarray, field}, optional The object with which the inner product is computed (default=None). tot : field The result of the tensor product, a field defined over a nested space. target : space, optional space wherein the transform of the output field should live (default: None).
transform(target=None, overwrite=False, **kwargs)

Computes the transform of the field using the appropriate conjugate transformation.

Parameters : Returns : target : space, optional Domain of the transform of the field (default:self.target) overwrite : bool, optional Whether to overwrite the field or not (default: False). field : field, optional If overwrite is False, the transformed field is returned. Otherwise, nothing is returned. iter : scalar Number of iterations (default: 0)
var(**kwargs)

Returns the variance of the field values.

Returns : var : scalar Variance of the field values.

np.var

weight(power=1, overwrite=False)

Returns the field values, weighted with the volume factors to a given power. The field values will optionally be overwritten.

Parameters : power : scalar, optional Specifies the optional power coefficient to which the field values are taken (default=1). overwrite : bool, optional Whether to overwrite the field values or not (default: False). field : field, optional If overwrite is False, the weighted field is returned. Otherwise, nothing is returned.

Field operations¶

NIFTy provides the user with a number of mathematical operations. These are basic operations, like trigonometrical functions, exponentials or square roots. For fields, they are calculated by overloading the respective numpy routines to NIFTy field instances