ograph 1.0.0__py3-none-any.whl

docs/source/conf.py

@@ -0,0 +1,78 @@
+import sys
+import os
+from importlib.metadata import metadata
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = metadata('ograph')['Name']
+copyright = f"2024-2025, {metadata('ograph')['Author-email']}"
+description = f"{metadata('ograph')['Summary']}"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+# Add path to source directory
+print(f"Append path: {os.path.abspath(os.path.join('..', '..'))}")
+
+sys.path.append(os.path.abspath(os.path.join('..', '..')))
+
+
+extensions = ['nbsphinx',
+              'sphinx.ext.todo',
+              'sphinx.ext.viewcode',
+              'sphinx.ext.autodoc',
+              'sphinx.ext.napoleon',
+              'sphinx.ext.autosummary']
+
+# -- Options for Typing ------------------------------------------------------
+
+language = 'en-uk'
+
+autoclass_content = 'class'
+autosummary_generate = True
+
+autodoc_default_options = {
+    'undoc-members': True,
+    # Note: `autodoc_class_signature='separated'` causes `ClassDocumenter` to
+    #   register both `__init__` and `__new__` as special members.
+    # This overrides the default behaviour of not documenting private
+    #   members -- even if `__new__` is marked as private, Sphinx still
+    #   documents it.
+    # Override the override with `'exclude-members'`, so that `__new__`
+    #   is ABSOLUTELY not be documented ... until another patch breaks it.
+    'exclude-members': '__new__',
+
+}
+
+
+autodoc_class_signature = 'separated'
+autodoc_inherit_docstrings = False
+
+autodoc_member_order = 'bysource'
+autodoc_typehints = 'signature'
+autodoc_typehints_description_target = 'all'
+
+napoleon_use_rtype = False
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+html_css_files = ['styles.css',]
+templates_path = ['_templates']
+exclude_patterns: list[str] = []
+
+napoleon_include_special_with_doc = True
+
+rst_prolog = """
+.. role:: python(code)
+  :language: python
+  :class: highlight
+
+.. role:: arg(code)
+  :class: highlight
+
+"""

ograph/applications/__init__.py

@@ -0,0 +1,3 @@
+"""Utilities for plotting clusters of points.
+Initially designed to visualise swarm-based algorithms.
+"""

ograph/applications/swarm.py

@@ -0,0 +1,131 @@
+from typing import Optional, Callable
+import numpy as np
+from ..oplot import contour
+from ..oplot import Vec2D, Vec3D
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+
+
+def plot_positions(data: Vec2D | Vec3D,
+                   objective: Optional[Callable[[float, float], float]] = None,
+                   *,
+                   override_region: Optional[Vec2D] = None,
+                   override_margin: Optional[float] = None):
+    """Plot a sequence of collections of points as they
+    change over time.
+
+    Args:
+        data: Either a 2-D tensor or a 3-D tensor.
+            * If :arg:`data` is 2-D: data[t] is a single point. Plot
+                its change over time.
+            * If :arg:`data` is 3-D: data[t] is a collection oof
+                points. Plot the change of these points over
+                time.
+
+        objective: An objective function to be plotted as background.
+
+        override_region: Only plot points that fall in this region.
+
+        override_margin: A small margin to add to override_region.
+            Might make the plot prettier.
+    """
+    mort = np.array(data)
+
+    margin: float = 1 if override_margin is None\
+        else override_margin
+
+    x_min: float
+    x_max: float
+    y_min: float
+    y_max: float
+
+    x_min = np.min(mort.T[0])
+    x_max = np.max(mort.T[0])
+    y_min = np.min(mort.T[1])
+    y_max = np.max(mort.T[1])
+
+    if (override_region is not None):
+        x_min = override_region[0][0]
+        x_max = override_region[0][1]
+        y_min = override_region[1][0]
+        y_max = override_region[1][1]
+
+        mort =\
+            np.apply_along_axis(func1d=lambda arr: [
+                arr[0] if x_min < arr[0] < x_max else np.nan,
+                arr[1] if y_min < arr[1] < y_max else np.nan],
+                axis=2 if len(mort.shape) == 3 else 1,
+                arr=mort)
+
+    # Adjust margins. Matplotlib does not plot ticks that intersect
+    #   with borders of the graph; this trick makes plots prettier.
+    x_min -= margin
+    y_min -= margin
+    x_max += margin
+    y_max += margin
+
+    if objective is not None:
+        contour(fun=lambda x, y: objective(x, y),
+                x_range=(x_min, x_max),
+                y_range=(y_min, y_max))  # type: ignore
+
+    for i in range(len(mort)):
+        _xs: float
+        _ys: float
+        _xs, _ys = np.array(mort[i]).T
+        _intensity: float = i / len(mort)
+        plt.scatter(_xs, _ys, s=9,
+                    color=mpl.colormaps['RdYlGn'](_intensity),
+                    alpha=0.5)  # type: ignore
+
+    plt.xlim((x_min + margin, x_max - margin))
+    plt.ylim((y_min + margin, y_max - margin))
+
+
+def plot_bests(data: Vec2D,
+               best_selector: Callable[[Vec2D],
+                                       np.float64] = np.max,
+               best_label: str = "Best value",
+               all_label: str = "All values",) -> None:
+    """Plot a sequence of numbers against the best one.
+    The "best value" is plotted as a horizontal line.
+
+
+    Args:
+        data: A sequence of points to be plotted. Each
+            data[i] should be a 2-D point.
+
+        best_selector: A :class:`Callable` that returns the best
+            value in :arg:`data`. To plot a pre-determined, constant
+            best value, let :arg:`best_selector` always return that value.
+
+        best_label: Label for the best value.
+
+        all_label: Label for other values.
+    """
+    mort = data
+
+    plt.scatter(range(len(mort)),
+                mort,
+                s=12,
+                color="tab:blue",
+                facecolors="white",)
+
+    plt.vlines(x=range(len(mort)),
+               ymin=np.repeat(a=np.min(mort), repeats=len(mort)),
+               ymax=mort,
+               zorder=-9,
+               linewidth=0.8)
+
+    plt.hlines(best_selector(mort),
+               xmin=0,
+               xmax=len(mort),
+               color="tab:green",
+               label=best_label)
+
+    plt.plot([],
+             [],
+             color="tab:blue",
+             label=all_label)
+
+    plt.legend()

ograph/oconfig.py

@@ -0,0 +1,95 @@
+"""Utilities that configure the current plot
+or all plots in the current session.
+"""
+
+from typing import Optional
+
+import matplotlib.pyplot as plt
+import matplotlib as mlp
+import matplotlib.pylab as pylab
+from mpl_toolkits.mplot3d.axes3d import Axes3D  # type: ignore[import-untyped]
+
+from .ofig import ensure_axes_dimension
+
+
+def clear_axis_labels(enable: bool = False) -> None:
+    plt.gca().get_yaxis().set_ticks([])
+    plt.gca().get_xaxis().set_ticks([])
+
+
+def use_axis_lines(enable: bool = True) -> None:
+    plt.gca().axhline(y=0, color='DimGrey', linestyle="--")
+    plt.gca().axvline(x=0, color='DimGrey', linestyle="--")
+
+
+def set_font_size(size: int) -> None:
+    """Set the font size to :arg:`size`.
+
+    Effect:
+        Configure the current plot.
+    """
+    mlp.rc("font", size=size)
+
+
+def use_high_res() -> None:
+    """Set figures to render in higher resolution.
+
+    Set runtime configuration ``figure.dpi`` to 200.
+
+    Effect:
+        Configure all plots in the current session.
+    """
+    pylab.rcParams.update({'figure.dpi': 200})
+
+
+def use_low_res() -> None:
+    """Set figures to render in the default resolution.
+
+    Set runtime configuration ``figure.dpi`` to 100, the default value.
+
+    Effect:
+        Configure all plots in the current session.
+    """
+    pylab.rcParams.update({'figure.dpi': 100})
+
+
+def view_rotate(h_rotate: float, v_rotate: float) -> None:
+    """Rotate the current `Axes3D`.
+
+    @param h_rotate the degree to rotate vertically
+    @param v_rotate the degree to rotate horizontally
+    """
+    ax: Axes3D = plt.gca()  # type: ignore[no-any-unimported]
+    ensure_axes_dimension(ax, 3)
+    if (isinstance(ax, Axes3D)):  # Make mypy happy
+        ax.view_init(h_rotate, v_rotate)
+    else:
+        raise Exception("This should not happen."
+                        "The exception has been checked.")
+
+
+def view_axis_pos(pos: Optional[str]) -> None:
+    """Position labels and ticks of the current Axes3D.
+
+    Args:
+        pos: The position, one of :python:`'lower'`,
+            :python:`'upper'`,
+            :python:`'default'`,
+            :python:`'both'`,
+            :python:`'none'`,
+            and :python:`None`.
+    """
+    accepted_values: list[str] = ['lower', 'upper', 'default', 'both', 'none']
+    ax: Axes3D = plt.gca()  # type: ignore[no-any-unimported]
+    ensure_axes_dimension(ax, 3)
+    match pos:
+        case None:
+            ax.axis('off')
+        case other:
+            if other in accepted_values:
+                for axis in ax.xaxis, ax.yaxis, ax.zaxis:
+                    axis.set_label_position(other)
+                    axis.set_ticks_position(other)
+            else:
+                raise ValueError(f"The input {other} is not one of"
+                                 f"{str(accepted_values)}.")

ograph/ofig.py

@@ -0,0 +1,180 @@
+"""Utilities that create and check figures
+of different dimensions.
+"""
+
+import matplotlib.pyplot as plt
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+import matplotlib.pylab as pylab
+from mpl_toolkits.mplot3d.axes3d import Axes3D  # type: ignore[import-untyped]
+from typing import Tuple
+from typing import Optional
+from typing import Any
+import logging
+
+
+def fig2(xlims: Optional[Tuple[float, float]] = None,
+         ylims: Optional[Tuple[float, float]] = None,
+         arg: None | tuple[float, float, float, float] = None,
+         **kwargs: Any) -> Tuple[Figure, Axes]:
+    """Create then return a figure with a 2-dimensional axis.
+
+    Invoke :meth:`.pyplot.figure` to create figure, then
+    invoke :meth:`.pyplot.axes` to create an :class:`Axes`.
+    Return both objects in a tuple.
+
+    Args:
+        arg: :python:`None` or 4-tuple.
+
+            - :python:`None`: A new full window Axes is added using
+              ``subplot(**kwargs)``.
+
+            - 4-tuple of floats *rect* = ``(left, bottom, width, height)``:
+              Add a new Axes with dimensions *rect* in normalized
+              (0, 1) units, using :meth:`Figure.add_axes` on the current
+              figure.
+
+        xlims: Size of figure along the X axis
+        ylims: Size of figure along the Y axis
+        *args: Positional arguments to pass to :meth:`.pyplot.axes`
+        *kwargs: Keyword arguments to pass to :meth:`.pyplot.axes`
+    """
+    fig = plt.figure()
+    ax = plt.axes(arg, projection='rectilinear', **kwargs)
+    if (xlims is not None):
+        ax.set_xlim(*xlims)
+    if (ylims is not None):
+        ax.set_ylim(*ylims)
+    return (fig, ax)
+
+
+def fig3(xlims: Optional[Tuple[float, float]] = None,  # type: ignore[no-any-unimported] # noqa: E501
+         ylims: Optional[Tuple[float, float]] = None,
+         zlims: Optional[Tuple[float, float]] = None,
+         arg: None | tuple[float, float, float, float] = None,
+         **kwargs: Any) \
+        -> Tuple[Figure, Axes3D]:
+    """Create then return a figure with a 3-dimensional axis.
+
+    Invoke :meth:`.pyplot.figure` to create figure, then
+    invoke :meth:`.pyplot.axes` to create an :class:`Axes3D`.
+    Return both objects in a tuple.
+
+    Args:
+        arg: :python:`None` or 4-tuple.
+
+            - :python:`None`: A new full window Axes is added using
+              ``subplot(**kwargs)``.
+
+            - 4-tuple of floats *rect* = ``(left, bottom, width, height)``:
+              Add a new Axes with dimensions *rect* in normalized
+              (0, 1) units, using :meth:`Figure.add_axes` on the current
+              figure.
+
+        xlims: Size of figure along the X axis
+        ylims: Size of figure along the Y axis
+        ylims: Size of figure along the Y axis
+        *kwargs: Keyword arguments to pass to :meth:`.pyplot.axes`
+    """
+    fig = plt.figure()
+    ax: Axes3D = plt.axes(arg,  # type: ignore[no-any-unimported]
+                          projection='3d',
+                          **kwargs)
+
+    if (xlims is not None):
+        ax.set_xlim(*xlims)
+    if (ylims is not None):
+        ax.set_ylim(*ylims)
+    if (zlims is not None):
+        ax.set_zlim(*zlims)
+    return (fig, ax)
+
+
+class DimensionError(ValueError):
+    """Raised when the dimension of a figure does not agree
+    with the plot.
+
+    When this happens, something is going seriously wrong.
+    """
+    def __init__(self, expected: str, actual: str):
+        """
+        Args:
+            expected: Dimensions of the plot
+            actual: Dimensions of the figure
+        """
+        super().__init__(f"Dimension mismatch: expected {expected},"
+                         f" got {actual}")
+
+
+def ensure_axes_dimension(axes: Axes | Axes3D,  # type: ignore[no-any-unimported] # noqa: E501
+                          dim: int) -> None:
+    """Assert if the given axes is of the specified dimension.
+
+    Raises:
+        :class:`DimensionError`: if :arg:`dim` does not agree with the
+            dimension of :arg:`axes:.`
+    """
+    dimension_to_name = {2: "rectilinear", 3: "3d"}
+    if dim in dimension_to_name:
+        if (axes.name != dimension_to_name[dim]):
+            raise DimensionError(dimension_to_name[dim], axes.name)
+    else:
+        fig3() if dim == 3 else fig2()
+        logging.warning(f"The current projection is not `{dim}d`."
+                        f"A new {"Axes" if dim == 2 else "Axes3D"}"
+                        " is created instead.")
+
+
+def annotate(title: str,
+             xlabel: str,
+             ylabel: str,
+             zlabel: Optional[str] = None) -> None:
+    """Annotate the current figure.
+
+    Set :arg:`title`, :arg:`xlabel`, and :arg:`ylabel` of the current axes.
+    Also set runtime configurations that style annotations.
+
+    To reset the parameters, call:
+    :python:`matplotlib.rcParams.update(matplotlib.rcParamsDefault)`
+
+    Args:
+        title: Title of the figure
+        xlabel: Labels for the x axis
+        ylabel: Labels for the y axis
+        zlabel: Labels for the z axis
+
+    Effect:
+        Plot to the current active figure.
+        Change runtime configurations.
+    """
+
+    axes_label_size: str = "x-large"
+    plot_title_size: str = "x-large"
+
+    font = {'legend.fontsize': 'x-large',
+            'axes.titlesize': plot_title_size,
+            'axes.labelsize': axes_label_size,
+            'xtick.labelsize': axes_label_size,
+            'ytick.labelsize': axes_label_size,
+            'text.usetex': False,
+            'font.family': 'Open Sans',
+            'axes.titlepad': 15, }
+
+    ax: Axes | Axes3D = plt.gca()  # type: ignore[no-any-unimported]
+
+    pylab.rcParams.update(font)
+    ax.set_xlabel(xlabel, fontname='PT Serif')
+    ax.set_ylabel(ylabel, fontname='PT Serif')
+    if (zlabel is not None):
+        ensure_axes_dimension(ax, 3)
+        if (isinstance(ax, Axes3D)):
+            ax.set_zlabel(zlabel, fontname='PT Serif')
+        else:
+            raise Exception("This should not happen.")
+
+    my_fig = ax.get_figure()
+
+    if (my_fig is not None):
+        my_fig.suptitle(title, fontname='PT Serif')
+    else:
+        raise Exception("Somehow the Axes is not attached to a Figure. How?")

ograph/ofunc.py

@@ -0,0 +1,48 @@
+"""Test functions and matrices. Examples are
+the Himmelblau function and the unit cube.
+"""
+from numpy import array
+
+
+def rosenbrock(*args: float) -> float:
+    """Rosenbrock function.
+
+    Multi-dimensional test function where the global minimum is located
+    inside a flat valley.
+    """
+    result: float = 0
+    for i in range(len(args) - 1):
+        result += 100 * (args[i + 1] - args[i]**2)**2 + (1 - args[i])**2
+    return result
+
+
+def himmelblau(x: float, y: float) -> float:
+    """Himmelblau function.
+
+    2-dimensional test function with several minimum.
+    """
+    return (x ** 2 + y - 11) ** 2 + (x + y ** 2 - 7) ** 2
+
+
+#! Immutable 2-dimensional unit square.
+unit_square = array(
+    [[0, 0],
+     [0, 1],
+     [1, 0],
+     [1, 1]]
+)
+unit_square.flags.writeable = False
+
+
+#! Immutable 3-dimensional unit cube. Fancy!
+unit_cube = array(
+    [[0, 0, 0],
+     [1, 0, 0],
+     [0, 1, 0],
+     [0, 0, 1],
+     [1, 1, 0],
+     [0, 1, 1],
+     [1, 0, 1],
+     [1, 1, 1],]
+)
+unit_cube.flags.writeable = False

ograph/oplot.py

@@ -0,0 +1,563 @@
+"""Utilities that plot to the current Axes.
+"""
+import matplotlib.pyplot as plt
+import matplotlib.colors as colors
+import numpy as np
+import matplotlib as mpl
+from typing import overload
+
+from .ofig import ensure_axes_dimension
+
+from matplotlib.typing import ColorType
+
+from typing import Any, Self
+import math
+from numpy.typing import ArrayLike
+
+from typing import Optional, Sequence, Callable
+
+from scipy.spatial import ConvexHull, distance  # type: ignore[import-untyped]
+
+from matplotlib.patches import FancyArrowPatch
+
+from mpl_toolkits.mplot3d.art3d import Poly3DCollection  # type: ignore[import-untyped] # noqa: E501
+from mpl_toolkits.mplot3d.axes3d import Axes3D  # type: ignore[import-untyped]
+from mpl_toolkits.mplot3d.art3d import Line3DCollection
+from mpl_toolkits.mplot3d.proj3d import proj_transform  # type: ignore[import-untyped] # noqa: E501
+
+from numpy import ndarray
+
+from matplotlib.patches import Patch
+from matplotlib.text import Text
+from matplotlib.legend import Legend
+
+type Array1D = np.ndarray[tuple[Any],
+                          np.dtype[np.float64]]
+type Array2D = np.ndarray[tuple[Any, Any],
+                          np.dtype[np.float64]]
+type Array3D = np.ndarray[tuple[Any, Any, Any],
+                          np.dtype[np.float64]]
+
+type Sequence1D = Sequence[float]
+type Sequence2D = Sequence[Sequence[float]]
+type Sequence3D = Sequence[Sequence[Sequence[float]]]
+
+type Vec1D = Array1D | Sequence1D
+type Vec2D = Array2D | Sequence2D
+type Vec3D = Array3D | Sequence3D
+
+type Point2D = Vec1D
+type Point3D = Vec1D
+
+type Points2D = Vec2D
+type Points3D = Vec2D
+
+FILL_CONFIG: dict[str, Any] = {"alpha": 0.5}
+EDGE_CONFIG: dict[str, Any] = {"color": "black", "alpha": 1}
+NODE_CONFIG: dict[str, Any] = {"color": "black", "alpha": 0.5}
+CONTOUR_CMAP: str = "viridis"
+
+
+def heatmap(data: Vec2D,
+            xlabels: Optional[Sequence[str]] = None,
+            ylabels: Optional[Sequence[str]] = None) -> None:
+    """Plot a matrix to the current active axis as a heatmap.
+
+    Args:
+        data: A Numpy matrix.
+        xlabels: labels for cells along the x axis.
+        ylabels: labels for cells along the x axis.
+
+    Effects:
+        Plot at the current active axis.
+    """
+    if not isinstance(data, ndarray):
+        # If the input is not an numpy array, attempt to cast it into one.
+        data = np.array(data)
+
+    # Configure the size of the plot to accommodate the size of each cell
+    plt.rcParams["figure.figsize"] = [len(data) * math.sqrt(len(data)),
+                                      len(data[0]) * math.sqrt(len(data[0]))]
+
+    xlabels = xlabels if (xlabels is not None)\
+        else ["X" + str(i) for i, _ in enumerate(data[0])]
+    ylabels = ylabels if (ylabels is not None)\
+        else ["Y" + str(i) for i, _ in enumerate(data)]
+
+    ax = plt.gca()
+
+    ensure_axes_dimension(ax, 2)
+    ax.imshow(data, cmap="Greys")
+
+    ax.set_xticks(np.arange(len(xlabels)), labels=xlabels)
+    ax.set_yticks(np.arange(len(ylabels)), labels=ylabels)
+
+    plt.setp(ax.get_xticklabels(),
+             rotation=45,
+             ha="right",
+             rotation_mode="anchor")
+
+    max_cell_value = data.max()
+    min_cell_value = data.min()
+
+    for i in range(len(ylabels)):
+        for j in range(len(xlabels)):
+            cell_value_scale = max_cell_value - min_cell_value
+            ratio = (data[i, j] - min_cell_value) / cell_value_scale
+            ax.text(j, i, "{:.2f}".format(data[i, j]),
+                    ha="center",
+                    va="center",
+                    color="w" if ratio > .6 else "k")
+
+    my_fig = ax.get_figure()
+    if (my_fig is not None):
+        my_fig.tight_layout()  # type: ignore[union-attr]
+        # (When called on an `Axes`, ->get_figure(.) always returns a `Figure`)
+
+
+def chull(shape: Points2D | Points3D) -> None:
+    """Plot a convex hull to the current active axes.
+
+    Detect the shape of points by inspecting the first in the sequence.
+
+    Args:
+        shape: A sequence of 2- or 3-dimensional points.
+
+    Effects:
+        Plot at the current active axis.
+    """
+    # The checker only checks if the first element has the correct dimension.
+    # This is bad, but performant.
+    match len(shape[0]):
+        case 2:
+            _chull_2d(np.array(shape))  # type: ignore[arg-type]
+        case 3:
+            _chull_3d(np.array(shape))  # type: ignore
+        case _:
+            raise ValueError("Input must be either 2 or 3")
+
+
+def _chull_3d(shape: Array2D) -> None:
+    ax: Axes3D = plt.gca()  # type: ignore[no-any-unimported]
+    ensure_axes_dimension(ax, 3)
+
+    hull = ConvexHull(shape)
+    for s in hull.simplices:
+        tri = Poly3DCollection([shape[s]])
+
+        if "alpha" in FILL_CONFIG:
+            tri.set_alpha(FILL_CONFIG["alpha"])
+        if "color" in FILL_CONFIG:
+            tri.set_color(FILL_CONFIG["color"])
+
+        tri.set_edgecolor('none')
+        ax.add_collection3d(tri)
+        edges = []
+        if distance.euclidean(shape[s[0]], shape[s[1]])\
+                < distance.euclidean(shape[s[1]], shape[s[2]]):
+            edges.append((s[0], s[1]))
+            if distance.euclidean(shape[s[1]], shape[s[2]])\
+                    < distance.euclidean(shape[s[2]], shape[s[0]]):
+                edges.append((s[1], s[2]))
+            else:
+                edges.append((s[2], s[0]))
+        else:
+            edges.append((s[1], s[2]))
+            if distance.euclidean(shape[s[0]], shape[s[1]]) <\
+                    distance.euclidean(shape[s[2]], shape[s[0]]):
+                edges.append((s[0], s[1]))
+            else:
+                edges.append((s[2], s[0]))
+        for v0, v1 in edges:
+            ax.plot(xs=shape[[v0, v1], 0],
+                    ys=shape[[v0, v1], 1],
+                    zs=shape[[v0, v1], 2],
+                    **EDGE_CONFIG)
+
+    ax.scatter(shape[:, 0],
+               shape[:, 1],
+               shape[:, 2],
+               marker='o',
+               **NODE_CONFIG)
+
+
+def _chull_2d(points: Array2D) -> None:
+    ax = plt.gca()
+    ensure_axes_dimension(ax, 2)
+    hull = ConvexHull(points)
+    ax.plot(points[:, 0], points[:, 1], 'o', **NODE_CONFIG)  # type: ignore[arg-type] # noqa: E501
+    for simplex in hull.simplices:
+        ax.plot(points[simplex, 0],
+                points[simplex, 1],
+                **EDGE_CONFIG)  # type: ignore[arg-type]
+
+    ax.fill(points[hull.vertices, 0],
+            points[hull.vertices, 1],
+            lw=2,
+            **FILL_CONFIG)
+
+
+class BigArrow(FancyArrowPatch):
+    """An 2- or 3-dimensional arrow.
+
+    :meta private:
+    """
+    def __init__(self,
+                 start: Vec1D,
+                 end: Vec1D,
+                 *args: Any,
+                 **kwargs: Any):
+        default_styles = {
+            "mutation_scale": 30,
+            "arrowstyle": "-|>",
+            "linestyle": "--"
+        }
+        # start[i] for example can be either a number or a vector.
+        super().__init__((start[0], start[1]),  # type: ignore[arg-type]
+                         (end[0], end[1]),
+                         *args,
+                         **(kwargs | default_styles))
+        # Note that two copies of `start` and `end` are preserved:
+        #   One copy is passed to ->_posA_posB of the parent class; this copy
+        #       is used in `draw`.
+        #   the other copy is passed to ->start and ->end of this class; this
+        #       copt is used in do_3d_projections.
+        self.start = start
+        self.end = end
+
+    def draw(self: Self, renderer: Any) -> None:
+        super().draw(renderer)
+
+    def do_3d_projection(self: Self, renderer: Any = None) -> Any:
+        # The reference
+        #   https://github.com/matplotlib/matplotlib/blob/v3.8.2/lib/
+        #       mpl_toolkits/mplot3d/art3d.py#L998-L1065
+        #   appears to return np.min(tzs).
+        # Removing it does not seem to change anything. Still, just to be safe.
+        if self.axes is None or not isinstance(self.axes, Axes3D):
+            raise Exception("Rendered without axes")
+        else:
+            txs, tys, tzs = proj_transform(*zip(self.start, self.end),
+                                           self.axes.M)
+            self.set_positions((txs[0], tys[0]), (txs[1], tys[1]))
+            return np.min(tzs)
+
+
+@overload
+def arrow(start: Point2D, end: Point2D,
+          *args: Any,
+          **kwargs: Any) -> None:
+    pass
+
+
+# Suppress the error. This overload will never be matched
+#   since :class:`Point3D` and :class:`Point2D` alias
+#   the same thing. The overload is there for the user's knowledge.
+@overload
+def arrow(start: Point3D,  # type: ignore[overload-cannot-match]
+          end: Point3D,
+          *args: Any,
+          **kwargs: Any) -> None:
+    pass
+
+
+def arrow(start: Point2D | Point3D,
+          end: Point2D | Point3D,
+          *args: Any,
+          **kwargs: Any) -> None:
+    '''Plot an arrow to the current Axes or Axes3D.
+
+    Args:
+        start: The starting point of the arrow.
+        end: The ending point of the arrow.
+
+    '''
+    ax = plt.gca()
+    # Type checking `ax` is necessary, since the arrow
+    #       class can handle the difference.
+    #   Plotting to 2D (projection='rectilinear') Axes calls `draw`.
+    #   Plotting to 3D (projection='3d') calls do_3d_projection.
+    #   Still, this function might not work for other projections.
+    arrow = BigArrow(start, end, *args, **kwargs)
+    ax.add_artist(arrow)
+
+
+def plot(fun: Callable[[float], float],
+         x_range: tuple[float, float],
+         density: int = 1000,
+         *args: ArrayLike,
+         **kwargs: Any) -> None:
+    '''Plot a contour map to the current Axes or Axes3D.
+
+    Args:
+        fun: The function to plot.
+        x_range: A tuple of the beginning and end of the x axis.
+        density: Number of data point to plot. These points are
+            evenly spaced over (:arg:`x_range` * :arg:`y_range`).
+    '''
+    ax = plt.gca()
+    x_max: float = max(x_range)
+    x_min: float = min(x_range)
+    xs, ys = _make_ys(fun=fun,
+                      x_range=(x_min, x_max),
+                      density=density)
+    ax.plot(xs, ys, *args, **kwargs)
+
+
+def _make_zs(fun: Callable[[float, float], float],
+             x_range: tuple[float, float],
+             y_range: tuple[float, float],
+             density: int = 100,) -> tuple[ndarray, ndarray, ndarray]:
+
+    x_max: float = max(x_range)
+    x_min: float = min(x_range)
+    y_max: float = max(y_range)
+    y_min: float = min(y_range)
+
+    xs = np.arange(x_min, x_max, step=(x_max - x_min) / density)
+    ys = np.arange(y_min, y_max, step=(y_max - y_min) / density)
+
+    xs, ys = np.meshgrid(xs, ys)
+    zs = np.vectorize(fun)(xs, ys)
+
+    # This code is for functions that cannot be properly vectorised.
+    # zs = np.empty(shape=(len(ys), len(xs)))
+    # for i, x in enumerate(xs):
+    #     for j, y in enumerate(ys):
+    #         zs[j][i] = fun(x, y)
+
+    return (xs, ys, zs)
+
+
+def contour(fun: Callable[[float, float], float],
+            x_range: tuple[float, float],
+            y_range: tuple[float, float],
+            density: int = 100,
+            levels: int = 50,
+            cmap: str = CONTOUR_CMAP,
+            colorbar: bool = True,
+            alpha: float = 0.5) -> None:
+    '''Plot a contour map to the current Axes3D.
+
+    Args:
+        fun: The function to plot.
+        x_range: A tuple of the beginning and end of the x axis.
+        y_range: A tuple of the beginning and end of the y axis.
+        density: Number of point to plot. These points are
+            evenly spaced over (:arg:`x_range` * :arg:`y_range`).
+        levels: The number of contour lines.
+        cmap: The colour map used by the contour map.
+        colorbar: If True, draw the colour bar.
+    '''
+    ax = plt.gca()
+    xs, ys, zs = _make_zs(fun, x_range, y_range, density)
+    cs = ax.contour(xs, ys, zs, levels=levels, cmap=cmap,
+                    norm=colors.Normalize(vmin=zs.min(),
+                                          vmax=zs.max()),
+                    alpha=alpha)
+
+    current_figure = ax.get_figure()
+    if colorbar and current_figure is not None:
+        current_figure.colorbar(cs)
+
+
+def wireframe(fun:  # type: ignore[no-any-unimported]
+              # Reason: I'm not sure which import is causing this.
+              Callable[[float, float], float],
+              x_range: tuple[float, float],
+              y_range: tuple[float, float],
+              density: int = 100,
+              cmap: str = CONTOUR_CMAP,
+              alpha: float = 0.9,
+              **kwargs: dict[str, Any]) -> Line3DCollection:
+    '''Plot a wireframe map to the current Axes or Axes3D.
+
+    Args:
+        fun: The function to plot.
+        x_range: A tuple of the beginning and end of the x axis.
+        y_range: A tuple of the beginning and end of the y axis.
+        density: Number of point to plot. These points are
+            evenly spaced over :arg:`x_range`.
+        cmap: The colour map used by the contour map.
+        alpha: Alpha value (transparency) of the frame.
+    '''
+    ax: Axes3D = plt.gca()  # type: ignore[no-any-unimported]
+    xs, ys, zs = _make_zs(fun, x_range, y_range, density)
+    return ax.plot_wireframe(xs, ys, zs,
+                             cmap=cmap,
+                             norm=colors.Normalize(vmin=zs.min(),
+                                                   vmax=zs.max()),
+                             alpha=alpha,
+                             **kwargs)
+
+
+def surface(fun: Callable[[float, float], float],  # type: ignore[no-any-unimported] # noqa: E501
+            x_range: tuple[float, float],
+            y_range: tuple[float, float],
+            density: int = 100,
+            cmap: str = CONTOUR_CMAP,
+            colorbar: bool = True,
+            alpha: float = 0.9,) -> Line3DCollection:
+    ax: Axes3D = plt.gca()  # type: ignore[no-any-unimported]
+    xs, ys, zs = _make_zs(fun, x_range, y_range, density)
+    cs = ax.plot_surface(xs, ys, zs,
+                         cmap=cmap,
+                         norm=colors.Normalize(vmin=zs.min(), vmax=zs.max()),
+                         alpha=alpha,
+                         rstride=1,
+                         cstride=1,
+                         edgecolor='none')
+
+    if colorbar:
+        ax.get_figure().colorbar(cs)
+    return cs
+
+
+def _make_ys(fun: Callable[[float], float],
+             x_range: tuple[float, float],
+             density: int = 20) -> tuple[Vec1D, Vec1D]:
+    x_max: float = max(x_range)
+    x_min: float = min(x_range)
+    xs = np.linspace(x_min, x_max, num=density, dtype=np.float64)
+    ys = np.array([fun(x) for x in xs])
+    return xs, ys
+
+
+def stems(fun: Callable[[float], float],
+          x_range: tuple[float, float],
+          density: int = 30,
+          plot_links: bool = False,
+          *,
+          edge_args: dict[str, Any] = {},
+          node_args: dict[str, Any] = {},
+          fill_args: dict[str, Any] = {}) -> None:
+    """PLot a stem plot to the current Axes.
+
+    Args:
+        x_range: A tuple of the beginning and end of the x axis.
+        density: Number of point to plot. These points are
+            evenly spaced over :arg:`x_range`.
+        plot_links: If ``True``, then plot links.
+    """
+
+    xs, ys = _make_ys(fun, x_range, density)
+
+    stem(xs=xs,
+         ys=ys,
+         plot_links=plot_links,
+         edge_args=edge_args,
+         node_args=node_args,
+         fill_args=fill_args)
+
+
+def stem(xs: Vec1D, ys: Vec1D,
+         plot_links: bool = False,
+         *,
+         edge_args: dict[str, Any] = {},
+         node_args: dict[str, Any] = {},
+         fill_args: dict[str, Any] = {}) -> None:
+    """Plot a stem plot to the current Axes.
+    Similar to :meth:`Axes.stem`, but offers more control over style.
+    """
+
+    edge_args = EDGE_CONFIG | edge_args
+    # The default node style now borrows from edge style.
+    node_args = node_args
+    fill_args = FILL_CONFIG | fill_args
+
+    ax = plt.gca()
+
+    # Incorporate alpha into edge color. Because `->scatter(.)` does not allow
+    #   alpha to be specified for `edgecolors`, this is necessary.
+
+    # Suppressing this error because `.get` is maltyped to return
+    #   (Any | None). This is not very helpful.
+    edge_color: Optional[ColorType]\
+        = edge_args.get("color")  # type: ignore[assignment]
+    edge_alpha: Optional[float]\
+        = edge_args.get("alpha")  # type: ignore[assignment]
+    if edge_color is not None and edge_alpha is not None:
+        line_color = mpl.colors.colorConverter.to_rgba(
+            edge_color,
+            edge_alpha
+        )
+
+    old_x = old_y = None
+
+    if (plot_links):
+        ax.plot((min(xs), max(xs)), (0, 0),
+                color=line_color,
+                linewidth=1,
+                zorder=-1)
+
+    for (x, y) in zip(xs, ys):
+        ax.plot([x, x], [0, y],
+                zorder=0,
+                linewidth=1,
+                **edge_args)
+
+        if (plot_links):
+            if old_x is not None and old_y is not None:
+                #Hull it
+                ax.plot((old_x, x), (old_y, y), color="#696969", linewidth=0.5,
+                        zorder=-1)
+                ax.fill_between((old_x, x), (old_y, y),
+                                zorder=-2,
+                                color="#F5F5F5", **fill_args)
+        old_x = x
+        old_y = y
+
+    ax.scatter(xs, ys, zorder=4,
+               facecolor=fill_args.get("color", "white"),
+               edgecolors=line_color,
+               linewidth=1.5,
+               **node_args)
+
+
+#: Legacy alias for :meth:`stem`.
+shatter = stem
+
+
+def _add_patch_to_current_legend(patch: Patch, label: str) -> None:
+    ax = plt.gca()
+    legend = [c for c in ax.get_children() if isinstance(c, Legend)][0]
+
+    handles = legend.legend_handles
+    labels = legend.texts
+
+    handles.append(patch)
+    labels.append(Text(0, 0, label))
+
+    plt.legend(handles)
+
+
+def patch(facecolor: ColorType,
+          label: str,
+          alpha: float = 1,
+          width: float = 1,
+          height: float = 0.8) -> None:
+    """Add and label a rectangular colour patch to the current
+    plot.
+
+    Args:
+        label: Label to the patch.
+        alpha: Alpha value of the patch.
+        width: Width of the patch.
+        height: Height of the patch.
+    """
+    new_patch = Patch(facecolor=facecolor,
+                      edgecolor=facecolor,
+                      label=label,
+                      alpha=alpha)
+
+    if plt.gca().get_legend() is None:
+        plt.gca().legend(handles=[new_patch],
+                         handlelength=width,
+                         handleheight=height,
+                         loc="lower left")
+    else:
+        _add_patch_to_current_legend(Patch(facecolor=facecolor,
+                                           edgecolor=facecolor,
+                                           label=label,
+                                           alpha=alpha),
+                                     label=label)

ograph/py.typed

@@ -0,0 +1 @@
+Whatever

ograph-1.0.0.dist-info/METADATA

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: ograph
+Version: 1.0.0
+Summary: Experimental Matplotlib API
+Author-email: Lyodine <lyodine@github.com>
+Project-URL: Documentation, https://yidingli.com/docs/ograph/
+Project-URL: Repository, https://yidingli.com/projects/ograph/
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12.0
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: matplotlib>=3.8.4
+Dynamic: license-file
+
+<p align="center">
+<img src="./media/alternative_logo.png" width=100>
+</p>
+
+
+# OGraph
+
+A lightweight Matplotlib wrapper.
+
+## Installation
+
+Install from PyPI:
+
+```shell
+pip install ograph
+```
+
+Install from source:
+
+```
+pip install .
+```
+
+Please see [documentation](https://yidingli.com/projects/ograph/docs/install-and-build.html) for detailed instructions.
+
+## Components
+
+The library have the following modules:
+
+| Component                                          | Description                |
+| -------------------------------------------------- | -------------------------- |
+| [ofig](./ograph/ofig/) | Create and check the dimensions of plots |
+| [oplot](./ograph/oplot/) | Plot to the current axes  |
+| [oconfig](./ograph/oconfig/)                       | Configure plots            |
+| [ofunc](./ograph/ofunc/) | Supply test functions and matrices |
+| [applications.swarm](./ograph/applications/swarm/) | Plot point clusters |
+
+The ograph.oplot library contains the following plotters: 
+
+| Plotter   | Dimension of Plot | Data               |
+| --------- | ----------------- | ------------------ |
+| heatmap   | 2                 | $M\times N$ matrix |
+| chull     | 2, 3              | $R^2$ or $R^3$     |
+| arrow     | 2, 3              | $R^2$ or $R^3$     |
+| plot      | 2                 | $R\rightarrow R$   |
+| wireframe | 3                 | $R^2\rightarrow R$ |
+| surface   | 3                 | $R^2\rightarrow R$ |
+| stems     | 2                 | $R\rightarrow R$   |
+| stem      | 2                 | `xs`  and `ys      |
+| patch     | Any               | Colours and labels |
+
+The `application.swarm` module contains the following plotters:
+
+
+plot_positions 2 list[R^2] or list[list[R^2]]
+plot_bests 2 list[R^2]

ograph-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+docs/source/conf.py,sha256=_UfMQZptjyv84FrdYGo3yI6ED5DdtmKD6xnP9PG4CuQ,2473
+ograph/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ograph/oconfig.py,sha256=AegLHVKt9yOzTaSG-7qARmUinISJsLh3FjdUcxcF8ck,2883
+ograph/ofig.py,sha256=fPw6fuWsY5rh5xnds0GP0jZrA199GASl1w5rHN3bisc,6325
+ograph/ofunc.py,sha256=Y8yrnU8KSIe82vHRJZXnHuYig9n3lDuyOgcDBRjwcuc,1068
+ograph/oplot.py,sha256=yGxyR2X9kZRRsXaHkpAyakvo-hEMZzcMu3f3Uu9gW1k,19435
+ograph/py.typed,sha256=5JcTXlyUgcObw15iknvFO3ytTtMZPxgx5j7maXO5cLE,8
+ograph/applications/__init__.py,sha256=TTgep3kTCzWGUQL1Bg2rprpyoP8tT7Ru5emWw5tgYUc,109
+ograph/applications/swarm.py,sha256=R5UyhGPehEhCq3sdT99DTPhw4r1QI7dYtZT2TC6yW78,4165
+ograph-1.0.0.dist-info/licenses/LICENSE.md,sha256=nQuuPcBjE5l5-ARuWaTQBbL0AIqq5-P_5myIcxqajfE,1086
+ograph-1.0.0.dist-info/METADATA,sha256=0Rzj6DYTnMwZ7c4GEHoM59r_FYvKA7_aI34sJuM8Wjo,2590
+ograph-1.0.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+ograph-1.0.0.dist-info/top_level.txt,sha256=cPMrKsahSsD8lnF-ud1xpxH8vbs22gfyrTWq6EH1fk0,12
+ograph-1.0.0.dist-info/RECORD,,

ograph-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ograph-1.0.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024-2025 Lyodine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

ograph-1.0.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+docs
+ograph