fullplot 0.1.1__py3-none-any.whl → 2.0.0__py3-none-any.whl

fullplot/__init__.py

@@ -1,25 +1,16 @@
-"""FullPlot public package interface.
-
-FullPlot is a small engineering-data plotting package centered on HDF5 files,
-reusable one-dimensional ``Trace`` objects, shared ``TimeAxis`` objects, and
-rectangular-grid map generation. Most users import the package as ``fullplot``
-or ``fplt`` and use the names re-exported here instead of importing from the
-internal modules directly.
-"""
+"""FullPlot public package interface."""
 
 from fullplot.cli import main
 from fullplot.fullplot import (
     AmbiguousDatasetError,
     DatasetNotFoundError,
     FullPlotError,
-    H5File,
     PlotDataError,
     TimeAxis,
     Trace,
     VALID_TRACE_ROLES,
     list,
     map,
-    open,
     plot,
     read,
     show,
@@ -29,6 +20,7 @@ from fullplot.fullplot import (
     values,
     write_traces,
 )
+from fullplot.linearization import H5File, Linearization, LinearizationError, open
 from fullplot.maps import (
     Axis,
     FullPlotMapError,
@@ -37,7 +29,7 @@ from fullplot.maps import (
     generate_map,
 )
 
-__version__ = "0.1.1"
+__version__ = "2.0.0"
 
 __all__ = [
     "__version__",
@@ -45,6 +37,8 @@ __all__ = [
     "DatasetNotFoundError",
     "AmbiguousDatasetError",
     "PlotDataError",
+    "LinearizationError",
+    "Linearization",
     "TimeAxis",
     "Trace",
     "VALID_TRACE_ROLES",

fullplot/fullplot.py

@@ -414,6 +414,20 @@ class TimeAxis:
     def __getitem__(self, item):
         return self.values[item]
 
+    def __str__(self) -> str:
+        """Return a compact summary of the active time range."""
+        active_label = "sample" if self.count == 1 else "samples"
+        window = ""
+        if self.has_window:
+            start, stop = self.window_range
+            start_text = "start" if start is None else f"{start:g}"
+            stop_text = "end" if stop is None else f"{stop:g}"
+            window = f", window={start_text} to {stop_text}"
+        return (
+            f"TimeAxis({self.name!r}, {self.count}/{self.raw_count} {active_label}, "
+            f"range={self.tmin:g} to {self.tmax:g}, zero={self.zero:g}{window})"
+        )
+
 class Trace:
     """Prepared one-dimensional engineering data series.
 
@@ -490,6 +504,17 @@ class Trace:
         self.role = _normalize_trace_role(role)
         self.attrs = {} if attrs is None else dict(attrs)
 
+    def __str__(self) -> str:
+        """Return a compact summary without printing the underlying arrays."""
+        finite_count = int(np.count_nonzero(self.finite))
+        count = len(self.x)
+        sample_label = "sample" if count == 1 else "samples"
+        return (
+            f"Trace({self.name!r}, role={self.role!r}, {count} {sample_label}, "
+            f"x={self.tmin:g} to {self.tmax:g}, "
+            f"finite={finite_count}/{count})"
+        )
+
     @property
     def x(self) -> np.ndarray:
         """Current x-values, including shared alignment and windowing."""
@@ -1314,6 +1339,10 @@ class H5File:
         self.filename = str(self.filename)
         self.root = _clean_root(self.root)
 
+    def __str__(self) -> str:
+        """Return the selected file and HDF5 root."""
+        return f"H5File({self.filename!r}, root={self.root!r})"
+
     def at(self, group: str) -> "H5File":
         """
         Return a new H5File scoped to a specific HDF5 group.

fullplot/linearization.py

@@ -0,0 +1,335 @@
+"""Read FullFlow state-space linearizations from HDF5 files."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import isclose
+from pathlib import Path
+from typing import Any
+
+import h5py
+import numpy as np
+
+from .fullplot import FullPlotError, H5File as _H5File, open as _open
+
+
+class LinearizationError(FullPlotError):
+    """An HDF5 linearization is missing, ambiguous, or malformed."""
+
+
+@dataclass
+class Linearization:
+    """One saved continuous-time state-space model and its operating point."""
+
+    A: np.ndarray
+    B: np.ndarray
+    C: np.ndarray
+    D: np.ndarray
+    x0: np.ndarray
+    xdot0: np.ndarray
+    u0: np.ndarray
+    y0: np.ndarray
+    states: tuple[str, ...]
+    inputs: tuple[str, ...]
+    outputs: tuple[str, ...]
+    time: float
+    diagnostics: dict[str, Any]
+    model_options: dict[str, Any]
+    solver: str
+    run: str
+    network: str
+    path: str
+
+    def __str__(self) -> str:
+        """Return a compact summary suitable for interactive printing."""
+        nx = len(self.states)
+        nu = len(self.inputs)
+        ny = len(self.outputs)
+        identity = " / ".join(
+            item for item in (self.network, self.solver, self.run) if item
+        )
+        title = "Linearization" if not identity else f"Linearization: {identity}"
+        dimensions = ", ".join((
+            f"{nx} state{'s' if nx != 1 else ''}",
+            f"{nu} input{'s' if nu != 1 else ''}",
+            f"{ny} output{'s' if ny != 1 else ''}",
+        ))
+        return "\n".join((
+            title,
+            f"  Time: {self.time:g} s",
+            f"  Dimensions: {dimensions}",
+            f"  Matrices: A{self.A.shape}, B{self.B.shape}, "
+            f"C{self.C.shape}, D{self.D.shape}",
+            f"  Path: {self.path}",
+        ))
+
+
+def _decode(value: Any) -> Any:
+    if isinstance(value, bytes):
+        return value.decode("utf-8")
+    if isinstance(value, np.generic):
+        return _decode(value.item())
+    if isinstance(value, np.ndarray):
+        return [_decode(item) for item in value.tolist()]
+    return value
+
+
+def _labels(group: h5py.Group, name: str) -> tuple[str, ...]:
+    if name not in group or not isinstance(group[name], h5py.Dataset):
+        raise LinearizationError(f"Missing {name!r} labels in {group.name}.")
+    values = group[name][()]
+    if np.asarray(values).ndim != 1:
+        raise LinearizationError(f"{group.name}/{name} must be a 1D label array.")
+    decoded = tuple(_decode(value) for value in values)
+    if any(not isinstance(value, str) for value in decoded):
+        raise LinearizationError(f"{group.name}/{name} contains non-string labels.")
+    return decoded
+
+
+def _array(group: h5py.Group, name: str, shape: tuple[int, ...]) -> np.ndarray:
+    if name not in group or not isinstance(group[name], h5py.Dataset):
+        raise LinearizationError(f"Missing dataset {group.name}/{name}.")
+    value = np.asarray(group[name][()])
+    if value.shape != shape or not np.issubdtype(value.dtype, np.number):
+        raise LinearizationError(
+            f"{group.name}/{name} must be a numeric array with shape {shape}; "
+            f"found {value.shape}."
+        )
+    return value.copy()
+
+
+def _metadata(group: h5py.Group, name: str) -> dict[str, Any]:
+    if name not in group:
+        return {}
+    node = group[name]
+    if not isinstance(node, h5py.Group):
+        raise LinearizationError(f"{group.name}/{name} must be a group.")
+    result = {key: _decode(value) for key, value in node.attrs.items()}
+    for key, item in node.items():
+        if isinstance(item, h5py.Dataset):
+            result[key] = _decode(item[()])
+        elif name == "model_options" and isinstance(item, h5py.Group):
+            option_name = _decode(item.attrs.get("name", key))
+            selected = _decode(item.attrs.get("option", ""))
+            result[option_name] = selected or None
+    return result
+
+
+def _identity(path: str) -> tuple[str, str, str]:
+    segments = path.strip("/").split("/")
+    if "linearization" not in segments:
+        return "", "", ""
+    i = segments.index("linearization")
+    network = "/".join(segments[:i])
+    solver = segments[i + 1] if i + 1 < len(segments) else ""
+    run = ""
+    if "runs" in segments:
+        j = segments.index("runs") + 1
+        end = segments.index("points") if "points" in segments else len(segments)
+        run = "/".join(segments[j:end])
+    return network, solver, run
+
+
+def _is_result(group: h5py.Group) -> bool:
+    return isinstance(group, h5py.Group) and all(name in group for name in ("A", "B", "C", "D"))
+
+
+def _read_result(group: h5py.Group) -> Linearization:
+    if not _is_result(group):
+        raise LinearizationError(
+            f"No base linearization is stored in {group.name}. "
+            "Specify time= or times= to read saved transient points."
+        )
+    network, solver, run = _identity(group.name)
+    states = _labels(group, "states")
+    inputs = _labels(group, "inputs")
+    outputs = _labels(group, "outputs")
+    nx, nu, ny = len(states), len(inputs), len(outputs)
+    if "time" not in group or not isinstance(group["time"], h5py.Dataset):
+        raise LinearizationError(f"Missing operating time in {group.name}.")
+    time_value = np.asarray(group["time"][()])
+    if time_value.shape != () or not np.issubdtype(time_value.dtype, np.number):
+        raise LinearizationError(f"{group.name}/time must be numeric and scalar.")
+    return Linearization(
+        A=_array(group, "A", (nx, nx)),
+        B=_array(group, "B", (nx, nu)),
+        C=_array(group, "C", (ny, nx)),
+        D=_array(group, "D", (ny, nu)),
+        x0=_array(group, "x0", (nx,)),
+        xdot0=_array(group, "xdot0", (nx,)),
+        u0=_array(group, "u0", (nu,)),
+        y0=_array(group, "y0", (ny,)),
+        states=states,
+        inputs=inputs,
+        outputs=outputs,
+        time=float(time_value),
+        diagnostics=_metadata(group, "diagnostics"),
+        model_options=_metadata(group, "model_options"),
+        solver=solver,
+        run=run,
+        network=network,
+        path=group.name,
+    )
+
+
+def _has_points(group: h5py.Group) -> bool:
+    if not isinstance(group, h5py.Group):
+        return False
+    points = group.get("points")
+    return isinstance(points, h5py.Group) and any(
+        _is_result(item) for item in points.values() if isinstance(item, h5py.Group)
+    )
+
+
+def _runs(root: h5py.Group) -> list[h5py.Group]:
+    if (_is_result(root) or _has_points(root)) and "/points/" not in root.name:
+        return [root]
+    found: list[h5py.Group] = []
+
+    def visit(name: str, item: h5py.Group | h5py.Dataset):
+        if not (_is_result(item) or _has_points(item)):
+            return
+        path = item.name
+        if "/linearization/" in path and "/runs/" in path and "/points/" not in path:
+            found.append(item)
+
+    root.visititems(visit)
+    return sorted(found, key=lambda group: group.name)
+
+
+def _missing_scoped_run(root: h5py.Group, solver: str | None):
+    raise LinearizationError(f"Scoped linearization {root.name} does not match solver={solver!r}.")
+
+
+def _select_run(root: h5py.Group, solver: str | None, run: str) -> h5py.Group:
+    runs = [group for group in _runs(root) if (not solver or _identity(group.name)[1] == solver)]
+    if (_is_result(root) or _has_points(root)) and "/points/" not in root.name:
+        return runs[0] if runs else _missing_scoped_run(root, solver)
+    matching = [group for group in runs if _identity(group.name)[2] == run]
+    if not matching and run == "base" and len(runs) == 1:
+        matching = runs
+    runs = matching
+    if not runs:
+        raise LinearizationError(
+            f"No linearization for solver={solver!r}, run={run!r} under {root.name}. "
+            "Call linearizations() to inspect available results."
+        )
+    if len(runs) != 1:
+        paths = ", ".join(group.name for group in runs)
+        raise LinearizationError(f"Multiple linearizations match; use .at() to select one: {paths}")
+    return runs[0]
+
+
+def _point(run: h5py.Group, time: float) -> h5py.Group:
+    points = run.get("points")
+    matches: list[h5py.Group] = []
+    available: list[float] = []
+    if isinstance(points, h5py.Group):
+        for item in points.values():
+            if not isinstance(item, h5py.Group) or "time" not in item:
+                continue
+            value = float(item["time"][()])
+            available.append(value)
+            if isclose(value, time, rel_tol=1e-10, abs_tol=1e-12):
+                matches.append(item)
+    if len(matches) == 1:
+        return matches[0]
+    if len(matches) > 1:
+        raise LinearizationError(f"Multiple saved points match t={time:g} under {run.name}.")
+    formatted = ", ".join(f"{value:g}" for value in sorted(available)) or "none"
+    raise LinearizationError(f"No linearization saved at t={time:g}. Available point times: {formatted}.")
+
+
+class H5File(_H5File):
+    """FullPlot HDF5 handle with support for FullFlow linearization records."""
+
+    def at(self, group: str) -> H5File:
+        scoped = super().at(group)
+        return H5File(scoped.filename, scoped.root)
+
+    def linearization(
+        self,
+        solver: str | None = None,
+        run: str = "base",
+        time: float | None = None,
+        times: list[float] | tuple[float, ...] | None = None,
+    ) -> Linearization | dict[float, Linearization]:
+        """Read one model, or a time-keyed dictionary of saved transient models.
+
+        With no time, reads the run's base result rather than the last point.
+        A scoped result group can be read directly with ``.linearization()``.
+        """
+        if solver not in (None, "steady_state", "transient"):
+            raise ValueError("solver must be 'steady_state' or 'transient'.")
+        if time is not None and times is not None:
+            raise ValueError("Specify time or times, not both.")
+        if times is not None and not times:
+            raise ValueError("times must not be empty.")
+        with h5py.File(self.filename, "r") as h5:
+            root = h5[self.root]
+            if _is_result(root) and "/points/" in root.name:
+                if time is not None or times is not None:
+                    raise ValueError("Already scoped to a point; omit time and times.")
+                if solver and _identity(root.name)[1] != solver:
+                    raise LinearizationError("The selected point does not match solver=.")
+                return _read_result(root)
+            selected = _select_run(root, solver, run)
+            if time is not None:
+                return _read_result(_point(selected, float(time)))
+            if times is not None:
+                results: dict[float, Linearization] = {}
+                for requested in times:
+                    key = float(requested)
+                    if key in results:
+                        raise ValueError(f"Duplicate requested time: {key:g}.")
+                    results[key] = _read_result(_point(selected, key))
+                return results
+            return _read_result(selected)
+
+    def linearizations(self, print_output: bool = True) -> list[dict[str, Any]]:
+        """List available linearization runs and their saved operating times."""
+        with h5py.File(self.filename, "r") as h5:
+            root = h5[self.root]
+            found = []
+            for group in _runs(root):
+                network, solver, run = _identity(group.name)
+                points = group.get("points")
+                point_times = []
+                if isinstance(points, h5py.Group):
+                    for point in points.values():
+                        if isinstance(point, h5py.Group) and "time" in point:
+                            point_times.append(float(point["time"][()]))
+                reference = group
+                if not _is_result(group):
+                    reference = min(
+                        (item for item in points.values() if _is_result(item)),
+                        key=lambda item: float(item["time"][()]),
+                    )
+                found.append({
+                    "network": network,
+                    "solver": solver,
+                    "run": run,
+                    "path": group.name,
+                    "time": float(group["time"][()]) if _is_result(group) else None,
+                    "states": len(_labels(reference, "states")),
+                    "inputs": len(_labels(reference, "inputs")),
+                    "outputs": len(_labels(reference, "outputs")),
+                    "times": sorted(point_times),
+                })
+        if print_output:
+            for item in found:
+                print(f"{item['network']} / {item['solver']} / {item['run']}")
+                base_time = f"t={item['time']:g}" if item["time"] is not None else "not saved"
+                print(f"  Base: {base_time}, {item['states']} states, "
+                      f"{item['inputs']} inputs, {item['outputs']} outputs")
+                if item["times"]:
+                    print("  Points: " + ", ".join(f"{t:g}" for t in item["times"]))
+            if not found:
+                print("No FullFlow linearization results found.")
+        return found
+
+
+def open(filename: str | Path, root: str = "/") -> H5File:
+    """Open an HDF5 file with the standard FullPlot API and linearization support."""
+    handle = _open(filename, root=root)
+    return H5File(handle.filename, handle.root)

fullplot/maps.py

@@ -69,6 +69,21 @@ class Axis:
     units: str = ""
     spacing: str = "values"
 
+    def __str__(self) -> str:
+        """Return a compact summary of the map axis."""
+        values = np.asarray(self.values)
+        if values.ndim != 1 or values.size == 0:
+            value_summary = f"shape={values.shape}"
+        else:
+            units = f" {self.units}" if self.units else ""
+            point_label = "point" if values.size == 1 else "points"
+            value_summary = (
+                f"{values.size} {point_label}, {values[0]:g} to {values[-1]:g}{units}"
+            )
+        return (
+            f"Axis({self.name!r}, {value_summary}, spacing={self.spacing!r})"
+        )
+
     @classmethod
     def linear(
         cls,

{fullplot-0.1.1.dist-info → fullplot-2.0.0.dist-info}/METADATA

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: fullplot
-Version: 0.1.1
-Summary: A documented HDF5 plotting, trace-processing, and map-generation package for engineering simulation and test data.
-Keywords: hdf5,plotting,engineering,simulation,test-data,map-generation,scientific-computing
+Version: 2.0.0
+Summary: HDF5 plotting, trace processing, linearization reading, and map generation for engineering data.
+Keywords: hdf5,plotting,engineering,simulation,test-data,linearization,state-space,map-generation,scientific-computing
 Author: Saaketh Ramoju
 Author-email: Saaketh Ramoju <skramoju@gmail.com>
 License-Expression: GPL-3.0-only
@@ -30,6 +30,7 @@ Project-URL: Issues, https://github.com/saakethramoju/FullPlot/issues
 Project-URL: Changelog, https://github.com/saakethramoju/FullPlot/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://github.com/saakethramoju/FullPlot#readme
 Project-URL: PyPI, https://pypi.org/project/fullplot/
+Provides-Extra: examples
 Description-Content-Type: text/markdown
 
 # FullPlot
@@ -193,6 +194,220 @@ settings = run.values("metadata")
 
 ---
 
+## Reading FullFlow linearizations
+
+FullPlot can read **previously calculated** FullFlow steady-state and transient linearization records. The result is a labeled `Linearization` object containing the state-space matrices and the operating point at which they were computed.
+
+A continuous-time linear model takes the form
+
+```math
+\Delta\dot{x}=A\Delta x+B\Delta u
+```
+
+```math
+\Delta y=C\Delta x+D\Delta u
+```
+
+where:
+
+- `x`: physical dynamic state vector (for example stored mass or energy),
+- `u`: selected input vector (for example valve area),
+- `y`: selected output vector (for example chamber pressure),
+- `A`: how state changes affect the state derivatives,
+- `B`: how input changes affect the state derivatives,
+- `C`: how state changes affect outputs,
+- `D`: how input changes directly affect outputs.
+
+`\Delta` denotes a deviation from the saved operating point. For a non-equilibrium transient point, the model also needs the saved baseline derivative:
+
+```math
+\dot{x}\approx\dot{x}_0+A(x-x_0)+B(u-u_0)
+```
+
+```math
+y\approx y_0+C(x-x_0)+D(u-u_0)
+```
+
+FullPlot **does not create these matrices**. It reads them from FullFlow's linearization HDF5 output, without needing the original nonlinear network or property-model packages.
+
+### Discover available results
+
+```python
+import fullplot as fplt
+
+file = fplt.open("Linearization.h5")
+info = file.linearizations()
+```
+
+`linearizations()` prints a summary of each available run and returns a list of dictionaries. Each record includes `network`, `solver`, `run`, `path`, `time`, matrix dimensions (`states`, `inputs`, `outputs`), and saved transient point times (`times`). When only transient points were saved, `time` is `None` because there is no separate base result.
+
+For programmatic discovery without printing:
+
+```python
+info = file.linearizations(print_output=False)
+
+for run in info:
+    print(run["solver"], run["time"], run["times"])
+```
+
+### Read one linearization
+
+```python
+steady = file.linearization(solver="steady_state")
+
+print(steady.A)
+print(steady.B)
+print(steady.C)
+print(steady.D)
+```
+
+Read the final/base transient result with:
+
+```python
+final = file.linearization(solver="transient")
+```
+
+Omitting `time` selects the **base result**, not the latest point stored in `points/`. If only saved points are present, specify `time=` or `times=`. If the file contains both steady-state and transient records, select `solver=` explicitly. If only one record is available, it can be inferred.
+
+### Read transient operating points
+
+```python
+point = file.linearization(solver="transient", time=0.1)
+
+print(point.time)
+print(point.A.shape)
+print(point.states)
+```
+
+Read several points at once:
+
+```python
+points = file.linearization(
+    solver="transient",
+    times=[0.1, 0.3],
+)
+
+for requested_time, linear in points.items():
+    print(requested_time, linear.A, linear.D)
+```
+
+`times=` returns an ordinary dictionary keyed by the **requested** times, even if HDF5 stores `0.3` as `0.30000000000000004`. Times are matched within a narrow floating-point tolerance. If a time does not exist, FullPlot reports the available point times. If multiple points match the same time, it rejects the ambiguous selection.
+
+Saved points can have **different numbers of states, inputs, or outputs**. FullPlot returns each result independently; it does not attempt to concatenate incompatible matrices.
+
+### Scope into a run
+
+```python
+run = file.at("/Water_Flow/linearization/transient/runs/base")
+
+point = run.linearization(time=0.1)
+final = run.linearization()
+```
+
+A handle scoped directly to a point group can read that point without a time argument:
+
+```python
+point = file.at(
+    "/Water_Flow/linearization/transient/runs/base/points/0"
+).linearization()
+```
+
+If several networks contain matching records, `.linearization()` raises an ambiguity error instead of choosing one arbitrarily. Use `.at()` to select the desired network or run. For non-base model-option runs, scope to the run group or supply its HDF5 run path (such as `run="Pump_Model/polytropic"`). A single unambiguous non-base run can also be selected automatically.
+
+### Data available in `Linearization`
+
+| Attribute | Description |
+| --- | --- |
+| `A`, `B`, `C`, `D` | NumPy state-space matrices |
+| `x0`, `xdot0`, `u0`, `y0` | Nominal states, state rates, inputs, and outputs |
+| `states`, `inputs`, `outputs` | Ordered Python string tuples corresponding to matrix rows and columns |
+| `time` | Operating-point time |
+| `diagnostics` | Saved condition numbers and other numerical diagnostics |
+| `model_options` | Saved FullFlow model-option metadata |
+| `network`, `solver`, `run`, `path` | Source identification and HDF5 path |
+
+Dimensions are checked on reading:
+
+```math
+A\in\mathbb R^{n_x\times n_x},\quad B\in\mathbb R^{n_x\times n_u},\quad
+C\in\mathbb R^{n_y\times n_x},\quad D\in\mathbb R^{n_y\times n_u}.
+```
+
+FullPlot validates the baseline-vector lengths and requires compatible label counts. HDF5 byte strings are decoded to regular Python strings. Incorrect or missing datasets raise `LinearizationError`.
+
+### Using the matrices
+
+Matrix labels determine the meaning of each row and column:
+
+```python
+linear = file.linearization(solver="transient", time=0.1)
+
+state_index = linear.states.index("Pipe 1.mass_flow")
+input_index = linear.inputs.index("Pipe 1.cross_sectional_area")
+
+sensitivity = linear.B[state_index, input_index]
+print(sensitivity)
+```
+
+For a small deviation from the nominal operating point:
+
+```python
+import numpy as np
+
+dx = np.zeros(len(linear.states))
+du = np.zeros(len(linear.inputs))
+du[0] = 1e-6
+
+xdot = linear.xdot0 + linear.A @ dx + linear.B @ du
+y = linear.y0 + linear.C @ dx + linear.D @ du
+```
+
+These are **local predictions**, not a substitute for the nonlinear model away from the operating point. FullPlot reads the saved arrays; it does not provide built-in eigenvalue analysis, controller tuning, state-space integration, linearization heat maps, or matrix-coefficient trace extraction.
+
+### FullFlow HDF5 format
+
+The reader supports the current FullFlow per-run and per-point layout:
+
+```text
+Network/
+  linearization/
+    steady_state/
+      runs/
+        base/
+          A, B, C, D
+          x0, xdot0, u0, y0
+          states, inputs, outputs, time
+          diagnostics/, model_options/
+    transient/
+      runs/
+        base/
+          A, B, C, D
+          x0, xdot0, u0, y0
+          states, inputs, outputs, time
+          diagnostics/, model_options/
+          points/
+            0/
+              A, B, C, D, ...
+              time
+            1/
+              A, B, C, D, ...
+              time
+```
+
+Reading a saved linearization is **not** the same as calculating one from a normal simulation-history file. Ordinary result traces alone cannot determine the original system equations or their derivatives. Matrix generation remains FullFlow's responsibility.
+
+### Linearization examples
+
+Run the small demo generator, then the two reading examples:
+
+```bash
+python examples/linearization/0generate_linearization_data.py
+python examples/linearization/1inspect_linearization.py
+python examples/linearization/2read_transient_points.py
+```
+
+The demo uses a tiny, self-contained HDF5 file in FullFlow's export format. Replace its filename with your own FullFlow result to inspect real networks. No FullFlow dependency is needed for these reading examples.
+
 ## Core public API
 
 Most users only need these names:
@@ -213,6 +428,7 @@ fplt.Trace
 fplt.TimeAxis
 fplt.Axis
 fplt.generate_map
+fplt.Linearization
 ```
 
 The main classes are:
@@ -223,6 +439,7 @@ The main classes are:
 | `Trace` | Reusable one-dimensional x/y data object. Used for raw data, filtered data, generated limits, commands, and derived traces. |
 | `TimeAxis` | Shared shiftable and windowable time basis. Several traces can share one axis and follow the same alignment/window. |
 | `Axis` | Independent variable definition for rectangular-grid map generation. |
+| `Linearization` | Labeled FullFlow state-space matrices and their saved operating point. |
 
 Important exceptions are:
 
@@ -235,6 +452,7 @@ Important exceptions are:
 | `FullPlotMapError` | Base map-generation exception. |
 | `MapGenerationError` | Map generation failed during evaluation, resume, or file layout validation. |
 | `MapOutputError` | The map `evaluate(...)` function returned invalid outputs. |
+| `LinearizationError` | A saved FullFlow linearization is missing, ambiguous, or malformed. |
 
 ---
 
@@ -988,11 +1206,12 @@ The CLI does not create plots. Use the Python API for plotting so scripts can co
 
 ## Examples
 
-The repository includes three example folders:
+The repository includes four example folders:
 
 ```text
 examples/
 ├── hdf5_plotting/
+├── linearization/
 ├── maps/
 └── traces/
 ```
@@ -1037,6 +1256,9 @@ examples/
 * output discovery,
 * HDF5 layout inspection.
 
+`examples/linearization/` demonstrates discovering and reading saved FullFlow
+steady-state and transient state-space models.
+
 ---
 
 ## Themes
@@ -1098,7 +1320,7 @@ This is deliberate. The package is meant to be a simple bridge between HDF5 engi
 
 ---
 
-# Documentation
+## Documentation
 
 Full documentation:
 

fullplot-2.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+fullplot/__init__.py,sha256=B-KeVjURXVJgn14OEodd7F2Hbj5gIV-o5qf80q0cMxs,1091
+fullplot/cli.py,sha256=u9OpNtKL82YLwJ3xrNgs0B3OsXjYGHFs7TgnydPBj7k,2591
+fullplot/fullplot.py,sha256=uWgeKfB4DLJ4NdNZRGtrX-Pxk8tZ1gt6jOAMLt7ECmU,81859
+fullplot/hdf5.py,sha256=P3EaLWdAKQSWqwrdM_Q3eqUNycGsmrA5zND0G7KreRw,2363
+fullplot/linearization.py,sha256=quM2RiqMSFtZ60JwFU_jVkSDjtp2xD8o2dvT2s_UwmI,13391
+fullplot/maps.py,sha256=TSNp-ITxjCp4yMRLcrxpad3_T7sJvBvKlumI0-6Jr8k,24928
+fullplot/themes.py,sha256=xZR44k29dCNGMwUk2CpkWLkp88mBlC7cK7O9FWmue6o,6220
+fullplot-2.0.0.dist-info/licenses/LICENSE,sha256=ixuiBLtpoK3iv89l7ylKkg9rs2GzF9ukPH7ynZYzK5s,35148
+fullplot-2.0.0.dist-info/WHEEL,sha256=3NO1oYsF7mANFUWVdyEQLM-zmecczWWEmmF5rEbXrWk,80
+fullplot-2.0.0.dist-info/entry_points.txt,sha256=4jALe-r2n_VzCxE1P4AsajIpUdkPq56IZWWOlZqPrq8,48
+fullplot-2.0.0.dist-info/METADATA,sha256=5Fug8vnZqxSzKdchc5YhpccOjiTUvrmpZ2H4cv3TRzg,34104
+fullplot-2.0.0.dist-info/RECORD,,

{fullplot-0.1.1.dist-info → fullplot-2.0.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.12.19
+Generator: uv 0.13.6
 Root-Is-Purelib: true
 Tag: py3-none-any

fullplot-0.1.1.dist-info/RECORD

@@ -1,11 +0,0 @@
-fullplot/__init__.py,sha256=hmctlgTH7-BzOtf8VQ2AAsNRX79--2i6tqHdabPwv80,1323
-fullplot/cli.py,sha256=u9OpNtKL82YLwJ3xrNgs0B3OsXjYGHFs7TgnydPBj7k,2591
-fullplot/fullplot.py,sha256=69mSqa858r37cRHyUW9MPiJpcPfnMYa__wGcEqCrqA8,80609
-fullplot/hdf5.py,sha256=P3EaLWdAKQSWqwrdM_Q3eqUNycGsmrA5zND0G7KreRw,2363
-fullplot/maps.py,sha256=xDUApvB-IYKtuyKiExZtx8G3XGPWc-uACsFerl0gDlQ,24322
-fullplot/themes.py,sha256=xZR44k29dCNGMwUk2CpkWLkp88mBlC7cK7O9FWmue6o,6220
-fullplot-0.1.1.dist-info/licenses/LICENSE,sha256=ixuiBLtpoK3iv89l7ylKkg9rs2GzF9ukPH7ynZYzK5s,35148
-fullplot-0.1.1.dist-info/WHEEL,sha256=e4_1dyBeezi8ZjfxrZ3bnVOxFDa3ksqVqH0jTHkUZ3k,81
-fullplot-0.1.1.dist-info/entry_points.txt,sha256=4jALe-r2n_VzCxE1P4AsajIpUdkPq56IZWWOlZqPrq8,48
-fullplot-0.1.1.dist-info/METADATA,sha256=M3-YzwUOcZQZs65Jccr_Rx0kodM-EcbT0F4DHOUPoLI,26361
-fullplot-0.1.1.dist-info/RECORD,,