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:
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 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.
- assert_field_compatible(other: FieldBase, accept_scalar: bool = False)[source]¶
checks whether other is compatible with the current field
- 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[DataFieldBase]¶
the fields of this collection
- Type
- classmethod from_dict(fields: Dict[str, DataFieldBase], *, copy_fields: bool = False, label: str = None, dtype=None) FieldCollection [source]¶
create a field collection from a dictionary of fields
- Parameters
fields (dict) – Dictionary of fields where keys determine field labels
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
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: 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 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.
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[str, Any], data: Optional[ndarray] = None) FieldCollection [source]¶
create a field collection from given state.
- get_image_data(index: int = 0, **kwargs) Dict[str, Any] [source]¶
return data for plotting an image of the field
- get_line_data(index: int = 0, scalar: str = 'auto', extract: str = 'auto') Dict[str, Any] [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: 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
- 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: Optional[Dict[str, Any]] = 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 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
- 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.