Module `phi.vis`

Visualization: plotting, interactive user interfaces.

Use view() to show fields or field variables in an interactive user interface.

Use plot() to plot fields using Matplotlib.

See the user interface documentation at https://tum-pbs.github.io/PhiFlow/Visualization.html

Functions

def action(fun)

def close(figure=None)

Close and destroy a figure.

Args

figure: (Optional) A figure that was created using plot(). If not specified, closes the figure created most recently.

def control(value, range: tuple = None, description='', **kwargs)

Mark a variable as controllable by any GUI created via view().

Example:

>>> dt = control(1.0, (0.1, 10), name="Time increment (dt)")

This will cause a control component (slider, checkbox, text field, drop-down, etc.) to be generated in the user interface. Changes to that component will immediately be reflected in the Python variable assigned to the control. The Python variable will always hold a primitive type, such as int, float´,bool or str`.

Args

value: Initial value. Must be either int, float, bool or str.
range: (Optional) Specify range of possible values as (min, max). Only for int, float and str values.
description: Human-readable description.
**kwargs: Additional arguments to determine the appearance of the GUI component, e.g. rows for text fields or log=False for float sliders.

Returns

value

def load_scalars(scene: phi.field._scene.Scene, name: str, prefix='log_', suffix='.txt', x: str | None = 'steps', entries_dim=(iterationˢ=None), batch_dim=(batchᵇ=None))

Read one or a Tensor of scalar logs as curves.

Args

scene: Scene or str. Directory containing the log files.
name: Log file base name.
prefix: Log file prefix.
suffix: Log file suffix.
x: 'steps' or 'time'
entries_dim: Curve dimension.

Returns

Tensor containing entries_dim and vector.

def overlay(*fields: phi.field._field.Field | phi.geom._geom.Geometry | phiml.math._tensors.Tensor) ‑> phiml.math._tensors.Tensor

Specify that multiple fields should be drawn on top of one another in the same figure. The fields will be plotted in the order they are given, i.e. the last field on top.

>>> plot(vis.overlay(heatmap, points, velocity))

Args

*fields: Field or Tensor instances

Returns

Plottable object

Creates one or multiple figures and sub-figures and plots the given fields.

To show the figures, use show().

The arguments row_dims, col_dims, animate and overlay() control how data is presented. Each accepts dimensions as a str, Shape, tuple, list or type function. In addition to the dimensions present on the data to be plotted, the dimensions args is created if multiple arguments are passed, and tuple, list, dict are generated for corresponding objects to be plotted.

Args

fields: Fields or Tensors to plot.
lib: Plotting library name or reference. Valid names are 'matplotlib', 'plotly' and 'console'.
row_dims: Batch dimensions along which sub-figures should be laid out vertically. Shape or comma-separated names as str, tuple or list.
col_dims: Batch dimensions along which sub-figures should be laid out horizontally. Shape or comma-separated names as str, tuple or list.
title: str for figures with a single subplot. For subplots, pass a string Tensor matching the content dimensions, i.e. row_dims and col_dims. Passing a tuple, list or dict, will create a tensor with these names internally.
size: Figure size in inches, (width, height).
same_scale: Whether to use the same axis limits for all sub-figures.
log_dims: Dimensions for which the plot axes should be scaled logarithmically. Can be given as a comma-separated str, a sequence of dimension names or a Shape. Use '_' to scale unnamed axes logarithmically, e.g. the y-axis of scalar functions.
show_color_bar: Whether to display color bars for heat maps.
color: Tensor of line / marker colors. The color can be specified either as a cycle index (int tensor) or as a hex code (str tensor). The color of different lines and markers can vary.
alpha: Opacity as float or Tensor. This affects all elements, not only line plots. Opacity can vary between lines and markers.
err: Expected deviation from the value given in fields. For supported plots, adds error bars of size 2·err. If the plotted data is the mean of some distribution, a good choice for err is the standard deviation along the mean dims.
animate: Time dimension to animate. If not present in the data, will produce a regular plot instead.
overlay: Dimensions along which elements should be overlaid in the same subplot. The default is only the overlay() dimension which is created by overlay().
frame_time: Interval between frames in the animation.
repeat: Whether the animation should loop.

Returns

Tensor of figure objects. The tensor contains those dimensions of fields that were not reduced by row_dims, col_dims or animate. Currently, only single-figure plots are supported.

In case of an animation, a displayable animation object will be returned instead of a Tensor.

def plot_scalars(*args, **kwargs)

def savefig(path: str, figure=None, dpi=120.0, close=False, transparent=True)

Save a figure to an image file.

Args

figure: Matplotlib or Plotly figure or text.
path: File path.
dpi: Pixels per inch.
close: Whether to close the figure after saving it.
transparent: Whether to save the figure with transparent background.

Args

See plot().

def smooth(curves: phiml.math._tensors.Tensor, n: int, ext: phiml.math.extrapolation.Extrapolation = <phiml.math.extrapolation._SymmetricGradientExtrapolation object>) ‑> phiml.math._tensors.Tensor

Applies a smoothing kernel to curves, all channels independently.

Args

curves: Tensor containing at least one spatial dimension
n: Kernel size, i.e. number of values to average.

Returns

Smoothed curves as Tensor

def write_image(path: str, figure=None, dpi=120.0, close=False, transparent=True)

Save a figure to an image file.

Args

figure: Matplotlib or Plotly figure or text.
path: File path.
dpi: Pixels per inch.
close: Whether to close the figure after saving it.
transparent: Whether to save the figure with transparent background.