feat(arrays): add model.free_format_npl to control values-per-line in free-format array output (#2696)

When free_format_npl is set (e.g., model.free_format_npl = 10), free-format
arrays are written with that many values per line instead of all values on a
single line. This produces block-format output matching Groundwater Vistas
style, improving readability for large unstructured models.

Affects both INTERNAL arrays (Util2d.string) and EXTERNAL/OPENCLOSE arrays
(Util2d.get_file_entry). Default is None (no change in behavior).

Author: reneangermeyer

autotest/test_usg.py

@@ -404,3 +404,70 @@ def test_load_usg(function_tmpdir, fpth):
 
     m.change_model_ws(function_tmpdir)
     m.write_input()
+
+
+def test_free_format_npl(function_tmpdir, freyberg_usg_model_path):
+    """Test that free_format_npl controls values per line in array output."""
+    nam = "freyberg.usg.nam"
+
+    # Load model with free_format_npl=10
+    m = MfUsg.load(nam, model_ws=freyberg_usg_model_path)
+    m.free_format_npl = 10
+    m.model_ws = function_tmpdir
+    m.write_input()
+
+    # Read the written RCH file and check values per line
+    rch_file = function_tmpdir / f"{m.name}.rch"
+    assert rch_file.is_file()
+
+    with open(rch_file) as f:
+        lines = f.readlines()
+
+    # Find a data line (not a header/control record) with multiple values
+    for line in lines:
+        parts = line.strip().split()
+        if len(parts) >= 5:
+            try:
+                [float(p) for p in parts]
+                # This is a data line — verify it has at most 10 values
+                assert len(parts) <= 10, (
+                    f"Expected at most 10 values per line, got {len(parts)}"
+                )
+                break
+            except ValueError:
+                continue
+
+    # Also verify default behavior (npl=None) writes all values on one line
+    m2 = MfUsg.load(nam, model_ws=freyberg_usg_model_path)
+    assert m2.free_format_npl is None
+    out2 = function_tmpdir / "default"
+    out2.mkdir()
+    m2.model_ws = out2
+    m2.write_input()
+
+    rch_file2 = out2 / f"{m2.name}.rch"
+    with open(rch_file2) as f:
+        lines2 = f.readlines()
+
+    # Find a data line — with default npl it should have more than 10 values
+    for line in lines2:
+        parts = line.strip().split()
+        if len(parts) >= 5:
+            try:
+                [float(p) for p in parts]
+                assert len(parts) > 10, (
+                    f"Expected more than 10 values per line with default npl, "
+                    f"got {len(parts)}"
+                )
+                break
+            except ValueError:
+                continue
+
+
+def test_free_format_npl_constructor():
+    """Test that free_format_npl can be set via constructor kwarg."""
+    m = MfUsg(free_format_npl=10)
+    assert m.free_format_npl == 10
+
+    m2 = MfUsg()
+    assert m2.free_format_npl is None

flopy/mbase.py

@@ -375,6 +375,12 @@ class BaseModel(ModelInterface):
         Specify if model grid is structured (default) or unstructured.
     verbose : bool, default False
         Print additional information to the screen.
+    free_format_npl : int, optional
+        Number of values per line when writing free-format arrays. When set
+        (e.g., ``free_format_npl=10``), arrays are written with that many
+        values per line instead of all values on a single line. This produces
+        block-format output, improving readability for large models.
+        Default is None (all values on one line).
     **kwargs : dict, optional
         Used to define: ``xll``/``yll`` for the x- and y-coordinates of
         the lower-left corner of the grid, ``xul``/``yul`` for the
@@ -393,6 +399,7 @@ def __init__(
         model_ws: Union[str, PathLike] = curdir,
         structured=True,
         verbose=False,
+        free_format_npl=None,
         **kwargs,
     ):
         """Initialize BaseModel."""
@@ -453,6 +460,7 @@ def __init__(
         # external option stuff
         self.array_free_format = True
         self.free_format_input = True
+        self.free_format_npl = free_format_npl
         self.parameter_load = False
         self.array_format = None
         self.external_fnames = []

flopy/mfusg/mfusg.py

@@ -34,7 +34,12 @@ class MfUsg(Modflow):
         Location for external files.
     verbose : bool, default False
         Print additional information to the screen.
-
+    free_format_npl : int, optional
+        Number of values per line when writing free-format arrays. When set
+        (e.g., ``free_format_npl=10``), arrays are written with that many
+        values per line instead of all values on a single line. This produces
+        block-format output, improving readability for large models.
+        Default is None (all values on one line).
 
     Attributes
     ----------
@@ -65,6 +70,7 @@ def __init__(
         model_ws: Union[str, PathLike] = curdir,
         external_path=None,
         verbose=False,
+        free_format_npl=None,
         **kwargs,
     ):
         super().__init__(
@@ -77,6 +83,7 @@ def __init__(
             model_ws=model_ws,
             external_path=external_path,
             verbose=verbose,
+            free_format_npl=free_format_npl,
             **kwargs,
         )
 

flopy/modflow/mf.py

@@ -85,6 +85,12 @@ class Modflow(BaseModel):
     extra_pkgs : dict, optional
         Add custom packages classes to mfnam_packages. Allows for loading models
         with custom packages not contained in the standard flopy distribution.
+    free_format_npl : int, optional
+        Number of values per line when writing free-format arrays. When set
+        (e.g., ``free_format_npl=10``), arrays are written with that many
+        values per line instead of all values on a single line. This produces
+        block-format output, improving readability for large models.
+        Default is None (all values on one line).
 
     Attributes
     ----------
@@ -117,6 +123,7 @@ def __init__(
         external_path: Union[str, PathLike, None] = None,
         verbose=False,
         extra_pkgs: Optional[dict] = None,
+        free_format_npl=None,
         **kwargs,
     ):
         super().__init__(
@@ -126,6 +133,7 @@ def __init__(
             model_ws,
             structured=structured,
             verbose=verbose,
+            free_format_npl=free_format_npl,
             **kwargs,
         )
         self.version_types = {

flopy/utils/util_array.py

@@ -2475,11 +2475,23 @@ def get_file_entry(self, how=None):
                         self.shape, self.python_file_path, self._array, bintype="head"
                     )
                 else:
+                    # Override npl for free format if model specifies free_format_npl
+                    python_format = None
+                    if (
+                        self.format.free
+                        and self._model is not None
+                        and getattr(self._model, "free_format_npl", None) is not None
+                    ):
+                        python_format = (
+                            self._model.free_format_npl,
+                            self.format.py[1],
+                        )
                     self.write_txt(
                         self.shape,
                         self.python_file_path,
                         self._array,
                         fortran_format=self.format.fortran,
+                        python_format=python_format,
                     )
 
             elif self.__value != self.python_file_path:
@@ -2536,8 +2548,16 @@ def string(self):
 
         """
         # convert array to string with specified format
+        python_format = self.format.py
+        # Override npl for free format if model specifies free_format_npl
+        if (
+            self.format.free
+            and self._model is not None
+            and getattr(self._model, "free_format_npl", None) is not None
+        ):
+            python_format = (self._model.free_format_npl, python_format[1])
         a_string = self.array2string(
-            self.shape, self._array, python_format=self.format.py
+            self.shape, self._array, python_format=python_format
         )
         return a_string