fix(HeadUFile): disable get_alldata without layer (#2686)

Close #1502. The issue is that get_alldata() assumes regular structure that USG files don't have. We could return e.g. a list of arrays or some other ragged representation but I figure better to acknowledge the limitation clearly than to return something technically valid but confusing. So, block usage of the method without providing a layer.

Author: wpbonelli

autotest/test_headufile.py

@@ -149,3 +149,36 @@ def get_expected():
     expected = get_expected()
     for layer, nn in lni:
         assert expected[layer][nn] == head[layer][nn]
+
+
+@requires_exe("mfusg", "gridgen")
+@requires_pkg("shapely", "shapefile")
+def test_get_alldata_not_supported(mfusg_model):
+    # test for https://github.com/modflowpy/flopy/issues/1502
+    # get_alldata should raise NotImplementedError when mflay=None
+
+    model, head_file = mfusg_model
+
+    # Should raise NotImplementedError when mflay=None (all layers)
+    with pytest.raises(NotImplementedError) as excinfo:
+        head_file.get_alldata()
+
+    assert "mflay=None" in str(excinfo.value)
+    assert "not supported" in str(excinfo.value).lower()
+
+    # But should work fine when mflay is specified (single layer)
+    import numpy as np
+
+    alldata = head_file.get_alldata(mflay=0)
+
+    # Verify it returns a numpy array
+    assert isinstance(alldata, np.ndarray)
+
+    # Verify shape is (ntimes, ncells_in_layer)
+    times = head_file.get_times()
+    assert alldata.shape[0] == len(times)
+
+    # Verify the data matches what get_data returns for each timestep
+    for i, time in enumerate(times):
+        data = head_file.get_data(totim=time, mflay=0)
+        np.testing.assert_array_almost_equal(alldata[i], data)

flopy/utils/binaryfile/__init__.py

@@ -863,6 +863,49 @@ def get_ts(self, idx):
 
         return np.array(result)
 
+    def get_alldata(self, mflay=None, nodata=-9999):
+        """
+        Get all data from the USG head file.
+
+        Parameters
+        ----------
+        mflay : integer
+           MODFLOW zero-based layer number to return. For USG files, this
+           parameter is required (cannot be None). (Default is None.)
+
+        nodata : float
+           The nodata value in the data array.  All array values that have the
+           nodata value will be assigned np.nan.
+
+        Returns
+        -------
+        data : numpy array
+            Array has size (ntimes, ncells_in_layer) when mflay is specified.
+
+        Raises
+        ------
+        NotImplementedError
+            Raised when mflay=None. USG head files contain ragged arrays with
+            variable-sized data per layer, which cannot be converted to a
+            uniform numpy array when retrieving all layers.
+
+        Notes
+        -----
+        For MODFLOW-USG files, the mflay parameter must be specified to retrieve
+        data for a single layer across all timesteps. To get all layers for a
+        specific timestep, use get_data() instead.
+
+        """
+        if mflay is None:
+            raise NotImplementedError(
+                "get_alldata() with mflay=None is not supported for"
+                "MODFLOW-USG head files. These contain variably-size "
+                "data per layer which cannot be stacked into a numpy "
+                "array. Specify mflay to get data for a single layer "
+                "or use get_data() for specific timesteps."
+            )
+        return super().get_alldata(mflay=mflay, nodata=nodata)
+
 
 class BudgetIndexError(Exception):
     pass