PlotSteady

class timflow.steady.plots.PlotSteady(ml)

Bases: timflow.plots.plots.PlotBase

Plotting functionality for timflow.steady models.

Provides methods for visualizing model layouts, contours, pathlines, and other model results.

contour(win, ngr=20, layers=0, levels=20, layout=True, labels=True, decimals=1, color=None, cmap=None, ax=None, figsize=None, legend=True, return_contours=False, parallel=False, **kwargs)

Head contour plot.

Parameters:

• win (list or tuple) – [xmin, xmax, ymin, ymax]

• ngr (scalar, tuple or list) – if scalar: number of grid points in x and y direction if tuple or list: nx, ny, number of grid points in x and y directions

• layers (integer, list or array) – layers for which grid is returned

• levels (integer or array (default 20)) – levels that are contoured

• layout (boolean (default True)) – plot layout of elements

• labels (boolean (default True)) – print labels along contours

• decimals (integer (default 0)) – number of decimals of labels along contours

• color (str or list of strings) – color of contour lines

• cmap (str or matplotlib colormap) – colormap for contour lines, only used if color is None

• ax (matplotlib.Axes) – axes to plot on, default is None which creates a new figure

• figsize (tuple of 2 values (default is mpl default)) – size of figure

• legend (list or boolean (default True)) – add legend to figure if list of strings: use strings as names in legend

• return_contours (bool, optional) – if True, return list of contour sets for each contoured layer

• parallel (bool or int, optional) – if True, compute head grid in parallel using multiprocessing, default is False. If int is provided, it is interpreted as the number of processes to use.

• **kwargs – additional keyword arguments passed to ax.contour()

Returns:

• ax (matplotlib.Axes) – axes with plot

• cs (list) – of contour sets for each contoured layer, only if return_contours=True

headalongline(x, y, layers=None, ax=None, sstart=0, **kwargs)

Plot head along the line provided by x and y coordinates.

Deprecated since version 0.3.0: Use head_along_line() instead.

Parameters:

• x (array) – x-coordinates of the line

• y (array) – y-coordinates of the line

• layers (integer, list or array) – layers for which head is plotted, default is all layers

• ax (matplotlib.Axes) – axes to plot on, default is None which creates a new figure

• **kwargs – additional keyword arguments passed to ax.plot()

Returns:

ax – axes with plot

Return type:

matplotlib.Axes

head_along_line(x1=0, x2=1, y1=0, y2=0, npoints=100, layers=None, sstart=0, color=None, lw=1.5, figsize=None, ax=None, legend=True, grid=True, **kwargs)

Plot head along line.

Parameters:

• x1 (float) – start and end coordinates of line

• x2 (float) – start and end coordinates of line

• y1 (float) – start and end coordinates of line

• y2 (float) – start and end coordinates of line

• npoints (int) – number of points along line

• layers (int, list or array) – layers for which head is plotted, default is all layers

• ax (matplotlib.Axes) – axes to plot on, default is None which creates a new figure

• **kwargs – additional keyword arguments passed to ax.plot()

Returns:

ax – axes with plot

Return type:

matplotlib.Axes

vcontour(win, n, levels=20, labels=True, decimals=0, color=None, cmap=None, vinterp=True, nudge=1e-06, ax=None, figsize=None, layout=True, horizontal_axis: Literal['x', 'y', 's'] = 's', return_contours=False, **kwargs)

Head contour plot in vertical cross-section.

Parameters:

• win (list or tuple) – [xmin, xmax, ymin, ymax]

• n (integer) – number of grid points along cross-section

• levels (integer or array (default 20)) – levels that are contoured

• labels (boolean (default True)) – print labels along contours

• decimals (integer (default 0)) – number of decimals of labels along contours

• color (str or list of strings) – color of contour lines

• cmap (str or matplotlib colormap) – colormap for contour lines, only used if color is None

• vinterp (boolean) – when True, interpolate between centers of layers when False, constant value vertically in each layer

• nudge (float) – small value to nudge grid points away from boundaries

• ax (matplotlib.Axes) – axes to plot on, default is None which creates a new figure

• figsize (tuple of 2 values (default is mpl default)) – size of figure

• layout (boolean) – plot layout if True

• horizontal_axis (str, optional) – ‘s’ for distance along cross-section on x-axis (default) ‘x’ for using x-coordinates on x-axis ‘y’ for using y-coordinates on x-axis

• return_contours (bool) – if True, return contour set, default is False

• **kwargs – additional keyword arguments passed to ax.contour()

Returns:

cs

Return type:

contour set

vcontour_stream_function(x1, x2, nx, levels, labels=False, decimals=0, color=None, cmap=None, ax=None, figsize=None, layout=True, nudge=1e-06, radial=False, horizontal_axis: Literal['x', 'y', 's'] = 's', **kwargs)

Contour stream_function.

Only applicable to models where flow is 1D (along a line), e.g. flow in a vertical cross-section or flow in a radially symmetric model.

Parameters:

• x1 (scalar) – left edge of contour domain

• x2 (scalar) – right edge of contour domain

• nx (integer) – number of grid points along cross-section

• levels (integer or array (default 20)) – levels that are contoured

• labels (boolean (default True)) – print labels along contours

• decimals (integer (default 0)) – number of decimals of labels along contours

• color (str or list of strings) – color of contour lines

• cmap (str or matplotlib colormap) – colormap for contour lines, only used if color is None

• ax (matplotlib axis) – add plot to specified axis

• figsize (tuple of 2 values (default is mpl default)) – size of figure

• layout (boolean) – plot layout if True

• nudge (float) – first value is computed nudge from the specified x1 and x2

• radial (bool) – if True, compute stream function for radially symmetric flow. Default is False.

• horizontal_axis (str, optional) – ‘s’ for distance along cross-section on x-axis (default) ‘x’ for using x-coordinates on x-axis ‘y’ for using y-coordinates on x-axis

Returns:

ax

Return type:

axis

tracelines(xstart, ystart, zstart, hstepmax, vstepfrac=0.2, tmax=1000000000000.0, nstepmax=100, silent='.', color=None, orientation: Literal['hor', 'ver', 'both'] = 'hor', win=None, ax=None, figsize=None, *, return_traces=False, **kwargs)

Plot or compute multiple pathlines.

Parameters:

• xstart (array) – x-coordinates of starting locations

• ystart (array) – y-coordinates of starting locations

• zstart (array) – z-coordinates of starting locations

• hstepmax (scalar) – maximum horizontal step size [L]

• vstepfrac (scalar) – maximum vertical step as fraction of layer thickness

• tmax (scalar) – maximum travel time

• nstepmax (int) – maximum number of steps

• silent (string) – if ‘.’, prints dot upon completion of each traceline

• color (string) – matplotlib color of traceline

• orientation (('hor', 'ver', 'both')) – ‘hor’ for horizontal, ‘ver’ for vertical ‘both’ for horizontal above vertical

• win (list) – list with [xmin, xmax, ymin, ymax]

• ax (matplotlib.Axes or list of Axes) – axes to plot on, default is None which creates a new figure

• return_traces (boolean) – if True, also return one trace result dict per pathline

• **kwargs – kwargs are passed on to LineCollections for plotting. For backward compatibility a deprecated metadata keyword is accepted and removed. metadata=False emits a DeprecationWarning; results always use the dict form from traceline().

Returns:

• ax (matplotlib.Axes or list of Axes) – axes with plot

• traces (list of dict) – only if return_traces is True; each dict matches traceline() output.

plot_capture_zone(well, nt=10, zstart=None, hstepmax=20, vstepfrac=0.2, tmax=365, nstepmax=100, silent='.', color=None, orientation='hor', win=None, ax=None, figsize=None, *, return_traces=False, **kwargs)

Plot a capture zone.

Parameters:

• well (timflow.steady.Well, list of wells or list of str) – well element from which capture zone is started. Accepts a well object, a list of wells, or a list of well names.

• nt (int) – number of path lines

• zstart (scalar) – starting elevation of the path lines. Halfway aquifer thickness if None

• hstepmax (scalar) – maximum step in horizontal space

• vstepfrac (float) – maximum fraction of aquifer layer thickness during one step

• tmax (scalar) – maximum time

• nstepmax (scalar(int)) – maximum number of steps

• silent (boolean or string) – True (no messages), False (all messages), or ‘.’ (print dot for each path line)

• color (color)

• orientation (string) – ‘hor’ for horizontal, ‘ver’ for vertical, or ‘both’ for both

• win (array_like (length 4)) – [xmin, xmax, ymin, ymax]

• axes (matplotlib.Axes, tuple of 2 matplotlib.Axes, or None) – axes to plot on, default is None which creates a new figure

• figsize (tuple of integers, optional, default: None) – width, height in inches.

• return_traces (boolean (default False)) – return the traces instead of plotting

• **kwargs – kwargs are passed on to LineCollections for plotting.

Returns:

• ax (matplotlib.Axes or list of Axes) – axes with plot

• traces (list of list of dict) – only if return_traces is True; outer list is per well, inner list matches tracelines() with return_traces=True

plotcapzone(well, nt=10, zstart=None, hstepmax=20, vstepfrac=0.2, tmax=365, nstepmax=100, silent='.', color=None, orientation='hor', win=None, ax=None, figsize=None, *, return_traces=False, **kwargs)

Plot a capture zone.

Deprecated since version Use: plot_capture_zone() instead. This method will be removed in a future version.

Parameters:

• well (timflow.steady.Well, list of wells or list of str) – well element from which capture zone is started. Accepts a well object, a list of wells, or a list of well names.

• nt (int) – number of path lines

• zstart (scalar) – starting elevation of the path lines. Halfway aquifer thickness if None

• hstepmax (scalar) – maximum step in horizontal space

• vstepfrac (float) – maximum fraction of aquifer layer thickness during one step

• tmax (scalar) – maximum time

• nstepmax (scalar(int)) – maximum number of steps

• silent (boolean or string) – True (no messages), False (all messages), or ‘.’ (print dot for each path line)

• color (color)

• orientation (string) – ‘hor’ for horizontal, ‘ver’ for vertical, or ‘both’ for both

• win (array_like (length 4)) – [xmin, xmax, ymin, ymax]

• axes (matplotlib.Axes, tuple of 2 matplotlib.Axes, or None) – axes to plot on, default is None which creates a new figure

• figsize (tuple of integers, optional, default: None) – width, height in inches.

• return_traces (boolean (default False)) – return the traces instead of plotting

• **kwargs – For backward compatibility only: deprecated metadata keyword (see tracelines()).

Returns:

• ax (matplotlib.Axes or list of Axes) – axes with plot

• traces (list of list of dict) – only if return_traces is True; outer list is per well, inner list matches tracelines() with return_traces=True

quiver_xy(x, y, z, normalize=False, ax=None, figsize=None, parallel=False, **kwargs)

Quiver plot of velocity field in xy-plane.

Parameters:

• x (1D arrays) – coordinates of grid points in x and y directions

• y (1D arrays) – coordinates of grid points in x and y directions

• z (scalar) – z-coordinate of plane in which to plot velocity field

• normalize (bool) – if True, normalize velocity vectors to have length 1

• ax (matplotlib.Axes) – axes to plot on, default is None which creates a new figure

• figsize (tuple of 2 values) – size of figure

• parallel (bool) – if True, compute velocity grid in parallel using multiprocessing, default is False

• **kwargs – additional keyword arguments passed to ax.quiver()

Returns:

ax – axes with plot

Return type:

matplotlib.Axes

quiver_z(x, y, z, normalize=False, ax=None, figsize=None, parallel=False, **kwargs)

Quiver plot of velocity field in xz- or yz-plane.

Parameters:

• x (1D arrays) – coordinates of grid points in x and y directions

• y (1D arrays) – coordinates of grid points in x and y directions

• z (scalar) – z-coordinate of plane in which to plot velocity field

• normalize (bool) – if True, normalize velocity vectors to have length 1

• ax (matplotlib.Axes) – axes to plot on, default is None which creates a new figure

• figsize (tuple of 2 values) – size of figure

• parallel (bool) – if True, compute velocity grid in parallel using multiprocessing, default is False

• **kwargs – additional keyword arguments passed to ax.quiver()

Returns:

ax – axes with plot

Return type:

matplotlib.Axes

topview(win=None, ax=None, figsize=None, layers=None)

Plot top-view.

This method plots all elements (in specified layers).

Parameters:

• win (list or tuple) – [x1, x2, y1, y2]

• ax (matplotlib.Axes, optional) – axes to plot on, default is None which creates a new figure

• figsize (tuple of 2 values) – size of figure

• layers (int or list of ints, optional) – layers to plot, default is None which plots elements in all layers

Returns:

ax – axes with plot

Return type:

matplotlib.Axes

xsection(xy: list[tuple[float]] | None = None, labels: bool = True, params: bool = False, names: bool = False, ax=None, fmt: str | None = None, units: dict | None = None, layer_names: tuple | dict = ('aquifer', 'leaky layer'), hstar: float | None = None, boundaries: bool = True, horizontal_axis: Literal['x', 'y', 's'] = 's', sep: Literal[', ', '\n'] = ', ', ha: str = 'center', **kwargs)

Plot cross-section of model.

This is a shared method that handles cross-section plotting for both steady and transient models. The method automatically adapts the parameter labels based on the model type.

Parameters:

• xy (list of tuples, optional) – list of tuples with coordinates of the form [(x0, y0), (x1, y1)]. If not provided, a cross section with length 1 is plotted for 3D models. For cross-section models the left and right are derived from the elements.

• labels (bool, optional) – add layer numbering labels to plot

• params (bool, optional) – add parameter values to plot

• names (bool, optional) – add inhomogeneity names to plot, only supported for cross-section models.

• ax (matplotlib.Axes, optional) – axes to plot on, default is None which creates a new figure

• fmt (str, optional) – format string for parameter values, e.g. ‘.2f’ for 2 decimals

• units (dict, optional) – dictionary with units keyed by timflow parameter names, e.g. {‘kaq’: ‘m/d’, ‘c’: ‘d’, ‘Saq’: ‘m$^{-1}$’, ‘Sll’: ‘m$^{-1}$’}

• layer_names (2-tuple or dict) – words to use for aquifers and leaky layers, default is (‘aquifer’, ‘leaky layer’). If a dict is provided, it maps layer type and number to a name, e.g. {‘aquifer 0’: ‘top aquifer’, ‘leaky layer 1’: ‘clay layer’}

• horizontal_axis (str) – ‘s’ for distance along cross-section on x-axis (default) ‘x’ for using x-coordinates on x-axis ‘y’ for using y-coordinates on x-axis

• hstar (float, optional) – override hstar value for plotting water level in transient 1D inhomogeneities that use hstar, useful for plotting pretty cross-sections when reference level is not equal to 0.

• boundaries (bool, optional) – whether to plot aquifer boundaries for cross-section models, default is True

• sep (str) – Separator between parameters, either “, “ or “n”

• ha (str, optional) – Horizontal alignment for parameter labels. Defaults to “center”.

• **kwargs – passed on to all ax.plot calls

Returns:

ax – axes with plot

Return type:

matplotlib.Axes

topview_and_xsection(win=None, axes=None, figsize=None, topfigfrac=0.8, layers=None, horizontal_axis: Literal['x', 'y'] = 'x', **xsection_kwargs)

Plot top-view above and cross-section below.

This method plots the top-view and cross-section side by side in a single figure.

Parameters:

• win (list or tuple) – [x1, x2, y1, y2]

• axes (list of matplotlib.Axes, optional) – axes to plot on, default is None which creates a new figure

• figsize (tuple of 2 values) – size of figure

• topfigfrac (float) – fraction of figure width for top-view plot

• layers (int or list of ints, optional) – layers to plot, default is None which plots elements in all layers

• horizontal_axis (str) – ‘x’ for using x-coordinates on x-axis ‘y’ for using y-coordinates on x-axis

• **xsection_kwargs (dict) – additional keyword arguments passed to xsection()

Returns:

axes – axes with plots [topview_ax, xsection_ax]

Return type:

list of matplotlib.Axes

vcontour_array(x, y, arr, levels=20, labels=True, decimals=0, color=None, cmap=None, vinterp=True, ax=None, figsize=None, layout=True, horizontal_axis: Literal['x', 'y', 's'] = 's', return_contours=False, **kwargs)

Contour array in vertical cross-section.

This method derives the vertical coordinates based on the model layers. It assumes that the input array has shape (layers, len(x)). Use vinterp to control whether to interpolate between layer centers or use constant values within each layer.

Parameters:

• x (1D array) – horizontal coordinates of grid points

• y (1D array) – horizontal coordinates of grid points

• arr (2D array) – array to contour, shape (naq, len(x))

• levels (integer or array (default 20)) – levels that are contoured

• labels (boolean (default True)) – print labels along contours

• decimals (integer (default 0)) – number of decimals of labels along contours

• color (str or list of strings) – color of contour lines

• cmap (str or matplotlib colormap) – colormap for contour lines, only used if color is None

• vinterp (boolean) – when True, interpolate between centers of layers when False, constant value vertically in each layer

• ax (matplotlib.Axes) – axes to plot on, default is None which creates a new figure

• figsize (tuple of 2 values (default is mpl default)) – size of figure

• layout (boolean) – plot layout if True

• horizontal_axis (str, optional) – ‘s’ for distance along cross-section on x-axis (default) ‘x’ for using x-coordinates on x-axis ‘y’ for using y-coordinates on x-axis

• return_contours (bool) – if True, return contour set, default is False

• **kwargs – additional keyword arguments passed to ax.contour()

Returns:

cs

Return type:

contour set