fullplot 0.1.1__py3-none-any.whl → 2.0.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fullplot/__init__.py +5 -11
- fullplot/fullplot.py +158 -37
- fullplot/linearization.py +335 -0
- fullplot/maps.py +15 -0
- {fullplot-0.1.1.dist-info → fullplot-2.0.1.dist-info}/METADATA +313 -5
- fullplot-2.0.1.dist-info/RECORD +12 -0
- {fullplot-0.1.1.dist-info → fullplot-2.0.1.dist-info}/WHEEL +1 -1
- fullplot-0.1.1.dist-info/RECORD +0 -11
- {fullplot-0.1.1.dist-info → fullplot-2.0.1.dist-info}/entry_points.txt +0 -0
- {fullplot-0.1.1.dist-info → fullplot-2.0.1.dist-info}/licenses/LICENSE +0 -0
fullplot/__init__.py
CHANGED
|
@@ -1,25 +1,16 @@
|
|
|
1
|
-
"""FullPlot public package interface.
|
|
2
|
-
|
|
3
|
-
FullPlot is a small engineering-data plotting package centered on HDF5 files,
|
|
4
|
-
reusable one-dimensional ``Trace`` objects, shared ``TimeAxis`` objects, and
|
|
5
|
-
rectangular-grid map generation. Most users import the package as ``fullplot``
|
|
6
|
-
or ``fplt`` and use the names re-exported here instead of importing from the
|
|
7
|
-
internal modules directly.
|
|
8
|
-
"""
|
|
1
|
+
"""FullPlot public package interface."""
|
|
9
2
|
|
|
10
3
|
from fullplot.cli import main
|
|
11
4
|
from fullplot.fullplot import (
|
|
12
5
|
AmbiguousDatasetError,
|
|
13
6
|
DatasetNotFoundError,
|
|
14
7
|
FullPlotError,
|
|
15
|
-
H5File,
|
|
16
8
|
PlotDataError,
|
|
17
9
|
TimeAxis,
|
|
18
10
|
Trace,
|
|
19
11
|
VALID_TRACE_ROLES,
|
|
20
12
|
list,
|
|
21
13
|
map,
|
|
22
|
-
open,
|
|
23
14
|
plot,
|
|
24
15
|
read,
|
|
25
16
|
show,
|
|
@@ -29,6 +20,7 @@ from fullplot.fullplot import (
|
|
|
29
20
|
values,
|
|
30
21
|
write_traces,
|
|
31
22
|
)
|
|
23
|
+
from fullplot.linearization import H5File, Linearization, LinearizationError, open
|
|
32
24
|
from fullplot.maps import (
|
|
33
25
|
Axis,
|
|
34
26
|
FullPlotMapError,
|
|
@@ -37,7 +29,7 @@ from fullplot.maps import (
|
|
|
37
29
|
generate_map,
|
|
38
30
|
)
|
|
39
31
|
|
|
40
|
-
__version__ = "0.1
|
|
32
|
+
__version__ = "2.0.1"
|
|
41
33
|
|
|
42
34
|
__all__ = [
|
|
43
35
|
"__version__",
|
|
@@ -45,6 +37,8 @@ __all__ = [
|
|
|
45
37
|
"DatasetNotFoundError",
|
|
46
38
|
"AmbiguousDatasetError",
|
|
47
39
|
"PlotDataError",
|
|
40
|
+
"LinearizationError",
|
|
41
|
+
"Linearization",
|
|
48
42
|
"TimeAxis",
|
|
49
43
|
"Trace",
|
|
50
44
|
"VALID_TRACE_ROLES",
|
fullplot/fullplot.py
CHANGED
|
@@ -2,6 +2,7 @@ from __future__ import annotations
|
|
|
2
2
|
|
|
3
3
|
import builtins
|
|
4
4
|
import itertools
|
|
5
|
+
import json
|
|
5
6
|
import posixpath
|
|
6
7
|
from contextlib import nullcontext
|
|
7
8
|
from dataclasses import dataclass
|
|
@@ -414,6 +415,20 @@ class TimeAxis:
|
|
|
414
415
|
def __getitem__(self, item):
|
|
415
416
|
return self.values[item]
|
|
416
417
|
|
|
418
|
+
def __str__(self) -> str:
|
|
419
|
+
"""Return a compact summary of the active time range."""
|
|
420
|
+
active_label = "sample" if self.count == 1 else "samples"
|
|
421
|
+
window = ""
|
|
422
|
+
if self.has_window:
|
|
423
|
+
start, stop = self.window_range
|
|
424
|
+
start_text = "start" if start is None else f"{start:g}"
|
|
425
|
+
stop_text = "end" if stop is None else f"{stop:g}"
|
|
426
|
+
window = f", window={start_text} to {stop_text}"
|
|
427
|
+
return (
|
|
428
|
+
f"TimeAxis({self.name!r}, {self.count}/{self.raw_count} {active_label}, "
|
|
429
|
+
f"range={self.tmin:g} to {self.tmax:g}, zero={self.zero:g}{window})"
|
|
430
|
+
)
|
|
431
|
+
|
|
417
432
|
class Trace:
|
|
418
433
|
"""Prepared one-dimensional engineering data series.
|
|
419
434
|
|
|
@@ -490,6 +505,17 @@ class Trace:
|
|
|
490
505
|
self.role = _normalize_trace_role(role)
|
|
491
506
|
self.attrs = {} if attrs is None else dict(attrs)
|
|
492
507
|
|
|
508
|
+
def __str__(self) -> str:
|
|
509
|
+
"""Return a compact summary without printing the underlying arrays."""
|
|
510
|
+
finite_count = int(np.count_nonzero(self.finite))
|
|
511
|
+
count = len(self.x)
|
|
512
|
+
sample_label = "sample" if count == 1 else "samples"
|
|
513
|
+
return (
|
|
514
|
+
f"Trace({self.name!r}, role={self.role!r}, {count} {sample_label}, "
|
|
515
|
+
f"x={self.tmin:g} to {self.tmax:g}, "
|
|
516
|
+
f"finite={finite_count}/{count})"
|
|
517
|
+
)
|
|
518
|
+
|
|
493
519
|
@property
|
|
494
520
|
def x(self) -> np.ndarray:
|
|
495
521
|
"""Current x-values, including shared alignment and windowing."""
|
|
@@ -1250,6 +1276,33 @@ def _to_numpy_index(value):
|
|
|
1250
1276
|
return value
|
|
1251
1277
|
|
|
1252
1278
|
|
|
1279
|
+
def _dataset_array(dataset):
|
|
1280
|
+
"""Read native values, with a narrow fallback for old FullFlow array histories."""
|
|
1281
|
+
raw = np.asarray(dataset[()])
|
|
1282
|
+
if (dataset.file.attrs.get("fullflow_format") != "fullflow-simple-hdf5"
|
|
1283
|
+
or raw.ndim != 1 or raw.dtype.kind not in "OSU" or not raw.size):
|
|
1284
|
+
return raw
|
|
1285
|
+
try:
|
|
1286
|
+
values = [None if not value else np.asarray(json.loads(value)) for value in raw]
|
|
1287
|
+
present = [value for value in values if value is not None]
|
|
1288
|
+
if not present or any(value.ndim == 0 or value.dtype.kind not in "biufc"
|
|
1289
|
+
or value.shape != present[0].shape for value in present):
|
|
1290
|
+
return raw
|
|
1291
|
+
dtype = np.result_type(*(value.dtype for value in present), float)
|
|
1292
|
+
return np.stack([np.full(present[0].shape, np.nan, dtype=dtype)
|
|
1293
|
+
if value is None else value for value in values])
|
|
1294
|
+
except (ValueError, TypeError):
|
|
1295
|
+
return raw
|
|
1296
|
+
|
|
1297
|
+
|
|
1298
|
+
def _time_dimension(dataset, array):
|
|
1299
|
+
if "time_axis" in dataset.attrs:
|
|
1300
|
+
return int(dataset.attrs["time_axis"])
|
|
1301
|
+
if dataset.ndim == 1 and array.ndim > 1 and dataset.dtype.kind in "OSU":
|
|
1302
|
+
return 0
|
|
1303
|
+
return None
|
|
1304
|
+
|
|
1305
|
+
|
|
1253
1306
|
def _apply_slice_for_lines(array: np.ndarray, axis: int, slice_spec) -> tuple[np.ndarray, int]:
|
|
1254
1307
|
array = np.asarray(array)
|
|
1255
1308
|
|
|
@@ -1314,6 +1367,10 @@ class H5File:
|
|
|
1314
1367
|
self.filename = str(self.filename)
|
|
1315
1368
|
self.root = _clean_root(self.root)
|
|
1316
1369
|
|
|
1370
|
+
def __str__(self) -> str:
|
|
1371
|
+
"""Return the selected file and HDF5 root."""
|
|
1372
|
+
return f"H5File({self.filename!r}, root={self.root!r})"
|
|
1373
|
+
|
|
1317
1374
|
def at(self, group: str) -> "H5File":
|
|
1318
1375
|
"""
|
|
1319
1376
|
Return a new H5File scoped to a specific HDF5 group.
|
|
@@ -1481,14 +1538,16 @@ class H5File:
|
|
|
1481
1538
|
def read(self, name: str):
|
|
1482
1539
|
"""Read one dataset by absolute path, relative path, or unique short name.
|
|
1483
1540
|
|
|
1484
|
-
|
|
1541
|
+
Native datasets retain their NumPy values. Legacy FullFlow JSON array
|
|
1542
|
+
histories are decoded when every sample has the same numeric shape. Use
|
|
1485
1543
|
``trace()`` or ``time()`` when the dataset should become a FullPlot
|
|
1486
1544
|
object with validation and metadata.
|
|
1487
1545
|
"""
|
|
1488
1546
|
|
|
1489
1547
|
with h5py.File(self.filename, "r") as h5:
|
|
1490
1548
|
path = self._resolve_dataset_path(h5, name)
|
|
1491
|
-
|
|
1549
|
+
dataset = h5[path]
|
|
1550
|
+
return dataset[()] if dataset.shape == () else _dataset_array(dataset)
|
|
1492
1551
|
|
|
1493
1552
|
def time(self, name: str = "time") -> TimeAxis:
|
|
1494
1553
|
"""Read a one-dimensional HDF5 dataset as a shared ``TimeAxis``.
|
|
@@ -1630,7 +1689,7 @@ class H5File:
|
|
|
1630
1689
|
x=None,
|
|
1631
1690
|
y2=None,
|
|
1632
1691
|
slice=None,
|
|
1633
|
-
axis: int =
|
|
1692
|
+
axis: int | None = None,
|
|
1634
1693
|
labels=None,
|
|
1635
1694
|
y2labels=None,
|
|
1636
1695
|
xlabel: str | None = None,
|
|
@@ -1873,6 +1932,7 @@ class H5File:
|
|
|
1873
1932
|
dpi: int = 200,
|
|
1874
1933
|
show: bool = True,
|
|
1875
1934
|
figsize=(8, 6),
|
|
1935
|
+
orientation: str | None = None,
|
|
1876
1936
|
):
|
|
1877
1937
|
"""
|
|
1878
1938
|
Plot a 2D dataset as a map.
|
|
@@ -1905,35 +1965,8 @@ class H5File:
|
|
|
1905
1965
|
theme = check_theme(theme)
|
|
1906
1966
|
|
|
1907
1967
|
with h5py.File(self.filename, "r") as h5:
|
|
1908
|
-
z_array, z_name = self.
|
|
1909
|
-
|
|
1910
|
-
z_array = _apply_slice_for_map(z_array, slice)
|
|
1911
|
-
|
|
1912
|
-
if z_array.ndim != 2:
|
|
1913
|
-
raise PlotDataError(
|
|
1914
|
-
f"map requires 2D data after slicing. "
|
|
1915
|
-
f"Selected data has shape {z_array.shape}."
|
|
1916
|
-
)
|
|
1917
|
-
|
|
1918
|
-
rows, cols = z_array.shape
|
|
1919
|
-
|
|
1920
|
-
x_array, x_name = self._read_map_axis(
|
|
1921
|
-
h5=h5,
|
|
1922
|
-
value=x,
|
|
1923
|
-
default=np.arange(cols),
|
|
1924
|
-
default_name="Column Index",
|
|
1925
|
-
valid_lengths=(cols, cols + 1),
|
|
1926
|
-
axis_name="x",
|
|
1927
|
-
)
|
|
1928
|
-
|
|
1929
|
-
y_array, y_name = self._read_map_axis(
|
|
1930
|
-
h5=h5,
|
|
1931
|
-
value=y,
|
|
1932
|
-
default=np.arange(rows),
|
|
1933
|
-
default_name="Row Index",
|
|
1934
|
-
valid_lengths=(rows, rows + 1),
|
|
1935
|
-
axis_name="y",
|
|
1936
|
-
)
|
|
1968
|
+
x_array, y_array, z_array, x_name, y_name, z_name = self._field_data(
|
|
1969
|
+
h5, z, x, y, slice, orientation)
|
|
1937
1970
|
|
|
1938
1971
|
fig, ax = plt.subplots(figsize=figsize)
|
|
1939
1972
|
apply_theme(fig, ax, theme)
|
|
@@ -1997,6 +2030,87 @@ class H5File:
|
|
|
1997
2030
|
|
|
1998
2031
|
return fig, ax
|
|
1999
2032
|
|
|
2033
|
+
def _field_data(self, h5, z, x, y, slice_spec, orientation):
|
|
2034
|
+
if orientation not in (None, "xy", "yx"):
|
|
2035
|
+
raise PlotDataError("orientation must be 'xy', 'yx', or None.")
|
|
2036
|
+
data, name = self._read_map_z(h5, z)
|
|
2037
|
+
time_axis = None
|
|
2038
|
+
time_path = None
|
|
2039
|
+
if isinstance(z, str):
|
|
2040
|
+
dataset = h5[self._resolve_dataset_path(h5, z)]
|
|
2041
|
+
time_axis = _time_dimension(dataset, data)
|
|
2042
|
+
time_path = dataset.attrs.get("time_dataset")
|
|
2043
|
+
if time_path is None and time_axis is not None and "time" in dataset.parent:
|
|
2044
|
+
time_path = dataset.parent["time"].name
|
|
2045
|
+
normalized = _normalize_slice_spec(slice_spec, data.ndim)
|
|
2046
|
+
remaining = [axis for axis in range(data.ndim)
|
|
2047
|
+
if not _is_integer_index(normalized.get(axis, builtins.slice(None)))]
|
|
2048
|
+
time_axis = remaining.index(time_axis) if time_axis in remaining else None
|
|
2049
|
+
data = _apply_slice_for_map(data, slice_spec)
|
|
2050
|
+
if data.ndim != 2:
|
|
2051
|
+
raise PlotDataError(f"Field plotting requires 2D data after slicing; got {data.shape}.")
|
|
2052
|
+
if x is None and time_axis is not None and time_path is not None:
|
|
2053
|
+
x = time_path
|
|
2054
|
+
x_values, x_name = self._read_map_axis(h5, x, None, "Column Index", None, "x")
|
|
2055
|
+
y_values, y_name = self._read_map_axis(h5, y, None, "Row Index", None, "y")
|
|
2056
|
+
candidates = []
|
|
2057
|
+
for candidate in ("yx", "xy"):
|
|
2058
|
+
rows, cols = data.shape if candidate == "yx" else data.shape[::-1]
|
|
2059
|
+
if ((x_values is None or len(x_values) in (cols, cols + 1))
|
|
2060
|
+
and (y_values is None or len(y_values) in (rows, rows + 1))):
|
|
2061
|
+
candidates.append(candidate)
|
|
2062
|
+
hint = None
|
|
2063
|
+
if time_axis is not None and time_path is not None:
|
|
2064
|
+
for coordinate, is_x in ((x, True), (y, False)):
|
|
2065
|
+
if isinstance(coordinate, str) and h5[self._resolve_dataset_path(h5, coordinate)] == h5[time_path]:
|
|
2066
|
+
hint = "xy" if (time_axis == 0) == is_x else "yx"
|
|
2067
|
+
if not candidates:
|
|
2068
|
+
raise PlotDataError(f"Coordinate lengths do not match field shape {data.shape}.")
|
|
2069
|
+
if orientation is None:
|
|
2070
|
+
if hint is not None:
|
|
2071
|
+
orientation = hint
|
|
2072
|
+
elif len(candidates) == 1:
|
|
2073
|
+
orientation = candidates[0]
|
|
2074
|
+
elif x is None and y is None:
|
|
2075
|
+
orientation = "yx"
|
|
2076
|
+
else:
|
|
2077
|
+
raise PlotDataError("Ambiguous field orientation; specify orientation='xy' (x first) or 'yx' (y first).")
|
|
2078
|
+
if orientation not in candidates:
|
|
2079
|
+
raise PlotDataError(f"Coordinate lengths do not match field shape {data.shape} and orientation {orientation!r}.")
|
|
2080
|
+
if orientation == "xy":
|
|
2081
|
+
data = data.T
|
|
2082
|
+
if x_values is None:
|
|
2083
|
+
x_values = np.arange(data.shape[1])
|
|
2084
|
+
if y_values is None:
|
|
2085
|
+
y_values = np.arange(data.shape[0])
|
|
2086
|
+
return x_values, y_values, data, x_name, y_name, name
|
|
2087
|
+
|
|
2088
|
+
def surface(self, z, x=None, y=None, slice=None, *, orientation=None,
|
|
2089
|
+
xlabel=None, ylabel=None, zlabel=None, title=None, theme="dark",
|
|
2090
|
+
save=None, dpi=200, show=False, figsize=(9, 6)):
|
|
2091
|
+
"""Plot a numerical 3D surface using the same axes and orientation as map()."""
|
|
2092
|
+
theme = check_theme(theme)
|
|
2093
|
+
with h5py.File(self.filename, "r") as h5:
|
|
2094
|
+
xs, ys, values, x_name, y_name, z_name = self._field_data(
|
|
2095
|
+
h5, z, x, y, slice, orientation)
|
|
2096
|
+
if len(xs) == values.shape[1] + 1:
|
|
2097
|
+
xs = (xs[:-1] + xs[1:]) / 2
|
|
2098
|
+
if len(ys) == values.shape[0] + 1:
|
|
2099
|
+
ys = (ys[:-1] + ys[1:]) / 2
|
|
2100
|
+
xx, yy = np.meshgrid(xs, ys)
|
|
2101
|
+
fig = plt.figure(figsize=figsize)
|
|
2102
|
+
ax = fig.add_subplot(111, projection="3d")
|
|
2103
|
+
apply_theme(fig, ax, theme)
|
|
2104
|
+
ax.plot_surface(xx, yy, values, cmap=theme_settings(theme)["map_cmap"])
|
|
2105
|
+
ax.set_xlabel(xlabel or x_name)
|
|
2106
|
+
ax.set_ylabel(ylabel or y_name)
|
|
2107
|
+
ax.set_zlabel(zlabel or z_name)
|
|
2108
|
+
if title is not None:
|
|
2109
|
+
ax.set_title(title)
|
|
2110
|
+
fig.tight_layout()
|
|
2111
|
+
self._save_and_show(fig, save, dpi, show)
|
|
2112
|
+
return fig, ax
|
|
2113
|
+
|
|
2000
2114
|
def _resolve_dataset_path(self, h5: h5py.File, selector: str) -> str:
|
|
2001
2115
|
if not isinstance(selector, str):
|
|
2002
2116
|
raise DatasetNotFoundError(f"Dataset selector must be a string, got {type(selector)}.")
|
|
@@ -2210,7 +2324,10 @@ class H5File:
|
|
|
2210
2324
|
path = self._resolve_dataset_path(h5, selector)
|
|
2211
2325
|
base_label = _basename(path)
|
|
2212
2326
|
|
|
2213
|
-
array =
|
|
2327
|
+
array = _dataset_array(h5[path])
|
|
2328
|
+
if axis is None:
|
|
2329
|
+
time_axis = _time_dimension(h5[path], array)
|
|
2330
|
+
axis = -1 if time_axis is None else time_axis
|
|
2214
2331
|
|
|
2215
2332
|
if not _is_numeric_dtype(array.dtype):
|
|
2216
2333
|
raise PlotDataError(f"Dataset {path!r} is not numeric.")
|
|
@@ -2292,7 +2409,7 @@ class H5File:
|
|
|
2292
2409
|
|
|
2293
2410
|
for selector in z:
|
|
2294
2411
|
path = self._resolve_dataset_path(h5, selector)
|
|
2295
|
-
array =
|
|
2412
|
+
array = _dataset_array(h5[path])
|
|
2296
2413
|
|
|
2297
2414
|
if not _is_numeric_dtype(array.dtype):
|
|
2298
2415
|
raise PlotDataError(f"Dataset {path!r} is not numeric.")
|
|
@@ -2314,7 +2431,7 @@ class H5File:
|
|
|
2314
2431
|
|
|
2315
2432
|
z_path = self._resolve_dataset_path(h5, z)
|
|
2316
2433
|
z_name = _basename(z_path)
|
|
2317
|
-
z_array =
|
|
2434
|
+
z_array = _dataset_array(h5[z_path])
|
|
2318
2435
|
|
|
2319
2436
|
if not _is_numeric_dtype(z_array.dtype):
|
|
2320
2437
|
raise PlotDataError("z must be numeric.")
|
|
@@ -2327,8 +2444,12 @@ class H5File:
|
|
|
2327
2444
|
|
|
2328
2445
|
if isinstance(value, str):
|
|
2329
2446
|
path = self._resolve_dataset_path(h5, value)
|
|
2330
|
-
array =
|
|
2447
|
+
array = _dataset_array(h5[path])
|
|
2331
2448
|
name = _basename(path)
|
|
2449
|
+
if array.ndim == 2 and _time_dimension(h5[path], array) == 0:
|
|
2450
|
+
if not len(array) or not np.array_equal(array, np.broadcast_to(array[0], array.shape), equal_nan=True):
|
|
2451
|
+
raise PlotDataError(f"{axis_name} coordinate history must be constant over time.")
|
|
2452
|
+
array = array[0]
|
|
2332
2453
|
else:
|
|
2333
2454
|
array = np.asarray(value)
|
|
2334
2455
|
name = default_name
|
|
@@ -2339,7 +2460,7 @@ class H5File:
|
|
|
2339
2460
|
if not _is_numeric_dtype(array.dtype):
|
|
2340
2461
|
raise PlotDataError(f"{axis_name} must be numeric.")
|
|
2341
2462
|
|
|
2342
|
-
if len(array) not in valid_lengths:
|
|
2463
|
+
if valid_lengths is not None and len(array) not in valid_lengths:
|
|
2343
2464
|
valid_text = " or ".join(str(length) for length in valid_lengths)
|
|
2344
2465
|
raise PlotDataError(
|
|
2345
2466
|
f"{axis_name} has length {len(array)}, but expected length {valid_text}."
|
|
@@ -0,0 +1,335 @@
|
|
|
1
|
+
"""Read FullFlow state-space linearizations from HDF5 files."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
from math import isclose
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
from typing import Any
|
|
9
|
+
|
|
10
|
+
import h5py
|
|
11
|
+
import numpy as np
|
|
12
|
+
|
|
13
|
+
from .fullplot import FullPlotError, H5File as _H5File, open as _open
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class LinearizationError(FullPlotError):
|
|
17
|
+
"""An HDF5 linearization is missing, ambiguous, or malformed."""
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
@dataclass
|
|
21
|
+
class Linearization:
|
|
22
|
+
"""One saved continuous-time state-space model and its operating point."""
|
|
23
|
+
|
|
24
|
+
A: np.ndarray
|
|
25
|
+
B: np.ndarray
|
|
26
|
+
C: np.ndarray
|
|
27
|
+
D: np.ndarray
|
|
28
|
+
x0: np.ndarray
|
|
29
|
+
xdot0: np.ndarray
|
|
30
|
+
u0: np.ndarray
|
|
31
|
+
y0: np.ndarray
|
|
32
|
+
states: tuple[str, ...]
|
|
33
|
+
inputs: tuple[str, ...]
|
|
34
|
+
outputs: tuple[str, ...]
|
|
35
|
+
time: float
|
|
36
|
+
diagnostics: dict[str, Any]
|
|
37
|
+
model_options: dict[str, Any]
|
|
38
|
+
solver: str
|
|
39
|
+
run: str
|
|
40
|
+
network: str
|
|
41
|
+
path: str
|
|
42
|
+
|
|
43
|
+
def __str__(self) -> str:
|
|
44
|
+
"""Return a compact summary suitable for interactive printing."""
|
|
45
|
+
nx = len(self.states)
|
|
46
|
+
nu = len(self.inputs)
|
|
47
|
+
ny = len(self.outputs)
|
|
48
|
+
identity = " / ".join(
|
|
49
|
+
item for item in (self.network, self.solver, self.run) if item
|
|
50
|
+
)
|
|
51
|
+
title = "Linearization" if not identity else f"Linearization: {identity}"
|
|
52
|
+
dimensions = ", ".join((
|
|
53
|
+
f"{nx} state{'s' if nx != 1 else ''}",
|
|
54
|
+
f"{nu} input{'s' if nu != 1 else ''}",
|
|
55
|
+
f"{ny} output{'s' if ny != 1 else ''}",
|
|
56
|
+
))
|
|
57
|
+
return "\n".join((
|
|
58
|
+
title,
|
|
59
|
+
f" Time: {self.time:g} s",
|
|
60
|
+
f" Dimensions: {dimensions}",
|
|
61
|
+
f" Matrices: A{self.A.shape}, B{self.B.shape}, "
|
|
62
|
+
f"C{self.C.shape}, D{self.D.shape}",
|
|
63
|
+
f" Path: {self.path}",
|
|
64
|
+
))
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def _decode(value: Any) -> Any:
|
|
68
|
+
if isinstance(value, bytes):
|
|
69
|
+
return value.decode("utf-8")
|
|
70
|
+
if isinstance(value, np.generic):
|
|
71
|
+
return _decode(value.item())
|
|
72
|
+
if isinstance(value, np.ndarray):
|
|
73
|
+
return [_decode(item) for item in value.tolist()]
|
|
74
|
+
return value
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def _labels(group: h5py.Group, name: str) -> tuple[str, ...]:
|
|
78
|
+
if name not in group or not isinstance(group[name], h5py.Dataset):
|
|
79
|
+
raise LinearizationError(f"Missing {name!r} labels in {group.name}.")
|
|
80
|
+
values = group[name][()]
|
|
81
|
+
if np.asarray(values).ndim != 1:
|
|
82
|
+
raise LinearizationError(f"{group.name}/{name} must be a 1D label array.")
|
|
83
|
+
decoded = tuple(_decode(value) for value in values)
|
|
84
|
+
if any(not isinstance(value, str) for value in decoded):
|
|
85
|
+
raise LinearizationError(f"{group.name}/{name} contains non-string labels.")
|
|
86
|
+
return decoded
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def _array(group: h5py.Group, name: str, shape: tuple[int, ...]) -> np.ndarray:
|
|
90
|
+
if name not in group or not isinstance(group[name], h5py.Dataset):
|
|
91
|
+
raise LinearizationError(f"Missing dataset {group.name}/{name}.")
|
|
92
|
+
value = np.asarray(group[name][()])
|
|
93
|
+
if value.shape != shape or not np.issubdtype(value.dtype, np.number):
|
|
94
|
+
raise LinearizationError(
|
|
95
|
+
f"{group.name}/{name} must be a numeric array with shape {shape}; "
|
|
96
|
+
f"found {value.shape}."
|
|
97
|
+
)
|
|
98
|
+
return value.copy()
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def _metadata(group: h5py.Group, name: str) -> dict[str, Any]:
|
|
102
|
+
if name not in group:
|
|
103
|
+
return {}
|
|
104
|
+
node = group[name]
|
|
105
|
+
if not isinstance(node, h5py.Group):
|
|
106
|
+
raise LinearizationError(f"{group.name}/{name} must be a group.")
|
|
107
|
+
result = {key: _decode(value) for key, value in node.attrs.items()}
|
|
108
|
+
for key, item in node.items():
|
|
109
|
+
if isinstance(item, h5py.Dataset):
|
|
110
|
+
result[key] = _decode(item[()])
|
|
111
|
+
elif name == "model_options" and isinstance(item, h5py.Group):
|
|
112
|
+
option_name = _decode(item.attrs.get("name", key))
|
|
113
|
+
selected = _decode(item.attrs.get("option", ""))
|
|
114
|
+
result[option_name] = selected or None
|
|
115
|
+
return result
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
def _identity(path: str) -> tuple[str, str, str]:
|
|
119
|
+
segments = path.strip("/").split("/")
|
|
120
|
+
if "linearization" not in segments:
|
|
121
|
+
return "", "", ""
|
|
122
|
+
i = segments.index("linearization")
|
|
123
|
+
network = "/".join(segments[:i])
|
|
124
|
+
solver = segments[i + 1] if i + 1 < len(segments) else ""
|
|
125
|
+
run = ""
|
|
126
|
+
if "runs" in segments:
|
|
127
|
+
j = segments.index("runs") + 1
|
|
128
|
+
end = segments.index("points") if "points" in segments else len(segments)
|
|
129
|
+
run = "/".join(segments[j:end])
|
|
130
|
+
return network, solver, run
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def _is_result(group: h5py.Group) -> bool:
|
|
134
|
+
return isinstance(group, h5py.Group) and all(name in group for name in ("A", "B", "C", "D"))
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def _read_result(group: h5py.Group) -> Linearization:
|
|
138
|
+
if not _is_result(group):
|
|
139
|
+
raise LinearizationError(
|
|
140
|
+
f"No base linearization is stored in {group.name}. "
|
|
141
|
+
"Specify time= or times= to read saved transient points."
|
|
142
|
+
)
|
|
143
|
+
network, solver, run = _identity(group.name)
|
|
144
|
+
states = _labels(group, "states")
|
|
145
|
+
inputs = _labels(group, "inputs")
|
|
146
|
+
outputs = _labels(group, "outputs")
|
|
147
|
+
nx, nu, ny = len(states), len(inputs), len(outputs)
|
|
148
|
+
if "time" not in group or not isinstance(group["time"], h5py.Dataset):
|
|
149
|
+
raise LinearizationError(f"Missing operating time in {group.name}.")
|
|
150
|
+
time_value = np.asarray(group["time"][()])
|
|
151
|
+
if time_value.shape != () or not np.issubdtype(time_value.dtype, np.number):
|
|
152
|
+
raise LinearizationError(f"{group.name}/time must be numeric and scalar.")
|
|
153
|
+
return Linearization(
|
|
154
|
+
A=_array(group, "A", (nx, nx)),
|
|
155
|
+
B=_array(group, "B", (nx, nu)),
|
|
156
|
+
C=_array(group, "C", (ny, nx)),
|
|
157
|
+
D=_array(group, "D", (ny, nu)),
|
|
158
|
+
x0=_array(group, "x0", (nx,)),
|
|
159
|
+
xdot0=_array(group, "xdot0", (nx,)),
|
|
160
|
+
u0=_array(group, "u0", (nu,)),
|
|
161
|
+
y0=_array(group, "y0", (ny,)),
|
|
162
|
+
states=states,
|
|
163
|
+
inputs=inputs,
|
|
164
|
+
outputs=outputs,
|
|
165
|
+
time=float(time_value),
|
|
166
|
+
diagnostics=_metadata(group, "diagnostics"),
|
|
167
|
+
model_options=_metadata(group, "model_options"),
|
|
168
|
+
solver=solver,
|
|
169
|
+
run=run,
|
|
170
|
+
network=network,
|
|
171
|
+
path=group.name,
|
|
172
|
+
)
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
def _has_points(group: h5py.Group) -> bool:
|
|
176
|
+
if not isinstance(group, h5py.Group):
|
|
177
|
+
return False
|
|
178
|
+
points = group.get("points")
|
|
179
|
+
return isinstance(points, h5py.Group) and any(
|
|
180
|
+
_is_result(item) for item in points.values() if isinstance(item, h5py.Group)
|
|
181
|
+
)
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
def _runs(root: h5py.Group) -> list[h5py.Group]:
|
|
185
|
+
if (_is_result(root) or _has_points(root)) and "/points/" not in root.name:
|
|
186
|
+
return [root]
|
|
187
|
+
found: list[h5py.Group] = []
|
|
188
|
+
|
|
189
|
+
def visit(name: str, item: h5py.Group | h5py.Dataset):
|
|
190
|
+
if not (_is_result(item) or _has_points(item)):
|
|
191
|
+
return
|
|
192
|
+
path = item.name
|
|
193
|
+
if "/linearization/" in path and "/runs/" in path and "/points/" not in path:
|
|
194
|
+
found.append(item)
|
|
195
|
+
|
|
196
|
+
root.visititems(visit)
|
|
197
|
+
return sorted(found, key=lambda group: group.name)
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def _missing_scoped_run(root: h5py.Group, solver: str | None):
|
|
201
|
+
raise LinearizationError(f"Scoped linearization {root.name} does not match solver={solver!r}.")
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
def _select_run(root: h5py.Group, solver: str | None, run: str) -> h5py.Group:
|
|
205
|
+
runs = [group for group in _runs(root) if (not solver or _identity(group.name)[1] == solver)]
|
|
206
|
+
if (_is_result(root) or _has_points(root)) and "/points/" not in root.name:
|
|
207
|
+
return runs[0] if runs else _missing_scoped_run(root, solver)
|
|
208
|
+
matching = [group for group in runs if _identity(group.name)[2] == run]
|
|
209
|
+
if not matching and run == "base" and len(runs) == 1:
|
|
210
|
+
matching = runs
|
|
211
|
+
runs = matching
|
|
212
|
+
if not runs:
|
|
213
|
+
raise LinearizationError(
|
|
214
|
+
f"No linearization for solver={solver!r}, run={run!r} under {root.name}. "
|
|
215
|
+
"Call linearizations() to inspect available results."
|
|
216
|
+
)
|
|
217
|
+
if len(runs) != 1:
|
|
218
|
+
paths = ", ".join(group.name for group in runs)
|
|
219
|
+
raise LinearizationError(f"Multiple linearizations match; use .at() to select one: {paths}")
|
|
220
|
+
return runs[0]
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
def _point(run: h5py.Group, time: float) -> h5py.Group:
|
|
224
|
+
points = run.get("points")
|
|
225
|
+
matches: list[h5py.Group] = []
|
|
226
|
+
available: list[float] = []
|
|
227
|
+
if isinstance(points, h5py.Group):
|
|
228
|
+
for item in points.values():
|
|
229
|
+
if not isinstance(item, h5py.Group) or "time" not in item:
|
|
230
|
+
continue
|
|
231
|
+
value = float(item["time"][()])
|
|
232
|
+
available.append(value)
|
|
233
|
+
if isclose(value, time, rel_tol=1e-10, abs_tol=1e-12):
|
|
234
|
+
matches.append(item)
|
|
235
|
+
if len(matches) == 1:
|
|
236
|
+
return matches[0]
|
|
237
|
+
if len(matches) > 1:
|
|
238
|
+
raise LinearizationError(f"Multiple saved points match t={time:g} under {run.name}.")
|
|
239
|
+
formatted = ", ".join(f"{value:g}" for value in sorted(available)) or "none"
|
|
240
|
+
raise LinearizationError(f"No linearization saved at t={time:g}. Available point times: {formatted}.")
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
class H5File(_H5File):
|
|
244
|
+
"""FullPlot HDF5 handle with support for FullFlow linearization records."""
|
|
245
|
+
|
|
246
|
+
def at(self, group: str) -> H5File:
|
|
247
|
+
scoped = super().at(group)
|
|
248
|
+
return H5File(scoped.filename, scoped.root)
|
|
249
|
+
|
|
250
|
+
def linearization(
|
|
251
|
+
self,
|
|
252
|
+
solver: str | None = None,
|
|
253
|
+
run: str = "base",
|
|
254
|
+
time: float | None = None,
|
|
255
|
+
times: list[float] | tuple[float, ...] | None = None,
|
|
256
|
+
) -> Linearization | dict[float, Linearization]:
|
|
257
|
+
"""Read one model, or a time-keyed dictionary of saved transient models.
|
|
258
|
+
|
|
259
|
+
With no time, reads the run's base result rather than the last point.
|
|
260
|
+
A scoped result group can be read directly with ``.linearization()``.
|
|
261
|
+
"""
|
|
262
|
+
if solver not in (None, "steady_state", "transient"):
|
|
263
|
+
raise ValueError("solver must be 'steady_state' or 'transient'.")
|
|
264
|
+
if time is not None and times is not None:
|
|
265
|
+
raise ValueError("Specify time or times, not both.")
|
|
266
|
+
if times is not None and not times:
|
|
267
|
+
raise ValueError("times must not be empty.")
|
|
268
|
+
with h5py.File(self.filename, "r") as h5:
|
|
269
|
+
root = h5[self.root]
|
|
270
|
+
if _is_result(root) and "/points/" in root.name:
|
|
271
|
+
if time is not None or times is not None:
|
|
272
|
+
raise ValueError("Already scoped to a point; omit time and times.")
|
|
273
|
+
if solver and _identity(root.name)[1] != solver:
|
|
274
|
+
raise LinearizationError("The selected point does not match solver=.")
|
|
275
|
+
return _read_result(root)
|
|
276
|
+
selected = _select_run(root, solver, run)
|
|
277
|
+
if time is not None:
|
|
278
|
+
return _read_result(_point(selected, float(time)))
|
|
279
|
+
if times is not None:
|
|
280
|
+
results: dict[float, Linearization] = {}
|
|
281
|
+
for requested in times:
|
|
282
|
+
key = float(requested)
|
|
283
|
+
if key in results:
|
|
284
|
+
raise ValueError(f"Duplicate requested time: {key:g}.")
|
|
285
|
+
results[key] = _read_result(_point(selected, key))
|
|
286
|
+
return results
|
|
287
|
+
return _read_result(selected)
|
|
288
|
+
|
|
289
|
+
def linearizations(self, print_output: bool = True) -> list[dict[str, Any]]:
|
|
290
|
+
"""List available linearization runs and their saved operating times."""
|
|
291
|
+
with h5py.File(self.filename, "r") as h5:
|
|
292
|
+
root = h5[self.root]
|
|
293
|
+
found = []
|
|
294
|
+
for group in _runs(root):
|
|
295
|
+
network, solver, run = _identity(group.name)
|
|
296
|
+
points = group.get("points")
|
|
297
|
+
point_times = []
|
|
298
|
+
if isinstance(points, h5py.Group):
|
|
299
|
+
for point in points.values():
|
|
300
|
+
if isinstance(point, h5py.Group) and "time" in point:
|
|
301
|
+
point_times.append(float(point["time"][()]))
|
|
302
|
+
reference = group
|
|
303
|
+
if not _is_result(group):
|
|
304
|
+
reference = min(
|
|
305
|
+
(item for item in points.values() if _is_result(item)),
|
|
306
|
+
key=lambda item: float(item["time"][()]),
|
|
307
|
+
)
|
|
308
|
+
found.append({
|
|
309
|
+
"network": network,
|
|
310
|
+
"solver": solver,
|
|
311
|
+
"run": run,
|
|
312
|
+
"path": group.name,
|
|
313
|
+
"time": float(group["time"][()]) if _is_result(group) else None,
|
|
314
|
+
"states": len(_labels(reference, "states")),
|
|
315
|
+
"inputs": len(_labels(reference, "inputs")),
|
|
316
|
+
"outputs": len(_labels(reference, "outputs")),
|
|
317
|
+
"times": sorted(point_times),
|
|
318
|
+
})
|
|
319
|
+
if print_output:
|
|
320
|
+
for item in found:
|
|
321
|
+
print(f"{item['network']} / {item['solver']} / {item['run']}")
|
|
322
|
+
base_time = f"t={item['time']:g}" if item["time"] is not None else "not saved"
|
|
323
|
+
print(f" Base: {base_time}, {item['states']} states, "
|
|
324
|
+
f"{item['inputs']} inputs, {item['outputs']} outputs")
|
|
325
|
+
if item["times"]:
|
|
326
|
+
print(" Points: " + ", ".join(f"{t:g}" for t in item["times"]))
|
|
327
|
+
if not found:
|
|
328
|
+
print("No FullFlow linearization results found.")
|
|
329
|
+
return found
|
|
330
|
+
|
|
331
|
+
|
|
332
|
+
def open(filename: str | Path, root: str = "/") -> H5File:
|
|
333
|
+
"""Open an HDF5 file with the standard FullPlot API and linearization support."""
|
|
334
|
+
handle = _open(filename, root=root)
|
|
335
|
+
return H5File(handle.filename, handle.root)
|
fullplot/maps.py
CHANGED
|
@@ -69,6 +69,21 @@ class Axis:
|
|
|
69
69
|
units: str = ""
|
|
70
70
|
spacing: str = "values"
|
|
71
71
|
|
|
72
|
+
def __str__(self) -> str:
|
|
73
|
+
"""Return a compact summary of the map axis."""
|
|
74
|
+
values = np.asarray(self.values)
|
|
75
|
+
if values.ndim != 1 or values.size == 0:
|
|
76
|
+
value_summary = f"shape={values.shape}"
|
|
77
|
+
else:
|
|
78
|
+
units = f" {self.units}" if self.units else ""
|
|
79
|
+
point_label = "point" if values.size == 1 else "points"
|
|
80
|
+
value_summary = (
|
|
81
|
+
f"{values.size} {point_label}, {values[0]:g} to {values[-1]:g}{units}"
|
|
82
|
+
)
|
|
83
|
+
return (
|
|
84
|
+
f"Axis({self.name!r}, {value_summary}, spacing={self.spacing!r})"
|
|
85
|
+
)
|
|
86
|
+
|
|
72
87
|
@classmethod
|
|
73
88
|
def linear(
|
|
74
89
|
cls,
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: fullplot
|
|
3
|
-
Version: 0.1
|
|
4
|
-
Summary:
|
|
5
|
-
Keywords: hdf5,plotting,engineering,simulation,test-data,map-generation,scientific-computing
|
|
3
|
+
Version: 2.0.1
|
|
4
|
+
Summary: HDF5 plotting, trace processing, linearization reading, and map generation for engineering data.
|
|
5
|
+
Keywords: hdf5,plotting,engineering,simulation,test-data,linearization,state-space,map-generation,scientific-computing
|
|
6
6
|
Author: Saaketh Ramoju
|
|
7
7
|
Author-email: Saaketh Ramoju <skramoju@gmail.com>
|
|
8
8
|
License-Expression: GPL-3.0-only
|
|
@@ -30,6 +30,7 @@ Project-URL: Issues, https://github.com/saakethramoju/FullPlot/issues
|
|
|
30
30
|
Project-URL: Changelog, https://github.com/saakethramoju/FullPlot/blob/main/CHANGELOG.md
|
|
31
31
|
Project-URL: Documentation, https://github.com/saakethramoju/FullPlot#readme
|
|
32
32
|
Project-URL: PyPI, https://pypi.org/project/fullplot/
|
|
33
|
+
Provides-Extra: examples
|
|
33
34
|
Description-Content-Type: text/markdown
|
|
34
35
|
|
|
35
36
|
# FullPlot
|
|
@@ -193,6 +194,220 @@ settings = run.values("metadata")
|
|
|
193
194
|
|
|
194
195
|
---
|
|
195
196
|
|
|
197
|
+
## Reading FullFlow linearizations
|
|
198
|
+
|
|
199
|
+
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.
|
|
200
|
+
|
|
201
|
+
A continuous-time linear model takes the form
|
|
202
|
+
|
|
203
|
+
```math
|
|
204
|
+
\Delta\dot{x}=A\Delta x+B\Delta u
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
```math
|
|
208
|
+
\Delta y=C\Delta x+D\Delta u
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
where:
|
|
212
|
+
|
|
213
|
+
- `x`: physical dynamic state vector (for example stored mass or energy),
|
|
214
|
+
- `u`: selected input vector (for example valve area),
|
|
215
|
+
- `y`: selected output vector (for example chamber pressure),
|
|
216
|
+
- `A`: how state changes affect the state derivatives,
|
|
217
|
+
- `B`: how input changes affect the state derivatives,
|
|
218
|
+
- `C`: how state changes affect outputs,
|
|
219
|
+
- `D`: how input changes directly affect outputs.
|
|
220
|
+
|
|
221
|
+
`\Delta` denotes a deviation from the saved operating point. For a non-equilibrium transient point, the model also needs the saved baseline derivative:
|
|
222
|
+
|
|
223
|
+
```math
|
|
224
|
+
\dot{x}\approx\dot{x}_0+A(x-x_0)+B(u-u_0)
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
```math
|
|
228
|
+
y\approx y_0+C(x-x_0)+D(u-u_0)
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
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.
|
|
232
|
+
|
|
233
|
+
### Discover available results
|
|
234
|
+
|
|
235
|
+
```python
|
|
236
|
+
import fullplot as fplt
|
|
237
|
+
|
|
238
|
+
file = fplt.open("Linearization.h5")
|
|
239
|
+
info = file.linearizations()
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
`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.
|
|
243
|
+
|
|
244
|
+
For programmatic discovery without printing:
|
|
245
|
+
|
|
246
|
+
```python
|
|
247
|
+
info = file.linearizations(print_output=False)
|
|
248
|
+
|
|
249
|
+
for run in info:
|
|
250
|
+
print(run["solver"], run["time"], run["times"])
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
### Read one linearization
|
|
254
|
+
|
|
255
|
+
```python
|
|
256
|
+
steady = file.linearization(solver="steady_state")
|
|
257
|
+
|
|
258
|
+
print(steady.A)
|
|
259
|
+
print(steady.B)
|
|
260
|
+
print(steady.C)
|
|
261
|
+
print(steady.D)
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
Read the final/base transient result with:
|
|
265
|
+
|
|
266
|
+
```python
|
|
267
|
+
final = file.linearization(solver="transient")
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
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.
|
|
271
|
+
|
|
272
|
+
### Read transient operating points
|
|
273
|
+
|
|
274
|
+
```python
|
|
275
|
+
point = file.linearization(solver="transient", time=0.1)
|
|
276
|
+
|
|
277
|
+
print(point.time)
|
|
278
|
+
print(point.A.shape)
|
|
279
|
+
print(point.states)
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
Read several points at once:
|
|
283
|
+
|
|
284
|
+
```python
|
|
285
|
+
points = file.linearization(
|
|
286
|
+
solver="transient",
|
|
287
|
+
times=[0.1, 0.3],
|
|
288
|
+
)
|
|
289
|
+
|
|
290
|
+
for requested_time, linear in points.items():
|
|
291
|
+
print(requested_time, linear.A, linear.D)
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
`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.
|
|
295
|
+
|
|
296
|
+
Saved points can have **different numbers of states, inputs, or outputs**. FullPlot returns each result independently; it does not attempt to concatenate incompatible matrices.
|
|
297
|
+
|
|
298
|
+
### Scope into a run
|
|
299
|
+
|
|
300
|
+
```python
|
|
301
|
+
run = file.at("/Water_Flow/linearization/transient/runs/base")
|
|
302
|
+
|
|
303
|
+
point = run.linearization(time=0.1)
|
|
304
|
+
final = run.linearization()
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
A handle scoped directly to a point group can read that point without a time argument:
|
|
308
|
+
|
|
309
|
+
```python
|
|
310
|
+
point = file.at(
|
|
311
|
+
"/Water_Flow/linearization/transient/runs/base/points/0"
|
|
312
|
+
).linearization()
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
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.
|
|
316
|
+
|
|
317
|
+
### Data available in `Linearization`
|
|
318
|
+
|
|
319
|
+
| Attribute | Description |
|
|
320
|
+
| --- | --- |
|
|
321
|
+
| `A`, `B`, `C`, `D` | NumPy state-space matrices |
|
|
322
|
+
| `x0`, `xdot0`, `u0`, `y0` | Nominal states, state rates, inputs, and outputs |
|
|
323
|
+
| `states`, `inputs`, `outputs` | Ordered Python string tuples corresponding to matrix rows and columns |
|
|
324
|
+
| `time` | Operating-point time |
|
|
325
|
+
| `diagnostics` | Saved condition numbers and other numerical diagnostics |
|
|
326
|
+
| `model_options` | Saved FullFlow model-option metadata |
|
|
327
|
+
| `network`, `solver`, `run`, `path` | Source identification and HDF5 path |
|
|
328
|
+
|
|
329
|
+
Dimensions are checked on reading:
|
|
330
|
+
|
|
331
|
+
```math
|
|
332
|
+
A\in\mathbb R^{n_x\times n_x},\quad B\in\mathbb R^{n_x\times n_u},\quad
|
|
333
|
+
C\in\mathbb R^{n_y\times n_x},\quad D\in\mathbb R^{n_y\times n_u}.
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
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`.
|
|
337
|
+
|
|
338
|
+
### Using the matrices
|
|
339
|
+
|
|
340
|
+
Matrix labels determine the meaning of each row and column:
|
|
341
|
+
|
|
342
|
+
```python
|
|
343
|
+
linear = file.linearization(solver="transient", time=0.1)
|
|
344
|
+
|
|
345
|
+
state_index = linear.states.index("Pipe 1.mass_flow")
|
|
346
|
+
input_index = linear.inputs.index("Pipe 1.cross_sectional_area")
|
|
347
|
+
|
|
348
|
+
sensitivity = linear.B[state_index, input_index]
|
|
349
|
+
print(sensitivity)
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
For a small deviation from the nominal operating point:
|
|
353
|
+
|
|
354
|
+
```python
|
|
355
|
+
import numpy as np
|
|
356
|
+
|
|
357
|
+
dx = np.zeros(len(linear.states))
|
|
358
|
+
du = np.zeros(len(linear.inputs))
|
|
359
|
+
du[0] = 1e-6
|
|
360
|
+
|
|
361
|
+
xdot = linear.xdot0 + linear.A @ dx + linear.B @ du
|
|
362
|
+
y = linear.y0 + linear.C @ dx + linear.D @ du
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
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.
|
|
366
|
+
|
|
367
|
+
### FullFlow HDF5 format
|
|
368
|
+
|
|
369
|
+
The reader supports the current FullFlow per-run and per-point layout:
|
|
370
|
+
|
|
371
|
+
```text
|
|
372
|
+
Network/
|
|
373
|
+
linearization/
|
|
374
|
+
steady_state/
|
|
375
|
+
runs/
|
|
376
|
+
base/
|
|
377
|
+
A, B, C, D
|
|
378
|
+
x0, xdot0, u0, y0
|
|
379
|
+
states, inputs, outputs, time
|
|
380
|
+
diagnostics/, model_options/
|
|
381
|
+
transient/
|
|
382
|
+
runs/
|
|
383
|
+
base/
|
|
384
|
+
A, B, C, D
|
|
385
|
+
x0, xdot0, u0, y0
|
|
386
|
+
states, inputs, outputs, time
|
|
387
|
+
diagnostics/, model_options/
|
|
388
|
+
points/
|
|
389
|
+
0/
|
|
390
|
+
A, B, C, D, ...
|
|
391
|
+
time
|
|
392
|
+
1/
|
|
393
|
+
A, B, C, D, ...
|
|
394
|
+
time
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
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.
|
|
398
|
+
|
|
399
|
+
### Linearization examples
|
|
400
|
+
|
|
401
|
+
Run the small demo generator, then the two reading examples:
|
|
402
|
+
|
|
403
|
+
```bash
|
|
404
|
+
python examples/linearization/0generate_linearization_data.py
|
|
405
|
+
python examples/linearization/1inspect_linearization.py
|
|
406
|
+
python examples/linearization/2read_transient_points.py
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
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.
|
|
410
|
+
|
|
196
411
|
## Core public API
|
|
197
412
|
|
|
198
413
|
Most users only need these names:
|
|
@@ -213,6 +428,7 @@ fplt.Trace
|
|
|
213
428
|
fplt.TimeAxis
|
|
214
429
|
fplt.Axis
|
|
215
430
|
fplt.generate_map
|
|
431
|
+
fplt.Linearization
|
|
216
432
|
```
|
|
217
433
|
|
|
218
434
|
The main classes are:
|
|
@@ -223,6 +439,7 @@ The main classes are:
|
|
|
223
439
|
| `Trace` | Reusable one-dimensional x/y data object. Used for raw data, filtered data, generated limits, commands, and derived traces. |
|
|
224
440
|
| `TimeAxis` | Shared shiftable and windowable time basis. Several traces can share one axis and follow the same alignment/window. |
|
|
225
441
|
| `Axis` | Independent variable definition for rectangular-grid map generation. |
|
|
442
|
+
| `Linearization` | Labeled FullFlow state-space matrices and their saved operating point. |
|
|
226
443
|
|
|
227
444
|
Important exceptions are:
|
|
228
445
|
|
|
@@ -235,6 +452,7 @@ Important exceptions are:
|
|
|
235
452
|
| `FullPlotMapError` | Base map-generation exception. |
|
|
236
453
|
| `MapGenerationError` | Map generation failed during evaluation, resume, or file layout validation. |
|
|
237
454
|
| `MapOutputError` | The map `evaluate(...)` function returned invalid outputs. |
|
|
455
|
+
| `LinearizationError` | A saved FullFlow linearization is missing, ambiguous, or malformed. |
|
|
238
456
|
|
|
239
457
|
---
|
|
240
458
|
|
|
@@ -861,6 +1079,91 @@ run.map(
|
|
|
861
1079
|
|
|
862
1080
|
---
|
|
863
1081
|
|
|
1082
|
+
## Time-dependent numerical fields and 3D surfaces
|
|
1083
|
+
|
|
1084
|
+
A distributed simulation may record `mass_distribution`, `temperature`,
|
|
1085
|
+
`heat_flux`, or `aero_forces` as multidimensional HDF5 datasets. FullPlot can
|
|
1086
|
+
read these directly; it does not require FullFlow at plotting time.
|
|
1087
|
+
|
|
1088
|
+
For FullFlow 4.0.3 output, numeric field histories have time on axis 0:
|
|
1089
|
+
|
|
1090
|
+
| Field | Dataset shape | Interpretation |
|
|
1091
|
+
| --- | --- | --- |
|
|
1092
|
+
| Mass or temperature | `(time, station)` | One scalar per station per timestep |
|
|
1093
|
+
| Aerodynamic forces | `(time, station, 3)` | Three force components per station |
|
|
1094
|
+
| Fixed final field | `(station,)` or `(station, 3)` | No time axis |
|
|
1095
|
+
|
|
1096
|
+
FullFlow's `State(np.ndarray)` and `StateArray` are saved identically as
|
|
1097
|
+
numerical fields. The HDF5 field has a `time_axis` attribute and a reference to
|
|
1098
|
+
the time dataset. FullPlot uses this information where available, so you do not
|
|
1099
|
+
need to transpose time-first arrays just to make a heat map.
|
|
1100
|
+
|
|
1101
|
+
### Plot a FullFlow field
|
|
1102
|
+
|
|
1103
|
+
```python
|
|
1104
|
+
import fullplot as fplt
|
|
1105
|
+
|
|
1106
|
+
run = fplt.open("2thermal_cells.h5").at("Thermal_Cells/transient")
|
|
1107
|
+
field = "components/Nose_Thermal/temperature"
|
|
1108
|
+
position = "components/Nose_Thermal/stations"
|
|
1109
|
+
|
|
1110
|
+
run.map(
|
|
1111
|
+
z=field,
|
|
1112
|
+
x="time",
|
|
1113
|
+
y=position,
|
|
1114
|
+
xlabel="Time [s]",
|
|
1115
|
+
ylabel="Axial Position [m]",
|
|
1116
|
+
zlabel="Temperature [K]",
|
|
1117
|
+
)
|
|
1118
|
+
|
|
1119
|
+
run.plot(
|
|
1120
|
+
y=field,
|
|
1121
|
+
x="time",
|
|
1122
|
+
slice={1: 3}, # temperature at station index 3
|
|
1123
|
+
xlabel="Time [s]",
|
|
1124
|
+
ylabel="Temperature [K]",
|
|
1125
|
+
)
|
|
1126
|
+
|
|
1127
|
+
run.surface(
|
|
1128
|
+
z=field,
|
|
1129
|
+
x="time",
|
|
1130
|
+
y=position,
|
|
1131
|
+
xlabel="Time [s]",
|
|
1132
|
+
ylabel="Axial Position [m]",
|
|
1133
|
+
zlabel="Temperature [K]",
|
|
1134
|
+
)
|
|
1135
|
+
```
|
|
1136
|
+
|
|
1137
|
+
`map()` renders the third variable as color; `surface()` draws a true 3D
|
|
1138
|
+
Matplotlib surface. Both accept `slice=`, `save=`, `show=`, and the usual title
|
|
1139
|
+
and label arguments. `surface()` returns the figure and 3D axes, not a
|
|
1140
|
+
browser-based interactive Plotly object. For `(time, station, component)`, use
|
|
1141
|
+
`slice={2: 0}` to select a force component before plotting.
|
|
1142
|
+
|
|
1143
|
+
### Axis selection and compatibility
|
|
1144
|
+
|
|
1145
|
+
For a 2D field, `x` and `y` must match its two coordinate dimensions (center or
|
|
1146
|
+
edge arrays are supported where appropriate). FullPlot uses coordinate
|
|
1147
|
+
lengths and available `time_axis`/`time_dataset` metadata to determine the
|
|
1148
|
+
orientation. If both orientations remain possible, provide
|
|
1149
|
+
`orientation="xy"` for data indexed `[x, y]` or `orientation="yx"` for `[y, x]`.
|
|
1150
|
+
A fixed station field recorded on every step may be reduced automatically to
|
|
1151
|
+
its unchanged one-dimensional coordinate array. For generic HDF5 data without
|
|
1152
|
+
axis hints, the established row/column behavior remains available.
|
|
1153
|
+
|
|
1154
|
+
`plot()` selects the time dimension automatically if present in the metadata;
|
|
1155
|
+
for other multidimensional data, supply `axis=` or `slice=` as needed. Numeric
|
|
1156
|
+
JSON-string array histories from older FullFlow HDF5 exports can also be read
|
|
1157
|
+
with `read()` and displayed without a conversion script. Unrelated text fields
|
|
1158
|
+
remain text.
|
|
1159
|
+
|
|
1160
|
+
The standalone example
|
|
1161
|
+
[`15field_results.py`](examples/hdf5_plotting/15field_results.py) creates a
|
|
1162
|
+
numeric HDF5 field and makes a heat map, a trace, and a 3D surface. You can
|
|
1163
|
+
also pass a FullFlow thermal example's HDF5 file as its first argument.
|
|
1164
|
+
|
|
1165
|
+
---
|
|
1166
|
+
|
|
864
1167
|
## Map generation
|
|
865
1168
|
|
|
866
1169
|
FullPlot can generate simple rectangular-grid HDF5 maps.
|
|
@@ -988,11 +1291,12 @@ The CLI does not create plots. Use the Python API for plotting so scripts can co
|
|
|
988
1291
|
|
|
989
1292
|
## Examples
|
|
990
1293
|
|
|
991
|
-
The repository includes
|
|
1294
|
+
The repository includes four example folders:
|
|
992
1295
|
|
|
993
1296
|
```text
|
|
994
1297
|
examples/
|
|
995
1298
|
├── hdf5_plotting/
|
|
1299
|
+
├── linearization/
|
|
996
1300
|
├── maps/
|
|
997
1301
|
└── traces/
|
|
998
1302
|
```
|
|
@@ -1009,6 +1313,7 @@ examples/
|
|
|
1009
1313
|
* log axes and log color scales,
|
|
1010
1314
|
* multidimensional line traces,
|
|
1011
1315
|
* multidimensional slices,
|
|
1316
|
+
* native time-first field histories and 3D surface plots,
|
|
1012
1317
|
* light theme plots,
|
|
1013
1318
|
* module-level API calls,
|
|
1014
1319
|
* saving figures.
|
|
@@ -1037,6 +1342,9 @@ examples/
|
|
|
1037
1342
|
* output discovery,
|
|
1038
1343
|
* HDF5 layout inspection.
|
|
1039
1344
|
|
|
1345
|
+
`examples/linearization/` demonstrates discovering and reading saved FullFlow
|
|
1346
|
+
steady-state and transient state-space models.
|
|
1347
|
+
|
|
1040
1348
|
---
|
|
1041
1349
|
|
|
1042
1350
|
## Themes
|
|
@@ -1098,7 +1406,7 @@ This is deliberate. The package is meant to be a simple bridge between HDF5 engi
|
|
|
1098
1406
|
|
|
1099
1407
|
---
|
|
1100
1408
|
|
|
1101
|
-
|
|
1409
|
+
## Documentation
|
|
1102
1410
|
|
|
1103
1411
|
Full documentation:
|
|
1104
1412
|
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
fullplot/__init__.py,sha256=x9ww_yzw0-khKIap3ItryWS8Ddouj4LSU3Myz5ZUXfE,1091
|
|
2
|
+
fullplot/cli.py,sha256=u9OpNtKL82YLwJ3xrNgs0B3OsXjYGHFs7TgnydPBj7k,2591
|
|
3
|
+
fullplot/fullplot.py,sha256=0Bkh5FEwAj0JchxcO949erpz_OEV23vPBPFhmwo7d_E,87213
|
|
4
|
+
fullplot/hdf5.py,sha256=P3EaLWdAKQSWqwrdM_Q3eqUNycGsmrA5zND0G7KreRw,2363
|
|
5
|
+
fullplot/linearization.py,sha256=quM2RiqMSFtZ60JwFU_jVkSDjtp2xD8o2dvT2s_UwmI,13391
|
|
6
|
+
fullplot/maps.py,sha256=TSNp-ITxjCp4yMRLcrxpad3_T7sJvBvKlumI0-6Jr8k,24928
|
|
7
|
+
fullplot/themes.py,sha256=xZR44k29dCNGMwUk2CpkWLkp88mBlC7cK7O9FWmue6o,6220
|
|
8
|
+
fullplot-2.0.1.dist-info/licenses/LICENSE,sha256=ixuiBLtpoK3iv89l7ylKkg9rs2GzF9ukPH7ynZYzK5s,35148
|
|
9
|
+
fullplot-2.0.1.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
|
|
10
|
+
fullplot-2.0.1.dist-info/entry_points.txt,sha256=4jALe-r2n_VzCxE1P4AsajIpUdkPq56IZWWOlZqPrq8,48
|
|
11
|
+
fullplot-2.0.1.dist-info/METADATA,sha256=ahkfDRQxLlrVMc4XbigFSqLQXUTGrbBTji640aVwHdg,37329
|
|
12
|
+
fullplot-2.0.1.dist-info/RECORD,,
|
fullplot-0.1.1.dist-info/RECORD
DELETED
|
@@ -1,11 +0,0 @@
|
|
|
1
|
-
fullplot/__init__.py,sha256=hmctlgTH7-BzOtf8VQ2AAsNRX79--2i6tqHdabPwv80,1323
|
|
2
|
-
fullplot/cli.py,sha256=u9OpNtKL82YLwJ3xrNgs0B3OsXjYGHFs7TgnydPBj7k,2591
|
|
3
|
-
fullplot/fullplot.py,sha256=69mSqa858r37cRHyUW9MPiJpcPfnMYa__wGcEqCrqA8,80609
|
|
4
|
-
fullplot/hdf5.py,sha256=P3EaLWdAKQSWqwrdM_Q3eqUNycGsmrA5zND0G7KreRw,2363
|
|
5
|
-
fullplot/maps.py,sha256=xDUApvB-IYKtuyKiExZtx8G3XGPWc-uACsFerl0gDlQ,24322
|
|
6
|
-
fullplot/themes.py,sha256=xZR44k29dCNGMwUk2CpkWLkp88mBlC7cK7O9FWmue6o,6220
|
|
7
|
-
fullplot-0.1.1.dist-info/licenses/LICENSE,sha256=ixuiBLtpoK3iv89l7ylKkg9rs2GzF9ukPH7ynZYzK5s,35148
|
|
8
|
-
fullplot-0.1.1.dist-info/WHEEL,sha256=e4_1dyBeezi8ZjfxrZ3bnVOxFDa3ksqVqH0jTHkUZ3k,81
|
|
9
|
-
fullplot-0.1.1.dist-info/entry_points.txt,sha256=4jALe-r2n_VzCxE1P4AsajIpUdkPq56IZWWOlZqPrq8,48
|
|
10
|
-
fullplot-0.1.1.dist-info/METADATA,sha256=M3-YzwUOcZQZs65Jccr_Rx0kodM-EcbT0F4DHOUPoLI,26361
|
|
11
|
-
fullplot-0.1.1.dist-info/RECORD,,
|
|
File without changes
|
|
File without changes
|