4.1.1 pde.fields.base module

Defines base class of fields or collections, which are discretized on grids.

class FieldBase(grid, data, *, label=None)[source]

Bases: object

Abstract base class for describing (discretized) fields.

Parameters:
  • grid (GridBase) – Grid defining the space on which this field is defined

  • data (ndarray, optional) – Field values at the support points of the grid and the ghost cells

  • label (str, optional) – Name of the field

apply(func, out=None, *, label=None, evaluate_args=None)[source]

Applies a function/expression to the data and returns it as a field.

Parameters:
  • func (callable or str) – The (vectorized) function being applied to the data or an expression that can be parsed using sympy (evaluate() is used in this case). The local field values can be accessed using the field labels for a field collection and via the variable c otherwise.

  • out (FieldBase, optional) – Optional field into which the data is written

  • label (str, optional) – Name of the returned field

  • evaluate_args (dict) – Additional arguments passed to evaluate(). Only used when func is a string.

  • self (TField)

Returns:

Field with new data. Identical to out if given.

Return type:

FieldBase

assert_field_compatible(other, accept_scalar=False)[source]

Checks whether other is compatible with the current field.

Parameters:
  • other (FieldBase) – The other field this one is compared to

  • accept_scalar (bool, optional) – Determines whether it is acceptable that other is an instance of ScalarField.

Return type:

None

property attributes: dict[str, Any]

describes the state of the instance (without the data)

Type:

dict

property attributes_serialized: dict[str, str]

serialized version of the attributes

Type:

dict

conjugate()[source]

Returns complex conjugate of the field.

Returns:

the complex conjugated field

Return type:

FieldBase

Parameters:

self (TField)

abstract copy(*, label=None, dtype=None)[source]

Return a new field with the data (but not the grid) copied.

Parameters:
  • label (str, optional) – Name of the returned field

  • dtype (numpy dtype) – The data type of the field. If omitted, it will be determined from data automatically or the dtype of the current field is used.

  • self (TField)

Returns:

A copy of the current field

Return type:

DataFieldBase

property data: ndarray

discretized data at the support points.

Type:

ndarray

property dtype: dtype[Any] | None | type[Any] | _SupportsDType[dtype[Any]] | str | tuple[Any, int] | tuple[Any, SupportsIndex | Sequence[SupportsIndex]] | list[Any] | _DTypeDict | tuple[Any, Any]

the numpy dtype of the underlying data.

Type:

DTypeLike

classmethod from_file(filename)[source]

Create field from data stored in a file.

Field can be written to a file using FieldBase.to_file().

Example

Write a field to a file and then read it back:

field = pde.ScalarField(...)
field.write_to("test.hdf5")

field_copy = pde.FieldBase.from_file("test.hdf5")
Parameters:

filename (str) – Path to the file being read

Returns:

The field with the appropriate sub-class

Return type:

FieldBase

classmethod from_state(attributes, data=None)[source]

Create a field from given state.

Parameters:
  • attributes (dict) – The attributes that describe the current instance

  • data (ndarray, optional) – Data values at the support points of the grid defining the field

Returns:

The field created from the state

Return type:

FieldBase

abstract get_image_data()[source]

Return data for plotting an image of the field.

Parameters:
  • scalar (str or int) – The method for extracting scalars as described in DataFieldBase.to_scalar().

  • transpose (bool) – Determines whether the transpose of the data should is plotted

  • **kwargs – Additional parameters are forwarded to grid.get_image_data

Returns:

Information useful for plotting an image of the field

Return type:

dict

abstract get_line_data(scalar='auto', extract='auto')[source]

Return data for a line plot of the field.

Parameters:
  • scalar (str or int) – The method for extracting scalars as described in DataFieldBase.to_scalar().

  • extract (str) – The method used for extracting the line data. See the docstring of the grid method get_line_data to find supported values.

Returns:

Information useful for performing a line plot of the field

Return type:

dict

property grid: GridBase

The grid on which the field is defined.

Type:

base,GridBase

property imag: TField

Imaginary part of the field.

Type:

FieldBase

property is_complex: bool

whether the field contains real or complex data

Type:

bool

property label: str | None

the name of the field

Type:

str

abstract plot(*args, **kwargs)[source]

Visualize the field.

plot_interactive(viewer_args=None, **kwargs)[source]

Create an interactive plot of the field using napari

For a detailed description of the launched program, see the napari webpage.

Parameters:
  • viewer_args (dict) – Arguments passed to napari.viewer.Viewer to affect the viewer.

  • **kwargs – Extra arguments passed to the plotting function

Return type:

None

property real: TField

Real part of the field.

Type:

FieldBase

split_mpi(decomposition='auto')[source]

Splits the field onto subgrids in an MPI run.

In a normal serial simulation, the method simply returns the field itself. In contrast, in an MPI simulation, the field provided on the main node is split onto all nodes using the given decomposition. The field data provided on all other nodes is not used.

Parameters:
  • decomposition (list of ints) – Number of subdivision in each direction. Should be a list of length grid.num_axes specifying the number of nodes for this axis. If one value is -1, its value will be determined from the number of available nodes. The default value auto tries to determine an optimal decomposition by minimizing communication between nodes.

  • self (TField)

Returns:

The part of the field that corresponds to the subgrid associated with the current MPI node.

Return type:

FieldBase

to_file(filename, **kwargs)[source]

Store field in a file.

The extension of the filename determines what format is being used. If it ends in .h5 or .hdf, the Hierarchical Data Format is used. The other supported format are images, where only the most typical formats are supported.

To load the field back from the file, you may use FieldBase.from_file().

Example

Write a field to a file and then read it back:

field = pde.ScalarField(...)
field.write_to("test.hdf5")

field_copy = pde.FieldBase.from_file("test.hdf5")
Parameters:
  • filename (str) – Path where the data is stored

  • **kwargs – Additional parameters may be supported for some formats

Return type:

None

classmethod unserialize_attributes(attributes)[source]

Unserializes the given attributes.

Parameters:

attributes (dict) – The serialized attributes

Returns:

The unserialized attributes

Return type:

dict

property writeable: bool

whether the field data can be changed or not

Type:

bool

exception RankError[source]

Bases: TypeError

Error indicating that the field has the wrong rank.