nifty.cl.field module#

class Field(domain, val)[source]#

Bases: Operator

The discrete representation of a continuous field over multiple spaces.

Stores data arrays and carries all the needed meta-information (i.e. the domain) for operators to be able to operate on them.

Parameters:

domain (DomainTuple) – The domain of the new Field.
val (AnyArray and all allowed wrappees of AnyArray (e.g. np.ndarray, cupy.ndarray, scalars)) – This object’s shape must match the domain shape After construction, the object will no longer be writeable!

Notes

If possible, do not invoke the constructor directly, but use one of the many convenience functions for instantiation!

__init__(domain, val)[source]#

__repr__()[source]#: Return repr(self).

__str__()[source]#: Return str(self).

all(spaces=None)[source]#

any(spaces=None)[source]#

asnumpy()[source]#: np.ndarray : the array storing the field’s entries.

Notes

The returned array is read-only.

asnumpy_rw()[source]#: np.ndarray : a copy of the array storing the field’s entries.

astype(dtype)[source]#

at(device_id, *, check_fail=True)[source]#

Field : a Field stored on a potentially different devicethe array storing the field’s entries.

Parameters:: device_id (int or dict) – The device on which the Field shall be allocated. -1 corresponds to host (cpu), 0 is the first device (gpu), 1 the second and so on. Default: -1.

broadcast(index, space)[source]#

cast_domain(new_domain)[source]#

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 defined on new_domain, but with the same data as self.
Return type:: Field

conjugate()[source]#

Returns the complex conjugate of the field.

Returns:: The complex conjugated field.
Return type:: Field

property device_id#

property domain#

the field’s domain

Type:: DomainTuple

property dtype#

the data type of the field’s entries

Type:: type

extract(dom)[source]#

extract_part(dom)[source]#

flexible_addsub(other, neg)[source]#

static from_random(domain, random_type='normal', dtype=<class 'numpy.float64'>, device_id=-1, **kwargs)[source]#

Draws a random field with the given parameters.

Parameters:

random_type ('pm1', 'normal', or 'uniform') – The random distribution to use.
domain (DomainTuple) – The domain of the output random Field.
dtype (type) – The datatype of the output random Field. If the datatype is complex, each real and imaginary part have variance 1
device_id (int) – Device id on which the Field shall be located. Note that Fields are always generated on the host and then potentially transferred to device. Default: -1

Returns:

The newly created Field.

Return type:

Field

static from_raw(domain, arr)[source]#

Returns a Field constructed from domain and arr.

Parameters:

domain (DomainTuple, tuple of Domain, or Domain) – The domain of the new Field.
arr (AnyArray) – The data content to be used for the new Field. Its shape must match the shape of domain.

static full(domain, val, device_id=-1)[source]#

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.
device_id (int) – The device on which the Field shall be allocated. -1 corresponds to host (cpu), 0 is the first device (gpu), 1 the second and so on. Default: -1.

Returns:

The newly created Field.

Return type:

Field

property imag#

The imaginary part of the field

Type:: Field

integrate(spaces=None)[source]#

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) – The summation is only carried out over the sub-domains in this tuple. If None, it is carried out over all sub-domains.
Returns:: The result of the integration.
Return type:: Field

map(func)[source]#: Applies a function directly on AnyArray-level.

Note

The result of the function needs to have the same shape as the original Field.

mean(spaces=None)[source]#

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) – The operation is only carried out over the sub-domains in this tuple. If None, it is carried out over all sub-domains.
Returns:: The result of the operation.
Return type:: Field

norm(ord=2)[source]#

Computes the L2-norm of the field values.

Parameters:: ord (int) – Accepted values: 1, 2, …, np.inf. Default: 2.
Returns:: The L2-norm of the field values.
Return type:: float

outer(x)[source]#

Computes the outer product of ‘self’ with x.

Parameters:: x (nifty.cl.field.Field)
Returns:: Defined on the product space of self.domain and x.domain.
Return type:: Field

prod(spaces=None)[source]#

Computes the product over the sub-domains given by spaces.

Parameters:: spaces (None, int or tuple of int) – The operation is only carried out over the sub-domains in this tuple. If None, it is carried out over all sub-domains. Default: None.
Returns:: The result of the product.
Return type:: Field

ptw(op, *args, **kwargs)[source]#

ptw_with_deriv(op, *args, **kwargs)[source]#

property raw#

the raw array (numpy.ndarray or cupy.ndarray) storing the field’s entries.

Notes

The returned array is read-only.

Type:: ndarray

property real#

The real part of the field

Type:: Field

s_all()[source]#

s_any()[source]#

s_integrate()[source]#

Integrates over the Field.

Integration is performed by summing over self multiplied by its volume factors.

Returns:: The result of the integration.
Return type:: Scalar

s_mean()[source]#

Determines the field mean

x.s_mean() is equivalent to x.s_integrate()/x.total_volume().

Returns:: The result of the operation.
Return type:: scalar

s_prod()[source]#

s_std()[source]#

Determines the standard deviation of the Field.

x.s_std() is equivalent to sqrt(x.s_var()).

Returns:: The result of the operation.
Return type:: scalar

s_sum()[source]#

Returns the sum over all entries

Returns:: The result of the summation.
Return type:: scalar

s_var()[source]#

Determines the field variance

Returns:: The result of the operation.
Return type:: scalar

s_vdot(x)[source]#

Computes the dot product of ‘self’ with x.

Parameters:: x (nifty.cl.field.Field) – x must be defined on the same domain as self.
Returns:: The dot product
Return type:: float or complex

static scalar(val, device_id=-1)[source]#

scalar_weight(spaces=None)[source]#

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:: If the requested sub-domain has a uniform volume element, it is returned. Otherwise, None is returned.
Return type:: float or None

scale(factor)[source]#

property shape#

the concatenated shapes of all sub-domains

Type:: tuple of int

property size#

total number of pixels in the field

Type:: int

squeeze(aggressive=False)[source]#

Squeezes the Field.

Look at SqueezeOperator for further information.

std(spaces=None)[source]#

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) – The operation is only carried out over the sub-domains in this tuple. If None, it is carried out over all sub-domains. Default: None.
Returns:: The result of the operation.
Return type:: Field

sum(spaces=None)[source]#

Sums up over the sub-domains given by spaces.

Parameters:: spaces (None, int or tuple of int) – The summation is only carried out over the sub-domains in this tuple. If None, it is carried out over all sub-domains.
Returns:: The result of the summation.
Return type:: Field

total_volume(spaces=None)[source]#

Returns the total volume of the field’s domain or of a subspace of it.

Parameters:: spaces (int, tuple of int or None) – Indices of the sub-domains of the field’s domain to be considered. If None, the total volume of the whole domain is returned.
Returns:: the total volume of the requested (sub-)domain.
Return type:: float

unite(other)[source]#

property val#

the array storing the field’s entries.

Notes

The returned array is read-only.

Type:: AnyArray

val_rw()[source]#: AnyArray : a copy of the array storing the field’s entries.

var(spaces=None)[source]#

Determines the variance over the sub-domains given by spaces.

Parameters:: spaces (None, int or tuple of int) – The operation is only carried out over the sub-domains in this tuple. If None, it is carried out over all sub-domains. Default: None.
Returns:: The result of the operation.
Return type:: Field

vdot(x, spaces=None)[source]#

Computes the dot product of ‘self’ with x.

Parameters:

x (nifty.cl.field.Field) – x must be defined on the same domain as self.
spaces (None, int or tuple of int) – The dot product is only carried out over the sub-domains in this tuple. If None, it is carried out over all sub-domains. Default: None.

Return type:

float, complex, either scalar (for full dot products) or Field (for partial dot products).

weight(power=1, spaces=None)[source]#

Weights the pixels of self with their invidual pixel volumes.

Parameters:

power (number) – The pixel values get multiplied with their volume-factor**power.
spaces (None, int or tuple of int) – Determines on which sub-domain the operation takes place. If None, the entire domain is used.

Returns:

The weighted field on the same device as self.

Return type:

Field

func(op)[source]#