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)orplot(a, b, multiblock=True). The first dataset sets the layout (dimensionality and panel count, after squeezing any size-1 axis left by a coordinateselect()); every dataset (including the first) is then drawn – overlaid onto the same panels for 1-D, or onto the nextstart_axes-offset block of panels whennum_axesspreads multiple datasets’ components across one grid (the old--subplotsbehaviour). Setoverlay_axes=Trueto keep every dataset in the samestart_axesblock 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
pcolormeshand no explicitzmin/zmaxis 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
yminandzmaxaccept 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/CLIplot1:1 (contour/quiver/streamline/lineouts, shifts/scales, limits, labels, legend, colorbar, aspect, log axes, xkcd/hashtag/jet, style).transposeswaps 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_indicesreplaces each plotted coordinate with its zero-based sample index without changing the dataset itself.save/saveas/no_showmake the render call self-sufficient:saveaswrites a PNG or PDF according to its extension (an extension-less name defaults to PNG), whilesave=Truederives a PNG name from the input dataset.clearletsrender.animateredraw onto a persistent figure across frames. A sequence ofsaveaspaths 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), orrepresent(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
cmaptogether withcvalcolors the line by mappingcvalonto the colormap;cval_min/cval_maxset the normalization range (typically the min/max of thecvalvalues across all curves), so several curves drawn into the same axes share one scale.coloraccepts 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.linestylesimilarly 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,
surfacedraws a 3D surface instead of apcolormesh. When several 2-D datasets are overlaid onto the same axes for comparison, setcomparisonso each surface/contour gets a distinct color and a legend entry instead of overlapping and hiding each other.alphacontrols the surface transparency. Setlegend_subplotto a zero-based subplot index to draw the legend only there;legend_locaccepts any Matplotlib legend location and defaults to"best". Explicitlegend_labelsare used verbatim on every component, without an added_cNsuffix. In Python, passlegend_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 oldalso 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=Trueturns every 1-D component panel into a joined pair split atsplit_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_ratiosandsplit_gapcontrol the pair’s geometry.split_linear_ylimandsplit_log_ylimaccept either one(min, max)pair, a sequence of pairs (one per component), or a mapping from component index to pair.split_legend_sideis'linear','log','left', or'right'. This mode is intentionally limited to 1-D, non-transposed plots.split_seam_ticklabelschooses 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.