refactor(datafiles): use 0-based kstp/kper indexing, deprecate get_ks…

…tpkper()

flopy/utils/binaryfile.py

@@ -458,10 +458,12 @@ def _build_index(self):
 
         if self.nrow < 0 or self.ncol < 0:
             raise Exception("negative nrow, ncol")
-        if self.nrow > 1 and self.nrow * self.ncol > 10000000:
-            s = "Possible error. ncol ({}) * nrow ({}) > 10,000,000 "
-            s = s.format(self.ncol, self.nrow)
-            warnings.warn(s)
+
+        warn_threshold = 10000000
+        if self.nrow > 1 and self.nrow * self.ncol > warn_threshold:
+            warnings.warn(
+                f"Very large grid, ncol ({self.ncol}) * nrow ({self.nrow}) > {warn_threshold}"
+            )
         self.file.seek(0, 2)
         self.totalbytes = self.file.tell()
         self.file.seek(0, 0)
@@ -473,14 +475,14 @@ def _build_index(self):
                 continue
             if ipos == 0:
                 self.times.append(header["totim"])
-                kstpkper = (header["kstp"], header["kper"])
-                self.kstpkper.append(kstpkper)
+                self.kstpkper.append((header["kstp"] - 1, header["kper"] - 1))
             else:
                 totim = header["totim"]
                 if totim != self.times[-1]:
                     self.times.append(totim)
-                    kstpkper = (header["kstp"], header["kper"])
-                    self.kstpkper.append(kstpkper)
+                    self.kstpkper.append(
+                        (header["kstp"] - 1, header["kper"] - 1)
+                    )
             ipos = self.file.tell()
             self.iposarray.append(ipos)
             databytes = self.get_databytes(header)
@@ -609,7 +611,7 @@ class HeadFile(BinaryLayerFile):
     >>> import flopy.utils.binaryfile as bf
     >>> hdobj = bf.HeadFile('model.hds', precision='single')
     >>> hdobj.list_records()
-    >>> rec = hdobj.get_data(kstpkper=(1, 50))
+    >>> rec = hdobj.get_data(kstpkper=(0, 50))
 
     >>> ddnobj = bf.HeadFile('model.ddn', text='drawdown', precision='single')
     >>> ddnobj.list_records()
@@ -762,7 +764,7 @@ class UcnFile(BinaryLayerFile):
     >>> import flopy.utils.binaryfile as bf
     >>> ucnobj = bf.UcnFile('MT3D001.UCN', precision='single')
     >>> ucnobj.list_records()
-    >>> rec = ucnobj.get_data(kstpkper=(1,1))
+    >>> rec = ucnobj.get_data(kstpkper=(0, 0))
 
     """
 
@@ -1200,7 +1202,7 @@ def _build_index(self):
                 header["totim"] = totim
             if totim >= 0 and totim not in self.times:
                 self.times.append(totim)
-            kstpkper = (header["kstp"], header["kper"])
+            kstpkper = (header["kstp"] - 1, header["kper"] - 1)
             if kstpkper not in self.kstpkper:
                 self.kstpkper.append(kstpkper)
             if header["text"] not in self.textlist:
@@ -1505,19 +1507,18 @@ def _unique_package_names(self):
 
     def get_kstpkper(self):
         """
-        Get a list of unique stress periods and time steps in the file
+        Get stress period and time step tuples.
 
         Returns
-        ----------
-        out : list of (kstp, kper) tuples
-            List of unique kstp, kper combinations in binary file.  kstp and
-            kper values are zero-based.
+        -------
+        list of (kstp, kper) tuples
+            List of unique combinations of stress period &
+            time step indices (0-based) in the binary file
 
+        .. deprecated:: 3.5
+            Use kstpkper property instead
         """
-        kstpkper = []
-        for kstp, kper in self.kstpkper:
-            kstpkper.append((kstp - 1, kper - 1))
-        return kstpkper
+        return self.kstpkper
 
     def get_indices(self, text=None):
         """
@@ -1764,25 +1765,24 @@ def get_ts(self, idx, text=None, times=None):
         # Initialize result array and put times in first column
         result = self._init_result(nstation)
 
-        kk = self.get_kstpkper()
         timesint = self.get_times()
         if len(timesint) < 1:
             if times is None:
-                timesint = [x + 1 for x in range(len(kk))]
+                timesint = [x + 1 for x in range(len(self.kstpkper))]
             else:
                 if isinstance(times, np.ndarray):
                     times = times.tolist()
-                if len(times) != len(kk):
+                if len(times) != len(self.kstpkper):
                     raise Exception(
                         "times passed to CellBudgetFile get_ts() "
                         "method must be equal to {} "
-                        "not {}".format(len(kk), len(times))
+                        "not {}".format(len(self.kstpkper), len(times))
                     )
                 timesint = times
         for idx, t in enumerate(timesint):
             result[idx, 0] = t
 
-        for itim, k in enumerate(kk):
+        for itim, k in enumerate(self.kstpkper):
             try:
                 v = self.get_data(kstpkper=k, text=text, full3D=True)
                 # skip missing data - required for storage

flopy/utils/datafile.py

@@ -477,19 +477,18 @@ def get_times(self):
 
     def get_kstpkper(self):
         """
-        Get a list of unique stress periods and time steps in the file
+        Get stress period and time step tuples.
 
         Returns
-        ----------
-        out : list of (kstp, kper) tuples
-            List of unique kstp, kper combinations in binary file.  kstp and
-            kper values are presently zero-based.
+        -------
+        list of (kstp, kper) tuples
+            List of unique combinations of stress period &
+            time step indices (0-based) in the binary file
 
+        .. deprecated:: 3.5
+            Use kstpkper property instead
         """
-        kstpkper = []
-        for kstp, kper in self.kstpkper:
-            kstpkper.append((kstp - 1, kper - 1))
-        return kstpkper
+        return self.kstpkper
 
     def get_data(self, kstpkper=None, idx=None, totim=None, mflay=None):
         """

flopy/utils/formattedfile.py

@@ -117,7 +117,7 @@ def _build_index(self):
         Build the recordarray and iposarray, which maps the header information
         to the position in the formatted file.
         """
-        self.kstpkper  # array of time step/stress periods with data available
+        self.kstpkper  # 0-based array of time step/stress periods
         self.recordarray  # array of data headers
         self.iposarray  # array of seek positions for each record
         self.nlay  # Number of model layers
@@ -167,7 +167,7 @@ def _store_record(self, header, ipos):
         totim = header["totim"]
         if totim > 0 and totim not in self.times:
             self.times.append(totim)
-        kstpkper = (header["kstp"], header["kper"])
+        kstpkper = (header["kstp"] - 1, header["kper"] - 1)
         if kstpkper not in self.kstpkper:
             self.kstpkper.append(kstpkper)
 
@@ -356,10 +356,9 @@ class FormattedHeadFile(FormattedLayerFile):
     >>> import flopy.utils.formattedfile as ff
     >>> hdobj = ff.FormattedHeadFile('model.fhd', precision='single')
     >>> hdobj.list_records()
-    >>> rec = hdobj.get_data(kstpkper=(1, 50))
+    >>> rec = hdobj.get_data(kstpkper=(0, 50))
     >>> rec2 = ddnobj.get_data(totim=100.)
 
-
     """
 
     def __init__(