4.1.2. pde.fields.collection module

Defines a collection of fields to represent multiple fields defined on a common grid.

class FieldCollection(fields: Sequence[DataFieldBase], *, copy_fields: bool = False, label: str = None, labels: Optional[List[str]] = None, dtype=None)[source]

Bases: pde.fields.base.FieldBase

Collection of fields defined on the same grid

Note that all fields in the same collection must have the same data type. This might lead to upcasting, where for instance a combination of a real-valued and a complex-valued field will be both stored as complex fields.

Parameters
  • fields – Sequence of the individual fields

  • copy_fields (bool) – Flag determining whether the individual fields given in fields are copied. Note that fields are always copied if some of the supplied fields are identical.

  • label (str) – Label of the field collection

  • labels (list of str) – Labels of the individual fields. If omitted, the labels from the fields argument are used.

  • dtype (numpy dtype) – The data type of the field. All the numpy dtypes are supported. If omitted, it will be determined from data automatically.

assert_field_compatible(other: FieldBase, accept_scalar: bool = False)[source]

checks whether other is compatible with the current field

Parameters
  • other (FieldBase) – Other field this is compared to

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

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

property averages: List

averages of all fields

copy(*, label: str = None, dtype=None) FieldCollection[source]

return a copy of the data, but not of the grid

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.

property fields: List[pde.fields.base.DataFieldBase]

the fields of this collection

Type

list

classmethod from_scalar_expressions(grid: GridBase, expressions: Sequence[str], *, label: str = None, labels: Optional[Sequence[str]] = None, dtype=None) FieldCollection[source]

create a field collection on a grid from given expressions

Warning

This implementation uses exec() and should therefore not be used in a context where malicious input could occur.

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

  • expressions (list of str) – A list of mathematical expression, one for each field in the collection. The expressions determine the values as a function of the position on the grid. The expressions may contain standard mathematical functions and they may depend on the axes labels of the grid. More information can be found in the expression documentation.

  • label (str, optional) – Name of the whole collection

  • labels (list of str, optional) – Names of the individual fields

  • dtype (numpy dtype) – The data type of the field. All the numpy dtypes are supported. If omitted, it will be determined from data automatically.

classmethod from_state(attributes: dict, data: numpy.ndarray = None) FieldCollection[source]

create a field collection from given state.

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

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

get_image_data(index: int = 0, **kwargs) dict[source]

return data for plotting an image of the field

Parameters
  • index (int) – Index of the field whose data is returned

  • **kwargs – Arguments forwarded to the get_image_data method

Returns

Information useful for plotting an image of the field

Return type

dict

get_line_data(index: int = 0, scalar: str = 'auto', extract: str = 'auto') dict[source]

return data for a line plot of the field

Parameters
  • index (int) – Index of the field whose data is returned

  • 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 integrals: List

integrals of all fields

interpolate_to_grid(grid: GridBase, *, backend: str = 'numba', method: str = 'linear', fill: Optional[Number] = None, label: str = None) FieldCollection[source]

interpolate the data of this field collection to another grid.

Parameters
  • grid (GridBase) – The grid of the new field onto which the current field is interpolated.

  • backend (str) – The accepted values “scipy” and “numba” determine the backend that is used for the interpolation.

  • method (str) – Determines the method being used for interpolation. Typical values that are “nearest” and “linear”, but the supported values depend on the chosen backend.

  • fill (Number, optional) – Determines how values out of bounds are handled. If None, a ValueError is raised when out-of-bounds points are requested. Otherwise, the given value is returned.

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

Returns

Interpolated data

Return type

FieldCollection

property labels: _FieldLabels

the labels of all fields

Note

The attribute returns a special class _FieldLabels to allow specific manipulations of the field labels. The returned object behaves much like a list, but assigning values will modify the labels of the fields in the collection.

Type

_FieldLabels

property magnitudes: numpy.ndarray

scalar magnitudes of all fields

Type

ndarray

plot(kind: Union[str, Sequence[str]] = 'auto', resize_fig=None, figsize='auto', arrangement='horizontal', subplot_args=None, *args, title: str = None, constrained_layout: bool = True, filename: str = None, action: str = 'auto', fig_style: dict = None, fig=None, **kwargs) List[PlotReference][source]

visualize all the fields in the collection

Parameters
  • kind (str or list of str) – Determines the kind of the visualizations. Supported values are image, line, vector, or interactive. Alternatively, auto determines the best visualization based on each field itself. Instead of a single value for all fields, a list with individual values can be given.

  • resize_fig (bool) – Whether to resize the figure to adjust to the number of panels

  • figsize (str or tuple of numbers) – Determines the figure size. The figure size is unchanged if the string default is passed. Conversely, the size is adjusted automatically when auto is passed. Finally, a specific figure size can be specified using two values, using matplotlib.figure.Figure.set_size_inches().

  • arrangement (str) – Determines how the subpanels will be arranged. The default value horizontal places all subplots next to each other. The alternative value vertical puts them below each other.

  • title (str) – Title of the plot. If omitted, the title might be chosen automatically. This is shown above all panels.

  • constrained_layout (bool) – Whether to use constrained_layout in matplotlib.pyplot.figure() call to create a figure. This affects the layout of all plot elements. Generally, spacing might be better with this flag enabled, but it can also lead to problems when plotting multiple plots successively, e.g., when creating a movie.

  • filename (str, optional) – If given, the figure is written to the specified file.

  • action (str) – Decides what to do with the final figure. If the argument is set to show, matplotlib.pyplot.show() will be called to show the plot. If the value is none, the figure will be created, but not necessarily shown. The value close closes the figure, after saving it to a file when filename is given. The default value auto implies that the plot is shown if it is not a nested plot call.

  • fig_style (dict) – Dictionary with properties that will be changed on the figure after the plot has been drawn by calling matplotlib.pyplot.setp(). For instance, using fig_style={‘dpi’: 200} increases the resolution of the figure.

  • fig (matplotlib.figures.Figure) – Figure that is used for plotting. If omitted, a new figure is created.

  • subplot_args (list) – Additional arguments for the specific subplots. Should be a list with a dictionary of arguments for each subplot. Supplying an empty dict allows to keep the default setting of specific subplots.

  • **kwargs – All additional keyword arguments are forwarded to the actual plotting function of all subplots.

Returns

Instances that contain information to update all the plots with new data later.

Return type

List of PlotReference

classmethod scalar_random_uniform(num_fields: int, grid: GridBase, vmin: float = 0, vmax: float = 1, *, label: str = None, labels: Optional[Sequence[str]] = None) FieldCollection[source]

create scalar fields with random values between vmin and vmax

Parameters
  • num_fields (int) – The number of fields to create

  • grid (GridBase) – Grid defining the space on which the fields are defined

  • vmin (float) – Lower bound. Can be complex to create complex fields

  • vmax (float) – Upper bound. Can be complex to create complex fields

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

  • labels (list of str, optional) – Names of the individual fields

smooth(sigma: float = 1, *, out: Optional[FieldCollection] = None, label: str = None) FieldCollection[source]

applies Gaussian smoothing with the given standard deviation

This function respects periodic boundary conditions of the underlying grid, using reflection when no periodicity is specified.

sigma (float):

Gives the standard deviation of the smoothing in real length units (default: 1)

out (FieldCollection, optional):

Optional field into which the smoothed data is stored

label (str, optional):

Name of the returned field

Returns

Field collection with smoothed data, stored at out if given.

classmethod unserialize_attributes(attributes: Dict[str, str]) dict[source]

unserializes the given attributes

Parameters

attributes (dict) – The serialized attributes

Returns

The unserialized attributes

Return type

dict