fullplot 0.1.1__tar.gz → 2.0.0__tar.gz

{fullplot-0.1.1 → fullplot-2.0.0}/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2.0.0
+
+### Added
+
+* Added `H5File.linearization()` to read previously saved FullFlow steady-state and transient state-space results without installing or running FullFlow.
+* Added `H5File.linearizations()` to discover available networks, solver runs, base operating points, and saved transient point times.
+* Added the public `Linearization` data class with `A`, `B`, `C`, `D`, baseline vectors, state/input/output labels, operating time, diagnostics, model-option metadata, and source identifiers.
+* Added single-time and multiple-time transient selection through `time=` and `times=`. Multiple times return a dictionary keyed by requested time.
+
 ## 0.1.1
 
 ### Added

{fullplot-0.1.1 → fullplot-2.0.0}/PKG-INFO

@@ -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-0.1.1 → fullplot-2.0.0}/README.md

@@ -159,6 +159,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:
@@ -179,6 +393,7 @@ fplt.Trace
 fplt.TimeAxis
 fplt.Axis
 fplt.generate_map
+fplt.Linearization
 ```
 
 The main classes are:
@@ -189,6 +404,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:
 
@@ -201,6 +417,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. |
 
 ---
 
@@ -954,11 +1171,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/
 ```
@@ -1003,6 +1221,9 @@ examples/
 * output discovery,
 * HDF5 layout inspection.
 
+`examples/linearization/` demonstrates discovering and reading saved FullFlow
+steady-state and transient state-space models.
+
 ---
 
 ## Themes
@@ -1064,7 +1285,7 @@ This is deliberate. The package is meant to be a simple bridge between HDF5 engi
 
 ---
 
-# Documentation
+## Documentation
 
 Full documentation:
 

fullplot-2.0.0/examples/linearization/0generate_linearization_data.py

@@ -0,0 +1,46 @@
+"""Create a small FullFlow-style HDF5 file for the linearization reading examples.
+
+The matrices below are illustrative. No FullFlow installation is required.
+"""
+
+from pathlib import Path
+
+import h5py
+import numpy as np
+
+
+filename = Path(__file__).resolve().parent / "linearization_demo.h5"
+
+
+def write_result(group, time, gain):
+    group.attrs["solver_type"] = "transient"
+    group.create_dataset("A", data=[[-0.25 * gain]])
+    group.create_dataset("B", data=[[0.5 * gain]])
+    group.create_dataset("C", data=[[1.0]])
+    group.create_dataset("D", data=[[0.0]])
+    group.create_dataset("x0", data=[10.0 - time])
+    group.create_dataset("xdot0", data=[-0.2 * gain])
+    group.create_dataset("u0", data=[0.5])
+    group.create_dataset("y0", data=[10.0 - time])
+    labels = h5py.string_dtype("utf-8")
+    group.create_dataset("states", data=["Tank:mass"], dtype=labels)
+    group.create_dataset("inputs", data=["Valve.area"], dtype=labels)
+    group.create_dataset("outputs", data=["Tank.pressure"], dtype=labels)
+    group.create_dataset("time", data=time)
+    group.create_group("model_options")
+    diagnostics = group.create_group("diagnostics")
+    diagnostics.attrs["sensitivity_condition_number"] = 1.0
+
+
+with h5py.File(filename, "w") as h5:
+    run = h5.require_group("Tank/linearization/transient/runs/base")
+    write_result(run, 1.0, 1.0)
+    points = run.create_group("points")
+    write_result(points.create_group("0"), 0.1, 0.8)
+    write_result(points.create_group("1"), 0.3, 0.9)
+
+    steady = h5.require_group("Tank/linearization/steady_state/runs/base")
+    write_result(steady, 1.0, 1.0)
+    steady.attrs["solver_type"] = "steady_state"
+
+print("Created", filename)

fullplot-2.0.0/examples/linearization/1inspect_linearization.py

@@ -0,0 +1,29 @@
+"""Read the matrices and labels of a FullFlow linearization HDF5 file.
+
+Run 0generate_linearization_data.py first, or replace the filename with a
+linearization file generated by FullFlow.
+"""
+
+from pathlib import Path
+
+import fullplot as fplt
+
+
+example_dir = Path(__file__).resolve().parent
+filename = example_dir / "linearization_demo.h5"
+
+file = fplt.open(filename)
+file.linearizations()
+
+steady = file.linearization(solver="steady_state")
+
+print("\nSteady-state linearization")
+print("Time:", steady.time)
+print("States:", steady.states)
+print("Inputs:", steady.inputs)
+print("Outputs:", steady.outputs)
+print("A:\n", steady.A)
+print("B:\n", steady.B)
+print("C:\n", steady.C)
+print("D:\n", steady.D)
+print("Diagnostics:", steady.diagnostics)

fullplot-2.0.0/examples/linearization/2read_transient_points.py

@@ -0,0 +1,32 @@
+"""Read multiple transient operating points from a FullFlow HDF5 file.
+
+Run 0generate_linearization_data.py first, or replace the filename with a
+transient linearization file generated by FullFlow.
+"""
+
+from pathlib import Path
+
+import fullplot as fplt
+
+
+example_dir = Path(__file__).resolve().parent
+filename = example_dir / "linearization_demo.h5"
+
+file = fplt.open(filename)
+
+final = file.linearization(solver="transient")
+print("Final/base operating point:", final.time)
+print("Final A:\n", final.A)
+
+points = file.linearization(solver="transient", times=[0.1, 0.3])
+
+for time, linear in points.items():
+    print(f"\nTime: {time:g} s")
+    print("State labels:", linear.states)
+    print("Input labels:", linear.inputs)
+    print("A:\n", linear.A)
+    print("B:\n", linear.B)
+
+run = file.at("/Tank/linearization/transient/runs/base")
+point = run.linearization(time=0.1)
+print("\nScoped result at:", point.time)