remove zoh and update docs and tests

Author: paulf81

docs/timing.md

@@ -30,7 +30,7 @@ instantaneous convention.
 
 The `interpolate_df` function in `utilities.py` accepts a mandatory
 `interpolation_method` parameter that controls how numeric columns are
-resampled onto the simulation time grid.  Three methods are available:
+resampled onto the simulation time grid.  Two methods are available:
 
 #### `"averaged_to_instantaneous"` (wind, solar, and similar resource and power signals)
 
@@ -60,25 +60,6 @@ time                 value
 Querying at 13:00 yields 150 (halfway between midpoints).
 ```
 
-#### `"zoh_to_instantaneous"` (LMP, external signals)
-
-Input values are piecewise-constant (zero-order hold) with timestamps at the
-start of each interval.  Each query time receives the value of the last
-original timestamp at or before it -- the value is held constant until the
-next timestamp.  This is appropriate for signals like locational marginal
-prices (LMP) that change in discrete steps.
-
-```
-Input file:
-
-time_utc             value
-12:00                100        ← held constant over [12:00, 13:00)
-13:00                200        ← held constant over [13:00, 14:00)
-
-Querying at 12:30 yields 100.
-Querying at 13:00 yields 200.
-```
-
 #### `"instantaneous_to_instantaneous"`
 
 Input values already represent instantaneous measurements at their
@@ -87,11 +68,46 @@ original timestamps with no midpoint shift.
 
 ---
 
-In all three methods, datetime columns (e.g. `time_utc`) are linearly
+In both methods, datetime columns (e.g. `time_utc`) are linearly
 interpolated on the raw timestamps without any shift, because they are
 instantaneous coordinate mappings between simulation time and wall-clock
 time, not period-averaged measurements.
 
+#### Achieving zero-order-hold (ZOH) behaviour
+
+`interpolate_df` does not provide a dedicated zero-order-hold mode.  If you
+need step/piecewise-constant semantics -- for example, LMP prices that
+should be held constant across each reporting interval -- pre-process your
+input data to include an additional row at the end of each interval that
+carries the same value as the start-of-interval row, and then use
+`"instantaneous_to_instantaneous"`.  Linear interpolation between each pair
+of identical endpoints reproduces the ZOH shape.
+
+```
+Original data (start-of-interval only):
+
+time_utc             value
+12:00                100
+13:00                200
+
+After inserting end-of-interval rows (just before the next start):
+
+time_utc             value
+12:00                100
+12:59:59             100   ← added endpoint
+13:00                200
+13:59:59             200   ← added endpoint
+
+Querying at 12:30 with "instantaneous_to_instantaneous" yields 100.
+Querying at 13:00 yields 200.
+```
+
+See
+[`generate_locational_marginal_price_dataframe_from_gridstatus`](../hercules/grid/grid_utilities.py)
+in `hercules/grid/grid_utilities.py` for a worked example of this
+endpoint-insertion pattern (it shifts a copy of the data by `dt - 1` seconds
+and merges it back in before handing the frame to Hercules).
+
 ## Input Requirements
 
 All Hercules input files must specify start and end times using UTC datetime strings:
@@ -200,7 +216,16 @@ Both wind and solar input CSV/Feather/Parquet files must contain a `time_utc` co
 
 ### External Data (LMP, etc.)
 
-External data files loaded via `_read_external_data_file` are interpolated with `"zoh_to_instantaneous"` (zero-order hold), which is appropriate for signals like LMP prices that are piecewise-constant over each interval rather than time-averaged.
+External data files loaded via `_read_external_data_file` are upsampled onto
+the simulation time grid with `"instantaneous_to_instantaneous"` (linear
+interpolation between the supplied timestamps).  If you want zero-order-hold
+(piecewise-constant) behaviour for signals like LMP prices, pre-process the
+file to include end-of-interval rows that repeat the previous value as
+described in [Achieving zero-order-hold (ZOH) behaviour](#achieving-zero-order-hold-zoh-behaviour).
+The helper
+[`generate_locational_marginal_price_dataframe_from_gridstatus`](../hercules/grid/grid_utilities.py)
+in `hercules/grid/grid_utilities.py` is a concrete example of adding those
+endpoint rows for LMP data.
 
 ```text
 time_utc,wd_mean,ws_000,ws_001,ws_002

hercules/hercules_model.py

@@ -173,10 +173,18 @@ def _read_external_data_file(self, filename):
         Read and interpolate external data from a CSV, feather, or pickle file.
 
         This method reads external data from the specified file (CSV, feather, or
-        pickle) and interpolates it onto the simulation time grid using zero-order
-        hold (``"zoh_to_instantaneous"``).  ZOH is appropriate because external
-        signals such as LMP prices are piecewise-constant over each reporting
-        interval, unlike time-averaged weather data used by wind/solar components.
+        pickle) and upsamples it onto the simulation time grid using
+        ``"instantaneous_to_instantaneous"`` (linear interpolation between the
+        values at the supplied timestamps).
+
+        If zero-order-hold (piecewise-constant / step) behavior is desired --
+        for example, LMP prices that should be held constant across each
+        reporting interval -- the external data file must be pre-processed to
+        include an additional row at the end of each interval carrying the
+        same value.  Linear interpolation between each pair of identical
+        endpoints then reproduces the ZOH shape.  See
+        ``hercules.grid.grid_utilities.generate_locational_marginal_price_dataframe_from_gridstatus``
+        for a worked example of this endpoint-insertion pattern.
 
         The external data must include a ``time_utc`` column which will be
         converted to simulation time.  The interpolated data is stored in
@@ -222,7 +230,7 @@ def _read_external_data_file(self, filename):
 
         # Interpolate using the utility function
         df_interpolated = interpolate_df(
-            df_ext, new_times, interpolation_method="zoh_to_instantaneous"
+            df_ext, new_times, interpolation_method="instantaneous_to_instantaneous"
         )
 
         # Convert interpolated DataFrame to dictionary format

hercules/utilities.py

@@ -450,7 +450,6 @@ def close_logging(logger):
 
 _VALID_INTERPOLATION_METHODS = {
     "averaged_to_instantaneous",
-    "zoh_to_instantaneous",
     "instantaneous_to_instantaneous",
 }
 
@@ -465,10 +464,6 @@ def interpolate_df(df, new_time, interpolation_method):
       timestamps mark the **start** of each period.  Each value is assigned to
       the midpoint of its interval and then linearly interpolated.  Use for
       wind speed, solar irradiance, and similar time-averaged signals.
-    - ``"zoh_to_instantaneous"``: Input values are piecewise-constant
-      (zero-order hold) with timestamps at the start of each interval.  Each
-      query time receives the value of the last original timestamp at or
-      before it.  Use for LMP prices and other step-change signals.
     - ``"instantaneous_to_instantaneous"``: Input values already represent
       instantaneous measurements.  Standard linear interpolation is performed
       directly on the original timestamps with no midpoint shift.
@@ -477,11 +472,21 @@ def interpolate_df(df, new_time, interpolation_method):
     the raw timestamps regardless of the chosen method, because they map
     simulation time to wall-clock time directly.
 
+    Note:
+        A dedicated zero-order-hold (ZOH) mode is intentionally not provided.
+        If you need step/piecewise-constant behaviour (e.g. LMP prices that
+        should be held constant across each reporting interval), pre-process
+        the input DataFrame to include an extra row at the end of each
+        interval carrying the same value, and then call this function with
+        ``"instantaneous_to_instantaneous"``.  Linear interpolation between
+        each pair of identical endpoints reproduces the ZOH shape.  See
+        ``hercules.grid.grid_utilities.generate_locational_marginal_price_dataframe_from_gridstatus``
+        for an example of this endpoint-insertion pattern.
+
     Args:
         df (pd.DataFrame): DataFrame with 'time' column and data columns.
         new_time (array-like): New time points for interpolation.
-        interpolation_method (str): One of ``"averaged_to_instantaneous"``,
-            ``"zoh_to_instantaneous"``, or
+        interpolation_method (str): One of ``"averaged_to_instantaneous"`` or
             ``"instantaneous_to_instantaneous"``.
 
     Returns:
@@ -519,14 +524,7 @@ def interpolate_df(df, new_time, interpolation_method):
 
     for col in numeric_cols:
         col_values = df_pl[col].to_numpy()
-        if interpolation_method == "zoh_to_instantaneous":
-            indices = np.searchsorted(time_values, new_time, side="right") - 1
-            indices = np.clip(indices, 0, len(col_values) - 1)
-            interpolated_values = col_values[indices].astype(hercules_float_type)
-        else:
-            interpolated_values = np.interp(new_time, x_coords, col_values).astype(
-                hercules_float_type
-            )
+        interpolated_values = np.interp(new_time, x_coords, col_values).astype(hercules_float_type)
         result_pl = result_pl.with_columns(pl.lit(interpolated_values).alias(col))
 
     # Process datetime columns

tests/utilities_test.py

@@ -82,19 +82,6 @@ def test_downsampling():
     assert np.allclose(result["value"], expected_values)
 
 
-def test_zoh_interpolation():
-    """Test zero-order hold interpolation with interpolate_df.
-
-    Each query time should receive the value at the last original
-    timestamp at or before it (piecewise-constant / step behaviour).
-    """
-    df = pd.DataFrame({"time": [0, 5, 10], "value": [100, 200, 300]})
-    new_time = np.array([0, 2, 5, 7, 10, 12])
-    result = interpolate_df(df, new_time, interpolation_method="zoh_to_instantaneous")
-    expected = [100, 100, 200, 200, 300, 300]
-    assert np.allclose(result["value"], expected)
-
-
 def test_datetime_interpolation():
     """
     Test interpolation of datetime columns with interpolate_df function.