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

fullplot/__init__.py

@@ -29,7 +29,7 @@ from fullplot.maps import (
     generate_map,
 )
 
-__version__ = "2.0.0"
+__version__ = "2.0.1"
 
 __all__ = [
     "__version__",

fullplot/fullplot.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import builtins
 import itertools
+import json
 import posixpath
 from contextlib import nullcontext
 from dataclasses import dataclass
@@ -1275,6 +1276,33 @@ def _to_numpy_index(value):
     return value
 
 
+def _dataset_array(dataset):
+    """Read native values, with a narrow fallback for old FullFlow array histories."""
+    raw = np.asarray(dataset[()])
+    if (dataset.file.attrs.get("fullflow_format") != "fullflow-simple-hdf5"
+            or raw.ndim != 1 or raw.dtype.kind not in "OSU" or not raw.size):
+        return raw
+    try:
+        values = [None if not value else np.asarray(json.loads(value)) for value in raw]
+        present = [value for value in values if value is not None]
+        if not present or any(value.ndim == 0 or value.dtype.kind not in "biufc"
+                              or value.shape != present[0].shape for value in present):
+            return raw
+        dtype = np.result_type(*(value.dtype for value in present), float)
+        return np.stack([np.full(present[0].shape, np.nan, dtype=dtype)
+                         if value is None else value for value in values])
+    except (ValueError, TypeError):
+        return raw
+
+
+def _time_dimension(dataset, array):
+    if "time_axis" in dataset.attrs:
+        return int(dataset.attrs["time_axis"])
+    if dataset.ndim == 1 and array.ndim > 1 and dataset.dtype.kind in "OSU":
+        return 0
+    return None
+
+
 def _apply_slice_for_lines(array: np.ndarray, axis: int, slice_spec) -> tuple[np.ndarray, int]:
     array = np.asarray(array)
 
@@ -1510,14 +1538,16 @@ class H5File:
     def read(self, name: str):
         """Read one dataset by absolute path, relative path, or unique short name.
 
-        The returned object is the raw NumPy value from ``h5py``. Use
+        Native datasets retain their NumPy values. Legacy FullFlow JSON array
+        histories are decoded when every sample has the same numeric shape. Use
         ``trace()`` or ``time()`` when the dataset should become a FullPlot
         object with validation and metadata.
         """
 
         with h5py.File(self.filename, "r") as h5:
             path = self._resolve_dataset_path(h5, name)
-            return h5[path][()]
+            dataset = h5[path]
+            return dataset[()] if dataset.shape == () else _dataset_array(dataset)
 
     def time(self, name: str = "time") -> TimeAxis:
         """Read a one-dimensional HDF5 dataset as a shared ``TimeAxis``.
@@ -1659,7 +1689,7 @@ class H5File:
         x=None,
         y2=None,
         slice=None,
-        axis: int = -1,
+        axis: int | None = None,
         labels=None,
         y2labels=None,
         xlabel: str | None = None,
@@ -1902,6 +1932,7 @@ class H5File:
         dpi: int = 200,
         show: bool = True,
         figsize=(8, 6),
+        orientation: str | None = None,
     ):
         """
         Plot a 2D dataset as a map.
@@ -1934,35 +1965,8 @@ class H5File:
         theme = check_theme(theme)
 
         with h5py.File(self.filename, "r") as h5:
-            z_array, z_name = self._read_map_z(h5, z)
-
-            z_array = _apply_slice_for_map(z_array, slice)
-
-            if z_array.ndim != 2:
-                raise PlotDataError(
-                    f"map requires 2D data after slicing. "
-                    f"Selected data has shape {z_array.shape}."
-                )
-
-            rows, cols = z_array.shape
-
-            x_array, x_name = self._read_map_axis(
-                h5=h5,
-                value=x,
-                default=np.arange(cols),
-                default_name="Column Index",
-                valid_lengths=(cols, cols + 1),
-                axis_name="x",
-            )
-
-            y_array, y_name = self._read_map_axis(
-                h5=h5,
-                value=y,
-                default=np.arange(rows),
-                default_name="Row Index",
-                valid_lengths=(rows, rows + 1),
-                axis_name="y",
-            )
+            x_array, y_array, z_array, x_name, y_name, z_name = self._field_data(
+                h5, z, x, y, slice, orientation)
 
         fig, ax = plt.subplots(figsize=figsize)
         apply_theme(fig, ax, theme)
@@ -2026,6 +2030,87 @@ class H5File:
 
         return fig, ax
 
+    def _field_data(self, h5, z, x, y, slice_spec, orientation):
+        if orientation not in (None, "xy", "yx"):
+            raise PlotDataError("orientation must be 'xy', 'yx', or None.")
+        data, name = self._read_map_z(h5, z)
+        time_axis = None
+        time_path = None
+        if isinstance(z, str):
+            dataset = h5[self._resolve_dataset_path(h5, z)]
+            time_axis = _time_dimension(dataset, data)
+            time_path = dataset.attrs.get("time_dataset")
+            if time_path is None and time_axis is not None and "time" in dataset.parent:
+                time_path = dataset.parent["time"].name
+        normalized = _normalize_slice_spec(slice_spec, data.ndim)
+        remaining = [axis for axis in range(data.ndim)
+                     if not _is_integer_index(normalized.get(axis, builtins.slice(None)))]
+        time_axis = remaining.index(time_axis) if time_axis in remaining else None
+        data = _apply_slice_for_map(data, slice_spec)
+        if data.ndim != 2:
+            raise PlotDataError(f"Field plotting requires 2D data after slicing; got {data.shape}.")
+        if x is None and time_axis is not None and time_path is not None:
+            x = time_path
+        x_values, x_name = self._read_map_axis(h5, x, None, "Column Index", None, "x")
+        y_values, y_name = self._read_map_axis(h5, y, None, "Row Index", None, "y")
+        candidates = []
+        for candidate in ("yx", "xy"):
+            rows, cols = data.shape if candidate == "yx" else data.shape[::-1]
+            if ((x_values is None or len(x_values) in (cols, cols + 1))
+                    and (y_values is None or len(y_values) in (rows, rows + 1))):
+                candidates.append(candidate)
+        hint = None
+        if time_axis is not None and time_path is not None:
+            for coordinate, is_x in ((x, True), (y, False)):
+                if isinstance(coordinate, str) and h5[self._resolve_dataset_path(h5, coordinate)] == h5[time_path]:
+                    hint = "xy" if (time_axis == 0) == is_x else "yx"
+        if not candidates:
+            raise PlotDataError(f"Coordinate lengths do not match field shape {data.shape}.")
+        if orientation is None:
+            if hint is not None:
+                orientation = hint
+            elif len(candidates) == 1:
+                orientation = candidates[0]
+            elif x is None and y is None:
+                orientation = "yx"
+            else:
+                raise PlotDataError("Ambiguous field orientation; specify orientation='xy' (x first) or 'yx' (y first).")
+        if orientation not in candidates:
+            raise PlotDataError(f"Coordinate lengths do not match field shape {data.shape} and orientation {orientation!r}.")
+        if orientation == "xy":
+            data = data.T
+        if x_values is None:
+            x_values = np.arange(data.shape[1])
+        if y_values is None:
+            y_values = np.arange(data.shape[0])
+        return x_values, y_values, data, x_name, y_name, name
+
+    def surface(self, z, x=None, y=None, slice=None, *, orientation=None,
+                xlabel=None, ylabel=None, zlabel=None, title=None, theme="dark",
+                save=None, dpi=200, show=False, figsize=(9, 6)):
+        """Plot a numerical 3D surface using the same axes and orientation as map()."""
+        theme = check_theme(theme)
+        with h5py.File(self.filename, "r") as h5:
+            xs, ys, values, x_name, y_name, z_name = self._field_data(
+                h5, z, x, y, slice, orientation)
+        if len(xs) == values.shape[1] + 1:
+            xs = (xs[:-1] + xs[1:]) / 2
+        if len(ys) == values.shape[0] + 1:
+            ys = (ys[:-1] + ys[1:]) / 2
+        xx, yy = np.meshgrid(xs, ys)
+        fig = plt.figure(figsize=figsize)
+        ax = fig.add_subplot(111, projection="3d")
+        apply_theme(fig, ax, theme)
+        ax.plot_surface(xx, yy, values, cmap=theme_settings(theme)["map_cmap"])
+        ax.set_xlabel(xlabel or x_name)
+        ax.set_ylabel(ylabel or y_name)
+        ax.set_zlabel(zlabel or z_name)
+        if title is not None:
+            ax.set_title(title)
+        fig.tight_layout()
+        self._save_and_show(fig, save, dpi, show)
+        return fig, ax
+
     def _resolve_dataset_path(self, h5: h5py.File, selector: str) -> str:
         if not isinstance(selector, str):
             raise DatasetNotFoundError(f"Dataset selector must be a string, got {type(selector)}.")
@@ -2239,7 +2324,10 @@ class H5File:
         path = self._resolve_dataset_path(h5, selector)
         base_label = _basename(path)
 
-        array = np.asarray(h5[path][()])
+        array = _dataset_array(h5[path])
+        if axis is None:
+            time_axis = _time_dimension(h5[path], array)
+            axis = -1 if time_axis is None else time_axis
 
         if not _is_numeric_dtype(array.dtype):
             raise PlotDataError(f"Dataset {path!r} is not numeric.")
@@ -2321,7 +2409,7 @@ class H5File:
 
             for selector in z:
                 path = self._resolve_dataset_path(h5, selector)
-                array = np.asarray(h5[path][()])
+                array = _dataset_array(h5[path])
 
                 if not _is_numeric_dtype(array.dtype):
                     raise PlotDataError(f"Dataset {path!r} is not numeric.")
@@ -2343,7 +2431,7 @@ class H5File:
 
         z_path = self._resolve_dataset_path(h5, z)
         z_name = _basename(z_path)
-        z_array = np.asarray(h5[z_path][()])
+        z_array = _dataset_array(h5[z_path])
 
         if not _is_numeric_dtype(z_array.dtype):
             raise PlotDataError("z must be numeric.")
@@ -2356,8 +2444,12 @@ class H5File:
 
         if isinstance(value, str):
             path = self._resolve_dataset_path(h5, value)
-            array = np.asarray(h5[path][()])
+            array = _dataset_array(h5[path])
             name = _basename(path)
+            if array.ndim == 2 and _time_dimension(h5[path], array) == 0:
+                if not len(array) or not np.array_equal(array, np.broadcast_to(array[0], array.shape), equal_nan=True):
+                    raise PlotDataError(f"{axis_name} coordinate history must be constant over time.")
+                array = array[0]
         else:
             array = np.asarray(value)
             name = default_name
@@ -2368,7 +2460,7 @@ class H5File:
         if not _is_numeric_dtype(array.dtype):
             raise PlotDataError(f"{axis_name} must be numeric.")
 
-        if len(array) not in valid_lengths:
+        if valid_lengths is not None and len(array) not in valid_lengths:
             valid_text = " or ".join(str(length) for length in valid_lengths)
             raise PlotDataError(
                 f"{axis_name} has length {len(array)}, but expected length {valid_text}."

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fullplot
-Version: 2.0.0
+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
@@ -1079,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.
@@ -1228,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.

fullplot-2.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+fullplot/__init__.py,sha256=x9ww_yzw0-khKIap3ItryWS8Ddouj4LSU3Myz5ZUXfE,1091
+fullplot/cli.py,sha256=u9OpNtKL82YLwJ3xrNgs0B3OsXjYGHFs7TgnydPBj7k,2591
+fullplot/fullplot.py,sha256=0Bkh5FEwAj0JchxcO949erpz_OEV23vPBPFhmwo7d_E,87213
+fullplot/hdf5.py,sha256=P3EaLWdAKQSWqwrdM_Q3eqUNycGsmrA5zND0G7KreRw,2363
+fullplot/linearization.py,sha256=quM2RiqMSFtZ60JwFU_jVkSDjtp2xD8o2dvT2s_UwmI,13391
+fullplot/maps.py,sha256=TSNp-ITxjCp4yMRLcrxpad3_T7sJvBvKlumI0-6Jr8k,24928
+fullplot/themes.py,sha256=xZR44k29dCNGMwUk2CpkWLkp88mBlC7cK7O9FWmue6o,6220
+fullplot-2.0.1.dist-info/licenses/LICENSE,sha256=ixuiBLtpoK3iv89l7ylKkg9rs2GzF9ukPH7ynZYzK5s,35148
+fullplot-2.0.1.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
+fullplot-2.0.1.dist-info/entry_points.txt,sha256=4jALe-r2n_VzCxE1P4AsajIpUdkPq56IZWWOlZqPrq8,48
+fullplot-2.0.1.dist-info/METADATA,sha256=ahkfDRQxLlrVMc4XbigFSqLQXUTGrbBTji640aVwHdg,37329
+fullplot-2.0.1.dist-info/RECORD,,

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

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

fullplot-2.0.0.dist-info/RECORD

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