Frontend-neutral plotting contracts

quantas.api.plotting exposes the passive contracts produced by public scientific plot builders. These objects carry prepared numerical values, scientific axes, units, masks, overlays, uncertainty information, directional fields, and portable presentation hints without constructing a concrete figure.

Renderer independence

The contracts do not depend on Matplotlib, Plotly, Dash, Rich, or browser components. A frontend may translate them into a static figure, an interactive figure, a notebook object, or another representation while preserving the scientific data and conventions supplied by Quantas.

Use the public namespace when implementing a renderer:

from quantas.api import elasticity, plotting

result = elasticity.run(
    "calcite.dat",
    options=elasticity.Options(calculate_2d=True),
)
collection = elasticity.build_2d_plots(result, properties=("young",))

for specification in collection.plots:
    if isinstance(specification, plotting.PolarPlotSpec):
        print(specification.key, len(specification.panels))

PlotCollection remains available from quantas.api.common for compatibility with the original common-contract entry point. Both aliases refer to the same class. New renderer implementations should normally import plot-specific contracts from this namespace.

Result-aware discovery

The inventory contracts describe what can be built from a specific scientific result before a frontend selects a builder. They expose scientific property keys, mathematical and plain-text symbols, units, representation families, selection contexts, and result-conditioned limitations without defining a generic build request.

Elasticity, SEISMIC, HA, QHA, and Thermoelasticity expose describe_plots(result) and advertise the registry capability PLOT_INVENTORY. Their existing module-specific builders remain the authoritative typed construction API. EOS advertises the same capability but retains a separate session-aware signature, describe_plots(archive, ...). It first exposes lightweight dataset, slot, and immutable-record history; the common detailed PlotInventory is attached only after an explicit record, accepted slot, or unique accepted result has been selected.

symbol_math contains mathematical source without renderer delimiters such as $. symbol_plain provides a Unicode or plain-text alternative. A context with selectable=False records exact information already fixed by the result, such as the SEISMIC sampling level. HA and QHA coordinate contexts are selectable because their public builders now support exact native-grid sections along either natural independent variable.

from quantas.api import ha

result = ha.read_result("mgo_ha.hdf5")
inventory = ha.describe_plots(result)

for quantity in inventory.properties:
    print(quantity.key, quantity.symbol_plain, quantity.unit)

temperatures = inventory.context_by_key("temperature_grid").values
quantas.api.plotting.PlotKind

alias of Literal[‘line’, ‘contour’, ‘polar’, ‘spherical_map’, ‘spherical_summary’, ‘surface’, ‘panel’]

quantas.api.plotting.PlotContextValue = str | int | float | bool

Represent a PEP 604 union type

E.g. for int | str

class quantas.api.plotting.PlotPropertyDescriptor(key, name, symbol_math, symbol_plain, unit, description='', category='', components=(), representations=())

Describe one scientifically meaningful plottable quantity.

Parameters:
keystr

Stable key accepted by the relevant public builder when the builder selects properties directly.

namestr

Extended human-readable quantity name.

symbol_mathstr

Mathematical symbol source without renderer delimiters such as $.

symbol_plainstr

Plain-text or Unicode symbol suitable for non-mathematical frontends.

unitstr or None

Physical unit of the represented values. Dimensionless quantities use None.

descriptionstr, optional

Short scientific description.

categorystr, optional

Stable module-local grouping key.

componentstuple of str, optional

Stable branches, modes, or components associated with the quantity.

representationstuple of str, optional

Representation keys in the containing PlotInventory.

Parameters:

  • key (str)

  • name (str)

  • symbol_math (str)

  • symbol_plain (str)

  • unit (str | None)

  • description (str)

  • category (str)

  • components (tuple[str, ...])

  • representations (tuple[str, ...])

class quantas.api.plotting.PlotRepresentationDescriptor(key, name, plot_kind, description='', property_keys=(), supported_contexts=(), constraints=())

Describe one scientific representation supported by a module.

Parameters:
keystr

Stable representation identifier.

namestr

Human-readable representation name.

plot_kindPlotKind

Frontend-neutral structural kind returned by the builder.

descriptionstr, optional

Scientific meaning of the representation.

property_keystuple of str, optional

Compatible property keys. An empty tuple is valid for a representation whose quantity is selected entirely through contexts.

supported_contextstuple of str, optional

Context keys required or understood by the representation.

constraintstuple of str, optional

Human-readable scientific limitations that cannot be expressed by the simple compatibility fields.

Parameters:

  • key (str)

  • name (str)

  • plot_kind (Literal['line', 'contour', 'polar', 'spherical_map', 'spherical_summary', 'surface', 'panel'])

  • description (str)

  • property_keys (tuple[str, ...])

  • supported_contexts (tuple[str, ...])

  • constraints (tuple[str, ...])

class quantas.api.plotting.PlotContextDescriptor(key, name, description='', values=(), unit=None, default=None, required=False, selectable=True)

Describe one scientific selection or result context.

Parameters:
keystr

Stable context identifier.

namestr

Human-readable context name.

descriptionstr, optional

Scientific meaning of the context.

valuestuple, optional

Exact supported values. Numeric grid values are expressed in unit.

unitstr or None, optional

Unit associated with numeric values.

defaultstr, int, float, bool, or None, optional

Public default when the context is selectable.

requiredbool, optional

Whether a caller must choose a value explicitly.

selectablebool, optional

False for informative result context such as a sampled grid or the calculation level already fixed in the stored result.

Parameters:

  • key (str)

  • name (str)

  • description (str)

  • values (tuple[str | int | float | bool, ...])

  • unit (str | None)

  • default (str | int | float | bool | None)

  • required (bool)

  • selectable (bool)

class quantas.api.plotting.PlotInventory(module, properties, representations, contexts=(), warnings=())

Complete result-aware plot discovery response for one module.

Parameters:
modulestr

Stable Quantas module identifier.

propertiestuple of PlotPropertyDescriptor

Quantities that can be built from the supplied result.

representationstuple of PlotRepresentationDescriptor

Available scientific representation families.

contextstuple of PlotContextDescriptor, optional

Scientific selections and informative result context.

warningstuple of str, optional

Non-fatal discovery limitations.

Parameters:
property_by_key(key)

Return one property descriptor by stable key.

Raises:
KeyError

If the key is not present in this inventory.

Parameters:

key (str)

Return type:

PlotPropertyDescriptor

representation_by_key(key)

Return one representation descriptor by stable key.

Parameters:

key (str)

Return type:

PlotRepresentationDescriptor

context_by_key(key)

Return one context descriptor by stable key.

Parameters:

key (str)

Return type:

PlotContextDescriptor

Axis and Cartesian primitives

quantas.api.plotting.AxisLocation

alias of Literal[‘top’, ‘bottom’, ‘left’, ‘right’]

quantas.api.plotting.AxisOrientation

alias of Literal[‘x’, ‘y’]

quantas.api.plotting.BandOrientation

alias of Literal[‘vertical’, ‘horizontal’]

quantas.api.plotting.LineStyle

alias of Literal[‘solid’, ‘dashed’, ‘dotted’, ‘dashdot’, ‘none’]

class quantas.api.plotting.PlotAxis(key, label, unit=None, limits=None, metadata=<factory>)

Description of one plot axis.

Parameters:
keystr

Stable machine-readable name of the represented quantity.

labelstr

Complete human-readable axis label, including symbols or units when required.

unitstr or None, optional

Physical unit represented by the axis.

limitstuple or None, optional

Optional lower and upper axis limits. Either bound may be None.

metadatadict, optional

Additional frontend-neutral axis information.

Parameters:

  • key (str)

  • label (str)

  • unit (str | None)

  • limits (tuple[float | None, float | None] | None)

  • metadata (dict[str, Any])

class quantas.api.plotting.PlotSeriesStyle(color=None, line_style='solid', line_width=1.5, marker=None, marker_size=None, marker_edge_color=None, marker_edge_width=None, alpha=1.0, errorbar_line_width=1.0, errorbar_capsize=2.0)

Frontend-neutral style hints for a plotted series.

Parameters:
colorstr or None, optional

Portable color specification. None delegates color selection to the renderer.

line_style{“solid”, “dashed”, “dotted”, “dashdot”}, optional

Semantic line style.

line_widthfloat, optional

Requested line width.

markerstr or None, optional

Optional portable marker name or symbol.

marker_sizefloat or None, optional

Marker size in renderer-independent typographic points.

marker_edge_colorstr or None, optional

Portable marker-edge color. None delegates to the renderer.

marker_edge_widthfloat or None, optional

Marker-edge width in typographic points.

alphafloat, optional

Portable opacity hint between zero and one.

errorbar_line_widthfloat, optional

Requested line width for error bars.

errorbar_capsizefloat, optional

Requested error-bar cap size in typographic points.

Parameters:

  • color (str | None)

  • line_style (Literal['solid', 'dashed', 'dotted', 'dashdot', 'none'])

  • line_width (float)

  • marker (str | None)

  • marker_size (float | None)

  • marker_edge_color (str | None)

  • marker_edge_width (float | None)

  • alpha (float)

  • errorbar_line_width (float)

  • errorbar_capsize (float)

class quantas.api.plotting.PlotSeries(key, label, x, y, x_error=None, y_error=None, style=<factory>, metadata=<factory>)

One numerical series in a neutral plot specification.

Parameters:
keystr

Stable machine-readable series name.

labelstr

Human-readable legend label.

xndarray

One-dimensional horizontal or angular coordinates.

yndarray

One-dimensional dependent values.

x_error, y_errorndarray or None, optional

Optional symmetric one-sigma uncertainties associated with the horizontal and vertical coordinates.

stylePlotSeriesStyle, optional

Portable style hints.

metadatadict, optional

Additional frontend-neutral series information.

Parameters:

  • key (str)

  • label (str)

  • x (ndarray)

  • y (ndarray)

  • x_error (ndarray | None)

  • y_error (ndarray | None)

  • style (PlotSeriesStyle)

  • metadata (dict[str, Any])

class quantas.api.plotting.PlotBandStyle(color=None, alpha=0.2, edge_color=None, edge_width=0.0, line_style='solid')

Frontend-neutral style hints for a confidence or uncertainty band.

Parameters:
colorstr or None, optional

Portable fill color. None delegates selection to the renderer.

alphafloat, optional

Fill opacity between zero and one.

edge_colorstr or None, optional

Optional portable edge color.

edge_widthfloat, optional

Width of the band boundary.

line_styleLineStyle, optional

Boundary line style.

Parameters:

  • color (str | None)

  • alpha (float)

  • edge_color (str | None)

  • edge_width (float)

  • line_style (Literal['solid', 'dashed', 'dotted', 'dashdot', 'none'])

class quantas.api.plotting.PlotBand(key, label, coordinates, lower, upper, orientation='vertical', style=<factory>, metadata=<factory>)

One symmetric or asymmetric interval around a Cartesian curve.

Parameters:
keystr

Stable machine-readable band name.

labelstr

Human-readable legend label.

coordinatesndarray

Coordinates along the varying axis.

lower, upperndarray

Lower and upper bounds perpendicular to coordinates.

orientation{“vertical”, “horizontal”}, optional

"vertical" means coordinates are x values and the bounds are y values. "horizontal" means coordinates are y values and the bounds are x values.

stylePlotBandStyle, optional

Portable display hints.

metadatadict, optional

Additional frontend-neutral information.

Parameters:

  • key (str)

  • label (str)

  • coordinates (ndarray)

  • lower (ndarray)

  • upper (ndarray)

  • orientation (Literal['vertical', 'horizontal'])

  • style (PlotBandStyle)

  • metadata (dict[str, Any])

class quantas.api.plotting.ColoredPathStyle(colormap='viridis', line_style='solid', line_width=1.8, marker=None, marker_size=None, marker_edge_color=None, marker_edge_width=None, alpha=1.0, show_colorbar=True, value_limits=None)

Frontend-neutral style hints for a scalar-colored path.

Parameters:
colormapstr, optional

Portable colormap name.

line_styleLineStyle, optional

Semantic path line style.

line_widthfloat, optional

Path width.

markerstr or None, optional

Optional marker symbol.

marker_sizefloat or None, optional

Marker size in typographic points.

marker_edge_colorstr or None, optional

Portable marker-edge color. None delegates to the renderer.

marker_edge_widthfloat or None, optional

Marker-edge width in typographic points.

alphafloat, optional

Path opacity.

show_colorbarbool, optional

Whether the mapped scalar should receive a colorbar.

value_limitstuple or None, optional

Optional lower and upper scalar limits shared by line and markers.

Parameters:

  • colormap (str)

  • line_style (Literal['solid', 'dashed', 'dotted', 'dashdot', 'none'])

  • line_width (float)

  • marker (str | None)

  • marker_size (float | None)

  • marker_edge_color (str | None)

  • marker_edge_width (float | None)

  • alpha (float)

  • show_colorbar (bool)

  • value_limits (tuple[float, float] | None)

class quantas.api.plotting.ColoredPathSeries(key, label, x, y, values, value_axis, style=<factory>, metadata=<factory>)

Cartesian path whose color is controlled by a third scalar variable.

Parameters:
keystr

Stable machine-readable path name.

labelstr

Human-readable legend label.

x, yndarray

Aligned Cartesian path coordinates.

valuesndarray

Scalar values mapped to the colormap.

value_axisPlotAxis

Description of the color-mapped scalar quantity.

styleColoredPathStyle, optional

Portable display hints.

metadatadict, optional

Additional frontend-neutral information.

Parameters:

  • key (str)

  • label (str)

  • x (ndarray)

  • y (ndarray)

  • values (ndarray)

  • value_axis (PlotAxis)

  • style (ColoredPathStyle)

  • metadata (dict[str, Any])

class quantas.api.plotting.SecondaryAxis(key, label, orientation, location, positions, labels, metadata=<factory>)

Prepared secondary Cartesian axis with explicit tick mapping.

Parameters:
keystr

Stable machine-readable axis name.

labelstr

Complete human-readable axis label.

orientation{“x”, “y”}

Axis orientation.

location{“top”, “bottom”, “left”, “right”}

Side on which the secondary axis is displayed.

positionsndarray

Tick positions expressed in primary-axis coordinates.

labelstuple of str

Labels corresponding one-to-one with positions.

metadatadict, optional

Additional frontend-neutral information.

Parameters:

  • key (str)

  • label (str)

  • orientation (Literal['x', 'y'])

  • location (Literal['top', 'bottom', 'left', 'right'])

  • positions (ndarray)

  • labels (tuple[str, ...])

  • metadata (dict[str, Any])

class quantas.api.plotting.PlotSpan(key, label, axis, start, end, color='0.85', alpha=0.25, hatch=None, metadata=<factory>)

One highlighted interval parallel to a Cartesian axis.

Parameters:
keystr

Stable interval identifier.

labelstr

Human-readable legend label.

axis{“x”, “y”}

Axis along which start and end are defined.

start, endfloat

Interval bounds in data coordinates.

colorstr or None, optional

Portable fill color.

alphafloat, optional

Fill opacity.

hatchstr or None, optional

Portable hatch hint.

metadatadict, optional

Additional frontend-neutral information.

Parameters:

  • key (str)

  • label (str)

  • axis (Literal['x', 'y'])

  • start (float)

  • end (float)

  • color (str | None)

  • alpha (float)

  • hatch (str | None)

  • metadata (dict[str, Any])

class quantas.api.plotting.PlotMask(key, label, x, y, mask, hatch='///', color='none', alpha=0.0, metadata=<factory>)

Two-dimensional boolean overlay for contours and domain maps.

Parameters:
keystr

Stable mask identifier.

labelstr

Human-readable legend label.

x, yndarray

One-dimensional Cartesian coordinates.

maskndarray

Boolean values with shape (len(y), len(x)).

hatchstr, optional

Portable hatch pattern.

colorstr or None, optional

Optional portable face color.

alphafloat, optional

Face opacity.

metadatadict, optional

Additional frontend-neutral information.

Parameters:

  • key (str)

  • label (str)

  • x (ndarray)

  • y (ndarray)

  • mask (ndarray)

  • hatch (str)

  • color (str | None)

  • alpha (float)

  • metadata (dict[str, Any])

class quantas.api.plotting.ScalarBackground(key, coordinates, values, value_axis, axis='y', colormap='viridis', alpha=0.2, show_colorbar=False, value_limits=None, metadata=<factory>)

Scalar field varying along one axis and painted behind a line plot.

Parameters:
keystr

Stable background identifier.

coordinates, valuesndarray

Aligned one-dimensional data coordinates and mapped scalar values.

value_axisPlotAxis

Description of the mapped scalar.

axis{“x”, “y”}, optional

Axis along which the scalar varies.

colormapstr, optional

Portable colormap name.

alphafloat, optional

Background opacity.

show_colorbarbool, optional

Whether a colorbar should be displayed.

value_limitstuple or None, optional

Optional mapped-value limits.

metadatadict, optional

Additional frontend-neutral information.

Parameters:

  • key (str)

  • coordinates (ndarray)

  • values (ndarray)

  • value_axis (PlotAxis)

  • axis (Literal['x', 'y'])

  • colormap (str)

  • alpha (float)

  • show_colorbar (bool)

  • value_limits (tuple[float, float] | None)

  • metadata (dict[str, Any])

Cartesian specifications

class quantas.api.plotting.LinePlotSpec(key, title, filename_stem, x_axis, y_axis, series, bands=<factory>, colored_paths=<factory>, secondary_axes=<factory>, spans=<factory>, backgrounds=<factory>, legend_title=None, legend_columns=1, show_legend=True, grid=True, invert_x_axis=False, invert_y_axis=False, metadata=<factory>)

Neutral specification for a Cartesian line plot.

Parameters:
keystr

Stable plot identifier.

titlestr

Figure title.

filename_stemstr

Default filename stem used by file renderers.

x_axis, y_axisPlotAxis

Axis descriptions.

serieslist of PlotSeries

Ordered ordinary line and error-bar series.

bandslist of PlotBand, optional

Confidence or uncertainty intervals drawn around Cartesian curves.

colored_pathslist of ColoredPathSeries, optional

Paths whose color is controlled by a third scalar quantity.

secondary_axeslist of SecondaryAxis, optional

Prepared secondary tick mappings.

spanslist of PlotSpan, optional

Highlighted intervals parallel to either Cartesian axis.

backgroundslist of ScalarBackground, optional

Scalar fields painted behind the primary line data.

legend_titlestr or None, optional

Optional legend title.

legend_columnsint, optional

Preferred number of legend columns.

show_legendbool, optional

Whether renderers should display a legend.

gridbool, optional

Whether renderers should display a grid.

invert_x_axis, invert_y_axisbool, optional

Whether renderers should invert the corresponding primary axis.

metadatadict, optional

Additional frontend-neutral plot information.

Parameters:
class quantas.api.plotting.ContourPlotSpec(key, title, filename_stem, x_axis, y_axis, value_axis, x, y, z, colormap='viridis', mode='smooth', levels=12, isolines=True, isoline_labels=True, value_limits=None, center=None, masks=<factory>, series=<factory>, colored_paths=<factory>, metadata=<factory>)

Neutral specification for a filled Cartesian contour plot.

Parameters:
keystr

Stable plot identifier.

titlestr

Figure title.

filename_stemstr

Default filename stem used by file renderers.

x_axis, y_axis, value_axisPlotAxis

Horizontal, vertical, and mapped-value descriptions.

x, yndarray

One-dimensional coordinate grids.

zndarray

Two-dimensional mapped values with shape (len(y), len(x)).

colormapstr, optional

Portable colormap name.

mode{“discrete”, “smooth”}, optional

Preferred filled-contour mode.

levelsint, optional

Number of principal contour levels.

isolinesbool, optional

Whether contour lines should be drawn.

isoline_labelsbool, optional

Whether isolines should be labelled.

value_limitstuple or None, optional

Optional lower and upper mapped-value limits.

centerfloat or None, optional

Optional center for a diverging color normalization.

maskslist of PlotMask, optional

Boolean overlays used to mark diagnostic regions.

serieslist of PlotSeries, optional

Ordinary Cartesian paths overlaid on the contour field.

colored_pathslist of ColoredPathSeries, optional

Scalar-colored Cartesian paths overlaid on the contour field.

metadatadict, optional

Additional frontend-neutral plot information.

Parameters:

  • key (str)

  • title (str)

  • filename_stem (str)

  • x_axis (PlotAxis)

  • y_axis (PlotAxis)

  • value_axis (PlotAxis)

  • x (ndarray)

  • y (ndarray)

  • z (ndarray)

  • colormap (str)

  • mode (Literal['discrete', 'smooth'])

  • levels (int)

  • isolines (bool)

  • isoline_labels (bool)

  • value_limits (tuple[float, float] | None)

  • center (float | None)

  • masks (list[PlotMask])

  • series (list[PlotSeries])

  • colored_paths (list[ColoredPathSeries])

  • metadata (dict[str, Any])

Directional and surface specifications

class quantas.api.plotting.PolarPlotPanel(key, title, series, angle_unit='degree', radial_limit=None, theta_zero_location='N', theta_direction=1, grid=True, metadata=<factory>)

One polar panel in a multi-plane plot.

Parameters:
keystr

Stable panel identifier, for example "xy".

titlestr

Human-readable panel title.

serieslist of PlotSeries

Ordered radial series. Their x values are angular coordinates.

angle_unit{“degree”, “radian”}, optional

Unit used by the angular series coordinates.

radial_limitfloat or None, optional

Optional upper radial limit.

theta_zero_locationstr, optional

Cardinal location used as angular zero.

theta_directionint, optional

Angular direction, 1 for counter-clockwise and -1 for clockwise.

gridbool, optional

Whether the polar grid should be displayed.

metadatadict, optional

Additional frontend-neutral panel information.

Parameters:

  • key (str)

  • title (str)

  • series (list[PlotSeries])

  • angle_unit (Literal['degree', 'radian'])

  • radial_limit (float | None)

  • theta_zero_location (str)

  • theta_direction (int)

  • grid (bool)

  • metadata (dict[str, Any])

class quantas.api.plotting.PolarPlotSpec(key, title, filename_stem, panels, show_legend=True, legend_columns=1, metadata=<factory>)

Neutral specification for a multi-panel polar plot.

Parameters:
keystr

Stable plot identifier.

titlestr

Figure title.

filename_stemstr

Default filename stem used by file renderers.

panelslist of PolarPlotPanel

Ordered polar panels.

show_legendbool, optional

Whether a figure-level legend should be displayed.

legend_columnsint, optional

Preferred number of legend columns.

metadatadict, optional

Additional frontend-neutral plot information.

Parameters:

  • key (str)

  • title (str)

  • filename_stem (str)

  • panels (list[PolarPlotPanel])

  • show_legend (bool)

  • legend_columns (int)

  • metadata (dict[str, Any])

class quantas.api.plotting.SurfaceStyle(color=None, colormap=None, opacity=1.0, show_colorbar=True, value_limits=None, show_mesh=False, mesh_color=None, mesh_line_width=0.5)

Frontend-neutral style hints for a three-dimensional surface.

Parameters:
colorstr or None, optional

Portable solid color used when colormap is None.

colormapstr or None, optional

Portable colormap name used to map the physical values.

opacityfloat, optional

Surface opacity between zero and one.

show_colorbarbool, optional

Whether renderers should display a color scale.

value_limitstuple or None, optional

Optional common lower and upper color limits.

show_meshbool, optional

Whether the surface mesh is outlined by the renderer.

mesh_colorstr or None, optional

Optional edge color used when show_mesh is enabled.

mesh_line_widthfloat, optional

Width of the mesh edges when displayed.

Parameters:

  • color (str | None)

  • colormap (str | None)

  • opacity (float)

  • show_colorbar (bool)

  • value_limits (tuple[float, float] | None)

  • show_mesh (bool)

  • mesh_color (str | None)

  • mesh_line_width (float)

class quantas.api.plotting.SurfaceLayer(key, label, x, y, z, values, theta=None, phi=None, style=<factory>, metadata=<factory>)

One Cartesian mesh in a neutral three-dimensional plot.

Parameters:
keystr

Stable branch identifier.

labelstr

Human-readable surface label.

x, y, zndarray

Two-dimensional Cartesian coordinates.

valuesndarray

Physical values used for color mapping and tooltips.

theta, phindarray or None, optional

Optional angular grids in radians.

styleSurfaceStyle, optional

Portable style hints.

metadatadict, optional

Additional frontend-neutral layer information.

Parameters:

  • key (str)

  • label (str)

  • x (ndarray)

  • y (ndarray)

  • z (ndarray)

  • values (ndarray)

  • theta (ndarray | None)

  • phi (ndarray | None)

  • style (SurfaceStyle)

  • metadata (dict[str, Any])

class quantas.api.plotting.VectorFieldStyle(color=None, line_width=1.0, scale=1.0, opacity=1.0)

Portable style hints for a Cartesian vector or axial field.

Parameters:
colorstr or None, optional

Portable color specification. None delegates color selection to the renderer.

line_widthfloat, optional

Requested line width for arrows or axial line segments.

scalefloat, optional

Multiplicative display scale applied by the renderer.

opacityfloat, optional

Layer opacity between zero and one.

Parameters:

  • color (str | None)

  • line_width (float)

  • scale (float)

  • opacity (float)

class quantas.api.plotting.VectorFieldLayer(key, label, origins, vectors, axial=False, resolved_mask=None, style=<factory>, metadata=<factory>)

Cartesian vector or axial field attached to a surface plot.

Parameters:
keystr

Stable machine-readable layer identifier.

labelstr

Human-readable layer label.

originsndarray

Cartesian origins with shape (n, 3).

vectorsndarray

Cartesian directions with shape (n, 3).

axialbool, optional

Whether opposite vector signs represent the same physical axis. Axial layers are rendered as centred line segments rather than arrows.

resolved_maskndarray or None, optional

Optional mask identifying uniquely resolved vectors or axes.

styleVectorFieldStyle, optional

Portable display hints.

metadatadict, optional

Additional frontend-neutral layer information.

Parameters:

  • key (str)

  • label (str)

  • origins (ndarray)

  • vectors (ndarray)

  • axial (bool)

  • resolved_mask (ndarray | None)

  • style (VectorFieldStyle)

  • metadata (dict[str, Any])

class quantas.api.plotting.SurfacePlotSpec(key, title, filename_stem, value_axis, layers, vector_layers=<factory>, equal_aspect=True, show_axes=True, metadata=<factory>)

Neutral specification for one three-dimensional surface figure.

Parameters:
keystr

Stable plot identifier.

titlestr

Figure title.

filename_stemstr

Default filename stem used by file renderers.

value_axisPlotAxis

Description of the radial and color-mapped physical quantity.

layerslist of SurfaceLayer

Ordered Cartesian surface meshes.

vector_layerslist of VectorFieldLayer, optional

Optional Cartesian vector or axial overlays.

equal_aspectbool, optional

Whether all Cartesian axes should use the same scale.

show_axesbool, optional

Whether renderers should display axes and labels.

metadatadict, optional

Additional frontend-neutral plot information.

Parameters:

  • key (str)

  • title (str)

  • filename_stem (str)

  • value_axis (PlotAxis)

  • layers (list[SurfaceLayer])

  • vector_layers (list[VectorFieldLayer])

  • equal_aspect (bool)

  • show_axes (bool)

  • metadata (dict[str, Any])

quantas.api.plotting.SphericalProjection

alias of Literal[‘equal_area’, ‘stereographic’]

class quantas.api.plotting.SphericalMarker(key, label, directions, marker='circle', metadata=<factory>)

Marker attached to one or more directions on a spherical map.

Parameters:
keystr

Stable machine-readable marker identifier.

labelstr

Human-readable marker label.

directionsndarray

Cartesian unit directions with shape (n, 3).

markerstr, optional

Portable marker symbol.

metadatadict, optional

Additional frontend-neutral marker information.

Parameters:

  • key (str)

  • label (str)

  • directions (ndarray)

  • marker (str)

  • metadata (dict[str, Any])

class quantas.api.plotting.AxisFieldLayer(key, label, directions, axes, resolved_mask=None, metadata=<factory>)

Axial-vector field sampled on directions of a spherical map.

Parameters:
keystr

Stable machine-readable layer identifier.

labelstr

Human-readable layer label.

directionsndarray

Cartesian unit directions at which the axes are drawn.

axesndarray

Cartesian unit axes with shape (n, 3). Opposite signs represent the same physical axis.

resolved_maskndarray or None, optional

Optional mask identifying uniquely resolved axes.

metadatadict, optional

Additional frontend-neutral layer information.

Parameters:

  • key (str)

  • label (str)

  • directions (ndarray)

  • axes (ndarray)

  • resolved_mask (ndarray | None)

  • metadata (dict[str, Any])

class quantas.api.plotting.SphericalMapSpec(key, title, filename_stem, theta, phi, values, value_axis, hemisphere, projection='equal_area', colormap='viridis', levels=12, isolines=True, markers=<factory>, axis_layers=<factory>, metadata=<factory>)

Neutral specification for a scalar field on a spherical domain.

Parameters:
keystr

Stable plot identifier.

titlestr

Figure title.

filename_stemstr

Default filename stem used by file renderers.

theta, phindarray

One-dimensional polar and azimuthal coordinates in radians.

valuesndarray

Scalar field with shape (len(theta), len(phi)).

value_axisPlotAxis

Description of the mapped physical quantity.

hemisphere{“upper”, “lower”, “full”}

Spherical domain represented by the data.

projection{“equal_area”, “stereographic”}, optional

Preferred map projection.

colormapstr, optional

Portable colormap name.

levelsint, optional

Preferred number of contour levels.

isolinesbool, optional

Whether isolines should be displayed.

markerslist of SphericalMarker, optional

Directional extrema or other annotations.

axis_layerslist of AxisFieldLayer, optional

Axial-vector overlays such as polarization axes.

metadatadict, optional

Additional frontend-neutral plot information.

Parameters:

  • key (str)

  • title (str)

  • filename_stem (str)

  • theta (ndarray)

  • phi (ndarray)

  • values (ndarray)

  • value_axis (PlotAxis)

  • hemisphere (Literal['upper', 'lower', 'full'])

  • projection (Literal['equal_area', 'stereographic'])

  • colormap (str)

  • levels (int)

  • isolines (bool)

  • markers (list[SphericalMarker])

  • axis_layers (list[AxisFieldLayer])

  • metadata (dict[str, Any])

class quantas.api.plotting.SphericalSummarySpec(key, title, filename_stem, maps, columns=3, metadata=<factory>)

Multi-panel summary assembled from spherical scalar maps.

Parameters:
keystr

Stable plot identifier.

titlestr

Figure title.

filename_stemstr

Default filename stem used by file renderers.

mapslist of SphericalMapSpec

Ordered spherical maps shown in the summary.

columnsint, optional

Preferred number of panel columns.

metadatadict, optional

Additional frontend-neutral layout information.

Parameters:

  • key (str)

  • title (str)

  • filename_stem (str)

  • maps (list[SphericalMapSpec])

  • columns (int)

  • metadata (dict[str, Any])

Composite and collection contracts

class quantas.api.plotting.PanelPlotSpec(key, title, filename_stem, panels, columns=2, share_x=False, share_y=False, metadata=<factory>)

Neutral multi-panel layout for Cartesian line and contour plots.

Parameters:
keystr

Stable plot identifier.

titlestr

Figure-level title.

filename_stemstr

Default filename stem used by file renderers.

panelslist of LinePlotSpec or ContourPlotSpec

Ordered Cartesian panels.

columnsint, optional

Preferred number of panel columns.

share_x, share_ybool, optional

Whether compatible panels should share their respective axes.

metadatadict, optional

Additional frontend-neutral layout information.

Raises:
ValueError

If no panels are provided or columns is not positive.

Parameters:

  • key (str)

  • title (str)

  • filename_stem (str)

  • panels (list[LinePlotSpec | ContourPlotSpec])

  • columns (int)

  • share_x (bool)

  • share_y (bool)

  • metadata (dict[str, Any])

quantas.api.plotting.PlotSpec = quantas.models.plot.LinePlotSpec | quantas.models.plot.ContourPlotSpec | quantas.models.plot.PolarPlotSpec | quantas.models.plot.SurfacePlotSpec | quantas.models.plot.SphericalMapSpec | quantas.models.plot.SphericalSummarySpec | quantas.models.plot.PanelPlotSpec

Represent a PEP 604 union type

E.g. for int | str

class quantas.api.plotting.PlotCollection(plots=<factory>, warnings=<factory>)

Collection of neutral plot specifications and non-fatal warnings.

Parameters:
plotslist of PlotSpec, optional

Ordered specifications ready for rendering.

warningslist of str, optional

Non-fatal conditions encountered while preparing plot data.

Parameters:

See also