4.1.2 pde.fields.collection module

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

class FieldCollection(fields, *, copy_fields=False, label=None, labels=None, dtype=None)[source]

Bases: FieldBase

Collection of fields defined on the same grid

Note

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

Parameters:
  • fields (sequence or mapping of DataFieldBase) – Sequence or mapping of the individual fields. If a mapping is used, the keys set the names 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. If fields are copied the original fields will be left untouched. Conversely, if copy_fields == False, the original fields are modified so their data points to the collection. It is thus basically impossible to have fields that are linked to multiple collections at the same time.

  • 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.

append(*fields, label=None)[source]

create new collection with appended field(s)

Parameters:
  • fields (FieldCollection or DataFieldBase) – A sequence of single fields or collection of fields that will be appended to the fields in the current collection. The data of all fields will be copied.

  • label (str) – Label of the new field collection. If omitted, the current label is used

Returns:

A new field collection, which combines the current one with fields given by fields.

Return type:

FieldCollection

assert_field_compatible(other, accept_scalar=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=None, dtype=None)[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.

  • self (FieldCollection) –

Return type:

FieldCollection

property fields: list[DataFieldBase]

the fields of this collection

Type:

list

classmethod from_data(field_classes, grid, data, *, with_ghost_cells=True, label=None, labels=None, dtype=None)[source]

create a field collection from classes and data

Parameters:
  • field_classes (list) – List of the classes that define the individual fields

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

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

  • with_ghost_cells (bool) – Indicates whether the ghost cells are included in data

  • 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.

classmethod from_scalar_expressions(grid, expressions, *, user_funcs=None, consts=None, label=None, labels=None, dtype=None)[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.

  • user_funcs (dict, optional) – A dictionary with user defined functions that can be used in the expression

  • consts (dict, optional) – A dictionary with user defined constants that can be used in the expression. The values of these constants should either be numbers or ndarray.

  • 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.

Return type:

FieldCollection

classmethod from_state(attributes, data=None)[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

Return type:

FieldCollection

get_image_data(index=0, **kwargs)[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=0, scalar='auto', extract='auto')[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, *, fill=None, label=None)[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.

  • 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: ndarray

scalar magnitudes of all fields

Type:

ndarray

plot(kind='auto', figsize='auto', arrangement='horizontal', subplot_args=None, *args, title=None, constrained_layout=True, filename=None, action='auto', fig_style=None, fig=None, **kwargs)[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, interactive, or merged. 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, unless merged is chosen.

  • 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, grid, vmin=0, vmax=1, *, label=None, labels=None, rng=None)[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

  • rng (Generator) – Random number generator (default: default_rng())

Return type:

FieldCollection

smooth(sigma=1, *, out=None, label=None)[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.

Parameters:
Return type:

FieldCollection

classmethod unserialize_attributes(attributes)[source]

unserializes the given attributes

Parameters:

attributes (dict) – The serialized attributes

Returns:

The unserialized attributes

Return type:

dict