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:
- assert_field_compatible(other, accept_scalar=False)[source]
checks whether other is compatible with the current field
- 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:
- property fields: list[DataFieldBase]
the fields of this collection
- Type:
- 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 gridgrid (
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 definedexpressions (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:
- classmethod from_state(attributes, data=None)[source]
create a field collection from given state.
- Parameters:
- Return type:
- get_line_data(index=0, scalar='auto', extract='auto')[source]
return data for a line plot of the field
- Parameters:
- Returns:
Information useful for performing a line plot of the field
- Return type:
- 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
- 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 definedvmin (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:
- 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:
sigma (float) –
out (FieldCollection | None) –
label (str | None) –
- Return type: