fullplot 0.1.1__tar.gz → 2.0.1__tar.gz

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

@@ -1,5 +1,19 @@
 # Changelog
 
+## 2.0.1
+
+* Added metadata/coordinate-aware numeric field orientation and H5File.surface(), with time-first line slicing and legacy FullFlow array-history reading.
+* Added standalone field plotting examples and tests for generic HDF5, coordinate validation, ambiguity and shared map/surface axes.
+
+## 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.1}/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.1
+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. |
 
 ---
 
@@ -861,6 +1079,91 @@ run.map(
 
 ---
 
+## Time-dependent numerical fields and 3D surfaces
+
+A distributed simulation may record `mass_distribution`, `temperature`,
+`heat_flux`, or `aero_forces` as multidimensional HDF5 datasets. FullPlot can
+read these directly; it does not require FullFlow at plotting time.
+
+For FullFlow 4.0.3 output, numeric field histories have time on axis 0:
+
+| Field | Dataset shape | Interpretation |
+| --- | --- | --- |
+| Mass or temperature | `(time, station)` | One scalar per station per timestep |
+| Aerodynamic forces | `(time, station, 3)` | Three force components per station |
+| Fixed final field | `(station,)` or `(station, 3)` | No time axis |
+
+FullFlow's `State(np.ndarray)` and `StateArray` are saved identically as
+numerical fields. The HDF5 field has a `time_axis` attribute and a reference to
+the time dataset. FullPlot uses this information where available, so you do not
+need to transpose time-first arrays just to make a heat map.
+
+### Plot a FullFlow field
+
+```python
+import fullplot as fplt
+
+run = fplt.open("2thermal_cells.h5").at("Thermal_Cells/transient")
+field = "components/Nose_Thermal/temperature"
+position = "components/Nose_Thermal/stations"
+
+run.map(
+    z=field,
+    x="time",
+    y=position,
+    xlabel="Time [s]",
+    ylabel="Axial Position [m]",
+    zlabel="Temperature [K]",
+)
+
+run.plot(
+    y=field,
+    x="time",
+    slice={1: 3},  # temperature at station index 3
+    xlabel="Time [s]",
+    ylabel="Temperature [K]",
+)
+
+run.surface(
+    z=field,
+    x="time",
+    y=position,
+    xlabel="Time [s]",
+    ylabel="Axial Position [m]",
+    zlabel="Temperature [K]",
+)
+```
+
+`map()` renders the third variable as color; `surface()` draws a true 3D
+Matplotlib surface. Both accept `slice=`, `save=`, `show=`, and the usual title
+and label arguments. `surface()` returns the figure and 3D axes, not a
+browser-based interactive Plotly object. For `(time, station, component)`, use
+`slice={2: 0}` to select a force component before plotting.
+
+### Axis selection and compatibility
+
+For a 2D field, `x` and `y` must match its two coordinate dimensions (center or
+edge arrays are supported where appropriate). FullPlot uses coordinate
+lengths and available `time_axis`/`time_dataset` metadata to determine the
+orientation. If both orientations remain possible, provide
+`orientation="xy"` for data indexed `[x, y]` or `orientation="yx"` for `[y, x]`.
+A fixed station field recorded on every step may be reduced automatically to
+its unchanged one-dimensional coordinate array. For generic HDF5 data without
+axis hints, the established row/column behavior remains available.
+
+`plot()` selects the time dimension automatically if present in the metadata;
+for other multidimensional data, supply `axis=` or `slice=` as needed. Numeric
+JSON-string array histories from older FullFlow HDF5 exports can also be read
+with `read()` and displayed without a conversion script. Unrelated text fields
+remain text.
+
+The standalone example
+[`15field_results.py`](examples/hdf5_plotting/15field_results.py) creates a
+numeric HDF5 field and makes a heat map, a trace, and a 3D surface. You can
+also pass a FullFlow thermal example's HDF5 file as its first argument.
+
+---
+
 ## Map generation
 
 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
 
 ## Examples
 
-The repository includes three example folders:
+The repository includes four example folders:
 
 ```text
 examples/
 ├── hdf5_plotting/
+├── linearization/
 ├── maps/
 └── traces/
 ```
@@ -1009,6 +1313,7 @@ examples/
 * log axes and log color scales,
 * multidimensional line traces,
 * multidimensional slices,
+* native time-first field histories and 3D surface plots,
 * light theme plots,
 * module-level API calls,
 * saving figures.
@@ -1037,6 +1342,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 +1406,7 @@ This is deliberate. The package is meant to be a simple bridge between HDF5 engi
 
 ---
 
-# Documentation
+## Documentation
 
 Full documentation: