postgkyl.plot

postgkyl.plot(*datasets, multiblock=False, args=None, figure=None, squeeze=False, transpose=False, grid_indices=False, num_axes=None, start_axes=0, overlay_axes=False, num_subplot_row=None, num_subplot_col=None, streamline=False, sdensity=1.0, arrowstyle=None, scatter=False, quiver=False, contour=False, clevels=None, cnlevels=None, cont_label=False, surface=False, comparison=False, alpha=None, diverging=False, lineouts=None, xmin=None, xmax=None, xscale=1.0, xshift=0.0, ymin=None, ymax=None, yscale=1.0, yshift=0.0, zmin=None, zmax=None, zscale=1.0, zshift=0.0, relax=False, style=None, rcParams=None, no_legend=False, legend_labels=None, legend_subplot=None, legend_loc='best', forcelegend=False, no_colorbar=False, xlabel=None, ylabel=None, clabel=None, title=None, subplot_titles=None, subplot_xlabels=None, subplot_ylabels=None, logx=False, logy=False, logz=False, split_linear_log=False, split_point=0.0, split_log_side='right', split_width_ratios=(1.0, 1.0), split_gap=0.0, split_linear_ylim=None, split_log_ylim=None, no_split_right_ticks=False, split_legend_side='log', split_log_base=10.0, split_log_nonpositive='clip', split_seam_ticklabels='left', fixaspect=False, aspect=None, edgecolors=None, no_showgrid=False, hashtag=False, xkcd=False, color=None, markersize=None, linewidth=None, linestyle=None, figsize=None, jet=False, cmap=None, cval=None, cval_min=None, cval_max=None, save=False, saveas=None, dpi=200, no_show=False, clear=False)

Plot one or more datasets onto a shared figure and return it.

Accepts plot(a) or plot(a, b, multiblock=True). The first dataset sets the layout (dimensionality and panel count, after squeezing any size-1 axis left by a coordinate select()); every dataset (including the first) is then drawn – overlaid onto the same panels for 1-D, or onto the next start_axes-offset block of panels when num_axes spreads multiple datasets’ components across one grid (the old --subplots behaviour). Set overlay_axes=True to keep every dataset in the same start_axes block instead of advancing per dataset – what the blocks of one multiblock field want, since they are one field and belong in one panel.

When more than one 2-D dataset is drawn as a pcolormesh and no explicit zmin/zmax is given, all of them share one per-component color scale (computed across the whole call) and one colorbar per panel, so the colorbar describes every dataset on the axes rather than whichever was drawn last.

Bounds such as ymin and zmax accept a shared number or a mapping from zero-based logical panel index to bound. Unspecified panels use their data limits. Coordinate axes shared by the layout keep common bounds.

Most of the keyword arguments mirror main’s output.plot/CLI plot 1:1 (contour/quiver/streamline/lineouts, shifts/scales, limits, labels, legend, colorbar, aspect, log axes, xkcd/hashtag/jet, style). transpose swaps the horizontal and vertical axes: in 1-D the coordinate moves to the vertical axis; in 2-D the data, grid, and default labels are swapped before drawing (shifts/scales keep their screen-axis meaning). grid_indices replaces each plotted coordinate with its zero-based sample index without changing the dataset itself. save/saveas/ no_show make the render call self-sufficient: saveas writes a PNG or PDF according to its extension (an extension-less name defaults to PNG), while save=True derives a PNG name from the input dataset. clear lets render.animate redraw onto a persistent figure across frames. A sequence of saveas paths writes the same figure to each path; this is primarily useful to CLI callers that request both a named output and frame output.

Modal DG data plots each stored coefficient as a separate channel on the cell grid. To plot the evaluated field, first use interpolate (uniform mesh), local_poly (preserves cell jumps), represent(to='nodal') (basis nodes), or represent(to='quad') (quadrature points). For native nodal/quadrature heatmaps, colored patches end at the original cell boundaries, with interior edges midway between sampling points. The input dataset is unchanged.

For 1-D data, passing cmap together with cval colors the line by mapping cval onto the colormap; cval_min/cval_max set the normalization range (typically the min/max of the cval values across all curves), so several curves drawn into the same axes share one scale. color accepts either one Matplotlib color, applied to every line, or a sequence containing one color per dataset (reused for all its components). A sequence with one color per individual line is also accepted, in dataset/component order. linestyle similarly accepts one style applied to every dataset, or a sequence with one entry per dataset; a one-entry sequence is broadcast to every dataset.

For 2-D data, surface draws a 3D surface instead of a pcolormesh. When several 2-D datasets are overlaid onto the same axes for comparison, set comparison so each surface/contour gets a distinct color and a legend entry instead of overlapping and hiding each other. alpha controls the surface transparency. Set legend_subplot to a zero-based subplot index to draw the legend only there; legend_loc accepts any Matplotlib legend location and defaults to "best". Explicit legend_labels are used verbatim on every component, without an added _cN suffix. In Python, pass legend_labels=["new", "old"]; in the CLI, pass --legend_labels '["new","old"]'. Quote the entire JSON array so the shell preserves its brackets and double quotes. Repeating --legend_labels new --legend_labels old also works. Labels follow dataset input order and are reused on each component subplot. A comma-separated CLI value without brackets is one literal label.

split_linear_log=True turns every 1-D component panel into a joined pair split at split_point: coordinates below the point are drawn on the left and coordinates at/above it on the right. The right side is logarithmic in y by default; split_log_side='left' reverses which half is logarithmic. split_width_ratios and split_gap control the pair’s geometry. split_linear_ylim and split_log_ylim accept either one (min, max) pair, a sequence of pairs (one per component), or a mapping from component index to pair. split_legend_side is 'linear', 'log', 'left', or 'right'. This mode is intentionally limited to 1-D, non-transposed plots. split_seam_ticklabels chooses which side owns the label at the joined boundary: 'left' (the default), 'right', 'both', or 'none'.

Parameters:
  • datasets – Datasets to draw.

  • multiblock – Force every dataset onto one figure instead of grouping fields.

  • args – Positional Matplotlib plot arguments.

  • figure – Existing or numbered figure to target.

  • squeeze – Remove singleton spatial axes before laying out panels.

  • transpose – Swap the horizontal and vertical display axes.

  • grid_indices – Plot zero-based sample indices instead of grid values.

  • num_axes – Number of logical component axes.

  • start_axes – First logical component axis to use.

  • overlay_axes – Draw every dataset in the same component-axis block.

  • num_subplot_row – Forced subplot row count.

  • num_subplot_col – Forced subplot column count.

  • streamline – Draw two-component fields as streamlines.

  • sdensity – Streamline density.

  • arrowstyle – Streamline arrow style.

  • scatter – Draw markers without connecting lines.

  • quiver – Draw two-component fields as arrows.

  • contour – Draw two-dimensional values as contours.

  • clevels – Explicit contour-level specification.

  • cnlevels – Number of contour levels.

  • cont_label – Label contour lines.

  • surface – Draw two-dimensional values as a three-dimensional surface.

  • comparison – Distinguish overlaid two-dimensional datasets.

  • alpha – Surface or comparison transparency.

  • diverging – Use a diverging colormap.

  • lineouts – Draw this many lineouts from two-dimensional data.

  • xmin – Lower horizontal-axis bound, shared or mapped by panel index.

  • xmax – Upper horizontal-axis bound, shared or mapped by panel index.

  • xscale – Horizontal-coordinate scale factor.

  • xshift – Horizontal-coordinate shift.

  • ymin – Lower vertical-axis bound, shared or mapped by panel index.

  • ymax – Upper vertical-axis bound, shared or mapped by panel index.

  • yscale – Vertical-coordinate scale factor.

  • yshift – Vertical-coordinate shift.

  • zmin – Lower value or color bound, shared or mapped by panel index.

  • zmax – Upper value or color bound, shared or mapped by panel index.

  • zscale – Value scale factor.

  • zshift – Value shift.

  • relax – Allow relaxed layout behavior for reused figures.

  • style – Matplotlib style name or style-file path.

  • rcParams – Matplotlib configuration overrides.

  • no_legend – Suppress legends for line plots.

  • legend_labels – Dataset labels in input order; CLI: –legend_labels ‘[“new”,”old”]’ (quote the whole JSON array), or repeat the option.

  • legend_subplot – Zero-based subplot receiving the legend.

  • legend_loc – Matplotlib legend location.

  • forcelegend – Retained for compatibility; default curves already have labels.

  • no_colorbar – Suppress color bars for field plots.

  • xlabel – Horizontal-axis label override.

  • ylabel – Vertical-axis label override.

  • clabel – Color-bar label override.

  • title – Figure-title override.

  • subplot_titles – Per-subplot title specification.

  • subplot_xlabels – Per-subplot horizontal-label specification.

  • subplot_ylabels – Per-subplot vertical-label specification.

  • logx – Use logarithmic horizontal coordinates.

  • logy – Use a logarithmic vertical axis.

  • logz – Use logarithmic values or colors.

  • split_linear_log – Split each one-dimensional panel into linear and log halves.

  • split_point – Coordinate joining the split halves.

  • split_log_side – Half using logarithmic scaling.

  • split_width_ratios – Relative widths of the split halves.

  • split_gap – Gap between split halves.

  • split_linear_ylim – Limits for the linear half.

  • split_log_ylim – Limits for the logarithmic half.

  • no_split_right_ticks – Suppress ticks on the right edge of split panels.

  • split_legend_side – Split half receiving the legend.

  • split_log_base – Logarithm base for the logarithmic half.

  • split_log_nonpositive – Handling of nonpositive logarithmic values.

  • split_seam_ticklabels – Half owning labels at the split seam.

  • fixaspect – Use equal physical scaling on coordinate axes.

  • aspect – Explicit axes aspect ratio.

  • edgecolors – Mesh edge color.

  • no_showgrid – Suppress plot grid lines.

  • hashtag – Prefix labels with a hash marker.

  • xkcd – Draw using Matplotlib’s XKCD context.

  • color – Line color or per-line colors.

  • markersize – Line-marker size.

  • linewidth – Line width.

  • linestyle – Line style or per-dataset styles.

  • figsize – Figure width and height in inches.

  • jet – Use the legacy jet colormap.

  • cmap – Matplotlib colormap name.

  • cval – Scalar used to color a one-dimensional curve.

  • cval_min – Lower normalization bound for curve coloring.

  • cval_max – Upper normalization bound for curve coloring.

  • save – Save to an automatically derived output name.

  • saveas – Explicit image output path or paths.

  • dpi – Saved-image resolution.

  • no_show – Do not display the figures interactively.

  • clear – Clear a reused figure before drawing.

Returns:

One Matplotlib Figure, or one figure per distinct field/frame family.

Raises:

ValueError – nothing to plot, a dataset has no values, a dataset has more than two (squeezed) dimensions, or (without squeeze) a reused figure does not have enough axes for the panel count.

CLI: plot