Rendering API

Scientific modules return neutral quantas.api.common.ReportTable and quantas.api.common.PlotCollection objects. The supported functions in quantas.api.rendering turn those contracts into deterministic text and static figures without exposing concrete renderer classes.

Plain-text rendering is available in the base installation. Static figure rendering requires the plot extra.

from pathlib import Path
from quantas.api import elasticity, rendering

result = elasticity.run("calcite.dat")
text = rendering.render_tables(elasticity.build_report(result))
Path("calcite.log").write_text(text, encoding="utf-8")

rendered = rendering.render_plots(
    elasticity.build_3d_plots(result),
    output_dir="figures",
    preset="publication",
    close=True,
)

Rendered plot contracts

class quantas.api.rendering.RenderedPlot(key, kind, figure, path=None)

Bases: object

Describe one concrete plot produced by a public rendering call.

Parameters:
keystr

Stable machine-readable plot identifier.

kindstr

Neutral plot family such as "curve", "surface", or "spherical_map".

figureobject

Backend figure object. The bundled backend returns a Matplotlib figure without making Matplotlib renderer classes public contracts.

pathPath or None

Saved file path when output_dir was supplied.

Parameters:

  • key (str)

  • kind (str)

  • figure (object)

  • path (Path | None)

class quantas.api.rendering.PlotRenderResult(artifacts, warnings=())

Bases: object

Concrete artifacts and warnings returned by render_plots().

Parameters:
artifactstuple of RenderedPlot

Rendered figures in the same order as the neutral collection.

warningstuple of str

Preparation warnings propagated by the scientific plot builder.

Parameters:

  • artifacts (tuple[RenderedPlot, ...])

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

property figures: tuple[object, ...]

Return all backend figure objects.

Returns:
tuple of object

Figure objects in rendering order.

property paths: tuple[Path, ...]

Return paths of all figures written to disk.

Returns:
tuple of Path

Saved paths, excluding artifacts that were not written.

Table rendering

quantas.api.rendering.render_table(table)

Render one neutral report table as deterministic plain text.

Parameters:
tableReportTable

Frontend-neutral table returned by a Quantas report builder.

Returns:
str

Aligned plain text without ANSI sequences or box-drawing characters.

Raises:
TypeError

If table is not a ReportTable.

Parameters:

table (ReportTable)

Return type:

str

quantas.api.rendering.render_tables(tables)

Render an ordered collection of neutral report tables.

Parameters:
tablessequence of ReportTable

Tables returned by a Quantas report builder.

Returns:
str

Concatenated deterministic plain-text report.

Raises:
TypeError

If any item is not a ReportTable.

Parameters:

tables (Sequence[ReportTable])

Return type:

str

Plot rendering

quantas.api.rendering.render_plots(collection, *, output_dir=None, filename_prefix='', image_format='png', preset='screen', dpi=None, figure_size=None, show=False, close=False, axis_label_mode='cartesian', annotate_extrema=True, show_title=False)

Render neutral Quantas plot specifications with the bundled backend.

Parameters:
collectionPlotCollection

Frontend-neutral plot collection returned by build_plots or a module-specific plot builder.

output_dirstr, Path, or None, optional

Directory in which figures are written. Figures are only returned in memory when omitted.

filename_prefixstr, optional

Prefix prepended to generated filenames.

image_formatstr, optional

Matplotlib-supported output format such as "png", "pdf", or "svg".

preset{“screen”, “publication”, “monochrome”}, optional

Standard Quantas figure preset.

dpiint or None, optional

Explicit raster resolution. None preserves the preset value.

figure_sizetuple of float or None, optional

Explicit width and height in inches. None preserves the preset or plot-specific dimensions.

showbool, optional

Display figures through the active Matplotlib backend.

closebool, optional

Close figures after rendering. Use this for batch file generation; closed figures remain listed in the returned artifact metadata.

axis_label_mode{“cartesian”, “crystal”}, optional

Labels used for directional axes.

annotate_extremabool, optional

Annotate extrema when supported by the selected plot type.

show_titlebool, optional

Show titles on three-dimensional surfaces.

Returns:
PlotRenderResult

Public artifact metadata, backend figures, saved paths, and propagated warnings.

Raises:
TypeError

If collection is not a PlotCollection.

ValueError

If rendering options or a plot specification are invalid.

Parameters:

  • collection (PlotCollection)

  • output_dir (str | Path | None)

  • filename_prefix (str)

  • image_format (str)

  • preset (Literal['screen', 'publication', 'monochrome'])

  • dpi (int | None)

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

  • show (bool)

  • close (bool)

  • axis_label_mode (Literal['cartesian', 'crystal'])

  • annotate_extrema (bool)

  • show_title (bool)

Return type:

PlotRenderResult

See also