The plotlib submodule

Functional Analysis

Purpose

A Matplotlib wrapper that encapsulates figure/graph/widget creation into a composable object hierarchy, eliminating boilerplate and providing a consistent API for all plots in fluidsolve.

Class Hierarchy & Relationships

PlotFigure
├── PlotGraph  (1..n, registered via addGraph)
│   ├── PlotCurve       (1..n, addCurve)
│   ├── PlotLine        (0..n, addVline / addHline)
│   ├── PlotAnnotation  (0..n, addAnnotation)
│   ├── PlotAxis        (0..4: x1, y1, x2, y2)
│   ├── PlotGrid        (0..1)
│   └── PlotLegend      (0..1)
├── PlotButton  (0..n, widget panel, addButton)
└── PlotSlider  (0..n, widget panel, addSlider)

All child objects hold a weakref back to their parent to avoid reference cycles.

Classes

Class	Role
PlotFigure	Top-level container. Manages plt.figure, GridSpec, optional widget figure, Tk window, and toolbar. Orchestrates show() / update() / updateData() on all children.
PlotGraph	Wraps a single matplotlib.axes.Axes. Positioned in the parent GridSpec by row/column (int or slice). Owns axes, curves, lines, annotations, axis config, grid, and legend.
PlotCurve	One data series: line, scatter, or bar. Supports in-place data update (set_xdata / set_ydata / set_offsets) without rebuilding the artist.
PlotLine	Static horizontal or vertical reference line (axhline / axvline).
PlotAxis	Configures one of four axis positions (x1, y1, x2, y2). Handles limits, tick spacing (vstep / vmstep), axis sharing, and labels. Secondary axes use twiny() / twinx().
PlotAnnotation	Batch text annotations over lists of (x, y, label) triples. Supports alternating offsets (xtoggle / ytoggle) for readability. Fully redrawn on updateData().
PlotGrid	Delegates to ax.grid() with configurable axis, color, linestyle, linewidth.
PlotLegend	Delegates to ax.legend() with location, title, font sizes, columns, and frame.
PlotButton	Matplotlib Button widget in the separate widget figure. Fires a user-supplied Callable on click.
PlotSlider	Matplotlib Slider widget with min/max/step/init. Fires a user-supplied Callable on change.

Key Design Patterns

• Two-phase construction: objects are configured first, then show() is called lazily (once) by prepareShow(). A _prepare flag prevents double-building.

• Validated kwargs: all __init__ parameters go through flsa.GetArgs / flsa.vFun validators (type checks, range checks, defaults, coercions).

• ``extra`` dict escape hatch: every class accepts an extra={} kwarg that is merged into the underlying matplotlib call, allowing full pass-through of any matplotlib option without needing to expose it explicitly.

• Update modes: update() redraws data and re-applies axes/grid; updateData() updates data in-place only — faster for interactive refresh.

• Widget panel: buttons and sliders live in a second plt.figure (separate from the graph figure), embedded side-by-side in the same Tk window. The widget panel is created when either buttons or sliders are registered.

---

Matplotlib wrapper utilities for engineering plots.

This module provides reusable plotting infrastructure used by fluidsolve, including figure/grid management, axis helpers, and optional interactive widgets (sliders/buttons) for parameter exploration.

Scope:

• generic plotting primitives and containers,

• consistent figure sizing/layout setup,

• Tk-backed embedding and toolbar support,

• helper integration points for higher-level domain plots.

Design intent:

• centralize matplotlib boilerplate in one place,

• keep plot creation consistent across examples and tools,

• provide a stable base for domain modules such as plotext.

Typical usage:

fig = PlotFigure(title='Q-H overview', nr=1, nc=1, toolbar=True)
graph = PlotGraph(fig, r=0, c=0)
curve = PlotCurve(graph, x=[0, 1, 2], y=[10, 8, 4])
fig.show()

By separating plotting infrastructure from hydraulic semantics, this module keeps UI/figure concerns maintainable and reusable.

Reference inspiration: https://medium.com/@basubinayak05/python-data-visualization-day-1-71334ff5044e

class fluidsolve.plotlib.PlotFigure(**kwargs: int)

Bases: object

Matplotlib figure container.

Parameters:

• dpi (int, optional) – Screen resolution (dots per inch).

• h (int, optional) – Figure height in pixels.

• w (int, optional) – Figure width in pixels.

• hw (int, optional) – Widget area height in pixels.

• nr (int, optional) – Number of graph rows.

• nc (int, optional) – Number of graph columns.

• nrw (int, optional) – Number of widget rows.

• ncw (int, optional) – Number of widget columns.

• facecolor (str, optional) – Background color.

• title (str, optional) – Figure title.

• toolbar (bool, optional) – Show the navigation toolbar.

• constrained_layout (bool, optional) – Use matplotlib constrained layout. Default True.

• extra (dict, optional) – Extra kwargs passed to plt.figure.

__init__(**kwargs: int) → None

property h: int

Figure height in pixels.

property w: int

Figure width in pixels.

property hw: int

Widget area height in pixels.

property nr: int

Number of graph rows.

property nc: int

Number of graph columns.

property nrw: int

Number of widget rows.

property ncw: int

Number of widget columns.

property figure: Any

Underlying matplotlib Figure object.

property gridspec: Any

Underlying GridSpec object.

property figure_widgets: Any

Matplotlib Figure used for widget controls.

property gridspec_widgets: Any

GridSpec used for widget controls.

property buttons: dict

List of registered PlotButton objects.

property sliders: dict

List of registered PlotSlider objects.

setExtra(key: str, **kwargs: int) → None

Updates extra configuration values for a given key.

This method merges the provided keyword arguments into the existing dictionary stored under self._extra[key].

Parameters:

• key (str) – The key under which to store extra configuration values. Must be one of the allowed values.

• **values (Any) – Arbitrary keyword arguments to merge into the extra configuration dictionary.

addGraph(graph: PlotGraph) → int

Register a graph and return its index.

Parameters:

graph (PlotGraph) – Graph to register.

Returns:

Index of the registered graph.

Return type:

int

addButton(button: PlotButton) → int

Register a button and return its index.

Parameters:

button (PlotButton) – Button to register.

Returns:

Index of the registered button.

Return type:

int

addSlider(slider: PlotSlider) → int

Register a slider and return its index.

Parameters:

slider (PlotSlider) – Slider to register.

Returns:

Index of the registered slider.

Return type:

int

prepareShow() → None

Build the figure, graphs, and widget areas.

show() → None

Build and display the figure in a Tkinter window.

update() → None

Redraw all graphs (curves, annotations, axes) and refresh the canvas.

updateData() → None

Update data in all graphs and refresh the canvas without touching axes or grid.

class fluidsolve.plotlib.PlotGraph(figure: PlotFigure, **kwargs: int)

Bases: object

Matplotlib axes container.

Parameters:

• figure (PlotFigure) – Parent figure.

• r (int | str) – Row index or slice in the GridSpec.

• c (int | str) – Column index or slice in the GridSpec.

• polar (bool, optional) – Use polar projection.

• title (str, optional) – Axes title.

• facecolor (str, optional) – Axes background color.

• edgecolor (str, optional) – Axes edge color.

• extra (dict, optional) – Extra kwargs passed to add_subplot.

__init__(figure: PlotFigure, **kwargs: int) → None

property axes: Any

Underlying matplotlib Axes object.

getAxes(axis: str = 'main') → Any

Return the requested matplotlib Axes object.

getAllAxes() → list

Return all configured matplotlib Axes objects without duplicates.

setExtra(key: str, **kwargs: int) → None

Updates extra configuration values for a given key.

This method merges the provided keyword arguments into the existing dictionary stored under self._extra[key].

Parameters:

• key (str) – The key under which to store extra configuration values. Must be one of the allowed values.

• **values (Any) – Arbitrary keyword arguments to merge into the extra configuration dictionary.

setXAxis(**kwargs: Any) → None

Configure the primary X axis.

setYAxis(**kwargs: Any) → Any

Configure the primary Y axis.

setXAxis2(**kwargs: Any) → Any

Configure the secondary X axis.

setYAxis2(**kwargs: Any) → Any

Configure the secondary Y axis.

setGrid(**kwargs: Any) → Any

Configure the grid.

setLegend(**kwargs: Any) → None

Configure the legend.

addCurve(curve: PlotCurve) → int

Register a curve and return its index.

Parameters:

curve (PlotCurve) – Curve to register.

Returns:

Index of the registered curve.

Return type:

int

addVline(line: PlotLine) → int

Register a vertical line and return its index.

Parameters:

line (PlotLine) – Line to register.

Returns:

Index of the registered line.

Return type:

int

addHline(line: PlotLine) → int

Register a horizontal line and return its index.

Parameters:

line (PlotLine) – Line to register.

Returns:

Index of the registered line.

Return type:

int

addAnnotation(annotation: PlotAnnotation) → int

Register an annotation and return its index.

Parameters:

annotation (PlotAnnotation) – Annotation to register.

Returns:

Index of the registered annotation.

Return type:

int

show() → None

Show the graph (axes); This is called by PlotFigure.show().

update() → None

Redraw curves and annotations, then re-apply axis limits and grid.

updateData() → None

Redraw only curve and annotation data without touching axes or grid.

class fluidsolve.plotlib.PlotCurve(graph: PlotGraph, **kwargs: int)

Bases: object

A single data series on a PlotGraph.

Parameters:

• graph (PlotGraph) – Parent graph.

• type (str, optional) – Plot type; one of line, scatter, or bar.

• x (list, optional) – X data.

• y (list, optional) – Y data.

• label (str, optional) – Legend label.

• color (str, optional) – Line or marker color.

• alpha (float, optional) – Opacity.

• linestyle (str, optional) – Line style.

• marker (str, optional) – Marker style.

• extra (dict, optional) – Extra kwargs passed to the plot call.

__init__(graph: PlotGraph, **kwargs: int) → None

property x: list

x data.

Returns:

x data.

Return type:

list

property y: list

y data.

Returns:

y data.

Return type:

list

property curve: Any

curve object.

Returns:

curve object.

Return type:

Any

setExtra(key: str, **kwargs: int) → None

Updates extra configuration values for a given key.

This method merges the provided keyword arguments into the existing dictionary stored under self._extra[key].

Parameters:

• key (str) – The key under which to store extra configuration values. Must be one of the allowed values.

• **values (Any) – Arbitrary keyword arguments to merge into the extra configuration dictionary.

show() → None

Show the data; This is called by PlotGraph.show().

update() → None

Redraw the curve with current data.

updateData() → None

Update curve data in-place without rebuilding the artist.

class fluidsolve.plotlib.PlotLine(graph: PlotGraph, **kwargs: int)

Bases: object

Horizontal or vertical reference line on a PlotGraph.

Parameters:

• graph (PlotGraph) – Parent graph.

• typev (bool) – True for vertical, False for horizontal.

• v (float, optional) – Position of the line.

• x (float, optional) – Relative start position (0-1).

• y (float, optional) – Relative end position (0-1).

• label (str, optional) – Legend label.

• color (str, optional) – Line color.

• alpha (float, optional) – Opacity.

• linestyle (str, optional) – Line style.

• extra (dict, optional) – Extra kwargs for the line call.

__init__(graph: PlotGraph, **kwargs: int) → None

setExtra(key: str, **kwargs: int) → None

Updates extra configuration values for a given key.

This method merges the provided keyword arguments into the existing dictionary stored under self._extra[key].

Parameters:

• key (str) – The key under which to store extra configuration values. Must be one of the allowed values.

• **values (Any) – Arbitrary keyword arguments to merge into the extra configuration dictionary.

show() → None

Show the line; This is called by PlotGraph.show().

class fluidsolve.plotlib.PlotAxis(graph: PlotGraph, **kwargs: int)

Bases: object

Configures axis properties on a PlotGraph.

Parameters:

• graph (PlotGraph) – Parent graph.

• type (str) – Axis type: x1, y1, x2, or y2. Set by PlotGraph.

• share (object, optional) – Axis to share scale with.

• vmin (int | float, optional) – Minimum axis value.

• vmax (int | float, optional) – Maximum axis value.

• vstep (int | float, optional) – Major tick step.

• vmstep (int | float, optional) – Minor tick step.

• axison (bool, optional) – Whether the axis is visible.

• axiscolor (str, optional) – Axis line color.

• labeltxt (str, optional) – Axis label text.

• labelcolor (str, optional) – Axis label color.

• labelfmt (str, optional) – Tick label format string.

• extra (dict, optional) – Extra kwargs for axis configuration.

__init__(graph: PlotGraph, **kwargs: int) → None

setExtra(key: str, **kwargs: int) → None

Updates extra configuration values for a given key.

This method merges the provided keyword arguments into the existing dictionary stored under self._extra[key].

Parameters:

• key (str) – The key under which to store extra configuration values. Must be one of the allowed values.

• **values (Any) – Arbitrary keyword arguments to merge into the extra configuration dictionary.

property axes: Any

Return the matplotlib Axes configured for this axis object.

show() → dict

Show the axis; This is called by PlotGraph.show().

class fluidsolve.plotlib.PlotAnnotation(graph: PlotGraph, **kwargs: int)

Bases: object

Configures annotation properties on a PlotGraph.

Parameters:

• graph (PlotGraph) – Parent graph.

• label (list, optional) – Annotation text labels.

• x (list, optional) – X positions.

• y (list, optional) – Y positions.

• textcoords (str, optional) – Coordinate system for text offset.

• xoffset (int | float, optional) – Horizontal text offset.

• yoffset (int | float, optional) – Vertical text offset.

• xtoggle (int | float, optional) – Alternating horizontal shift.

• ytoggle (int | float, optional) – Alternating vertical shift.

• fontsize (int, optional) – Text font size.

• color (str, optional) – Text color.

• bbox (dict, optional) – Bounding box properties.

• arrow (dict, optional) – Arrow properties.

• halignment (str, optional) – Horizontal alignment.

• valignment (str, optional) – Vertical alignment.

• extra (dict, optional) – Extra kwargs passed to annotate.

__init__(graph: PlotGraph, **kwargs: int) → None

property x: list

x data.

Returns:

x data.

Return type:

list

property y: list

y data.

Returns:

y data.

Return type:

list

property label: list

label data.

Returns:

label data.

Return type:

list

setExtra(key: str, **values: Any) → None

Updates extra configuration values for a given key.

This method merges the provided keyword arguments into the existing dictionary stored under self._extra[key].

Parameters:

• key (str) – The key under which to store extra configuration values. Must be one of the allowed values.

• **values (Any) – Arbitrary keyword arguments to merge into the extra configuration dictionary.

show() → None

Show the annotation; This is called by PlotGraph.show().

update() → None

Update the annotation by removing and redrawing it.

updateData() → None

Remove and redraw all annotations with current data.

class fluidsolve.plotlib.PlotGrid(graph: PlotGraph, **kwargs: int)

Bases: object

Configures grid properties on a PlotGraph.

Parameters:

• graph (PlotGraph) – Parent graph.

• axis (str, optional) – Which axis to apply the grid to: x, y, or both.

• color (str, optional) – Grid line color.

• linestyle (str, optional) – Grid line style.

• linewidth (int | float, optional) – Grid line width.

• extra (dict, optional) – Extra kwargs passed to ax.grid.

__init__(graph: PlotGraph, **kwargs: int) → None

setExtra(key: str, **kwargs: int) → None

Updates extra configuration values for a given key.

This method merges the provided keyword arguments into the existing dictionary stored under self._extra[key].

Parameters:

• key (str) – The key under which to store extra configuration values. Must be one of the allowed values.

• **values (Any) – Arbitrary keyword arguments to merge into the extra configuration dictionary.

show() → dict

Show the grid; This is called by PlotGraph.show().

class fluidsolve.plotlib.PlotLegend(graph: PlotGraph, **kwargs: int)

Bases: object

Configures a legend on a PlotGraph.

Parameters:

• graph (PlotGraph) – Parent graph.

• loc (str, optional) – Legend location (e.g. best, upper right). Default best.

• title (str, optional) – Legend title.

• fontsize (int, optional) – Font size for legend entries.

• title_fontsize (int, optional) – Font size for the legend title.

• frameon (bool, optional) – Whether to draw the legend frame. Default True.

• ncols (int, optional) – Number of columns. Default 1.

• extra (dict, optional) – Extra kwargs passed to ax.legend.

__init__(graph: PlotGraph, **kwargs: int) → None

show() → None

Show the legend; This is called by PlotGraph.show().

class fluidsolve.plotlib.PlotButton(fig: PlotFigure, **kwargs: int)

Bases: object

Matplotlib button widget.

Parameters:

• fig (PlotFigure) – Parent figure.

• r (int | str) – Row index or slice in the widget GridSpec.

• c (int | str) – Column index or slice in the widget GridSpec.

• label (str, optional) – Button label text.

• color (str, optional) – Button background color.

• hovercolor (str, optional) – Button hover color.

• fun (Callable) – Callback executed when the button is clicked.

• extra (dict, optional) – Extra kwargs passed to the Button constructor.

__init__(fig: PlotFigure, **kwargs: int) → None

property widget: Any

setExtra(key: str, **kwargs: int) → None

Updates extra configuration values for a given key.

This method merges the provided keyword arguments into the existing dictionary stored under self._extra[key].

Parameters:

• key (str) – The key under which to store extra configuration values. Must be one of the allowed values.

• **values (Any) – Arbitrary keyword arguments to merge into the extra configuration dictionary.

show() → dict

Show the button; This is called by PlotFigure.show().

class fluidsolve.plotlib.PlotSlider(fig: PlotFigure, **kwargs: int)

Bases: object

Matplotlib slider widget.

Parameters:

• fig (PlotFigure) – Parent figure.

• r (int | str) – Row index or slice in the widget GridSpec.

• c (int | str) – Column index or slice in the widget GridSpec.

• label (str, optional) – Slider label text.

• color (str, optional) – Slider color.

• hovercolor (str, optional) – Slider hover color.

• vmin (int | float) – Minimum slider value.

• vmax (int | float) – Maximum slider value.

• vstep (int | float, optional) – Slider step size.

• vinit (int | float, optional) – Initial slider value.

• fun (Callable) – Callback executed on slider change.

• extra (dict, optional) – Extra kwargs passed to the Slider constructor.

__init__(fig: PlotFigure, **kwargs: int) → None

property widget: Any

setExtra(key: str, **kwargs: int) → None

Updates extra configuration values for a given key.

This method merges the provided keyword arguments into the existing dictionary stored under self._extra[key].

Parameters:

• key (str) – The key under which to store extra configuration values. Must be one of the allowed values.

• **values (Any) – Arbitrary keyword arguments to merge into the extra configuration dictionary.

show() → dict

Show the slider; This is called by PlotFigure.show().