Add extras rows to make Sequence quasi-2d

.github/workflows/notebooks.yml

@@ -33,5 +33,5 @@ jobs:
           - name: Install dependencies
             run: pip install nox
 
-          - name: Build documentation
+          - name: Test notebooks
             run: nox -s test-notebooks

.github/workflows/test.yml

@@ -20,7 +20,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ["3.9", "3.10", "3.11"]
+        python-version: ["3.10", "3.11"]
 
     steps:
       - uses: actions/checkout@v2

docs/reference/cli/index.md

@@ -1,4 +1,4 @@
-# ``sequence``
+# Command-line interface
 
 The *Sequence* model can be run from the command line using the
 *sequence* program.

docs/reference/cli/input_files.md

@@ -58,11 +58,34 @@ spacing = 1000.0
 ```
 
 In this case we have a grid that represents a 1D profile that consists of
-500 columns (i.e. vertical stacks) of sediment (the *n_cols* parameter).
+100 columns (i.e. vertical stacks) of sediment (the *n_cols* parameter).
 
 The *spacing* parameter is the width of each of your sediment stacks in meters.
 Thus, the length of you domain is the product of the number of columns with
-the spacing (that is, for this example, 500 * 100 m or 50 km).
+the spacing (that is, for this example, 100 * 1000 m or 100 km).
+
+You can also run *Sequence* in a quasi-2d mode in which *Sequence* models parallel
+cross-shore profiles. Each profile will have its own sediment supply that is
+transported into the ocean and then can be diffused between profiles. To set up
+such a case, the grid section can, for example, be modified in the following way,
+
+```toml
+[sequence.grid]
+shape = [3, 100]
+spacing = [10000.0, 1000.0]
+```
+In this case *Sequence* will create three parallel profiles (with an along-shore
+width of 10000.0 m).
+
+:::{note}
+The following is equivalent to the 1D example above,
+
+```toml
+[sequence.grid]
+shape = [1, 100]
+spacing = [1.0, 1000.0]
+```
+:::
 
 (the-output-section)=
 

docs/tutorials/cli/sealevel.md

@@ -27,7 +27,7 @@ we replace this section with the following,
 
 ```toml
 [sequence.sea_level]
-filepath = sealevel.csv
+filepath = "sealevel.csv"
 ```
 
 With this configuration, *Sequence* will read sea level values from this

news/78.feature

@@ -0,0 +1,3 @@
+
+Added a quasi-2d mode for *Sequence* that keeps track of multiple cross-shore
+rows.

sequence/_grid.py

@@ -15,33 +15,93 @@
 class SequenceModelGrid(RasterModelGrid):
     """Create a Landlab ModelGrid for use with Sequence."""
 
-    def __init__(self, n_cols: int, spacing: float = 100.0):
+    def __init__(
+        self, shape: int | tuple[int, int], spacing: float | tuple[float, float] = 100.0
+    ):
         """Create a *Landlab* :class:`~landlab.grid.base.ModelGrid` for use with *Sequence*.
 
         Parameters
         ----------
-        n_cols : int
-            The number of columns.
-        spacing : float, optional
-            The spacing between columns.
+        shape : int or tuple of int
+            The number of columns in the cross-shore direction or, if a ``tuple``,
+            ``(n_rows, n_cols)``  where rows are in the along-shore direction and
+            columns in the cross-shore direction.
+        spacing : float or tuple of float, optional
+            The spacing between columns or, if ``len(shape) == 2``,
+            ``(row_spacing, col_spacing)``.
 
         Examples
         --------
         >>> from sequence import SequenceModelGrid
-        >>> grid = SequenceModelGrid(500, spacing=10.0)
-        >>> grid.shape
-        (3, 500)
-        >>> grid.spacing
-        (1.0, 10.0)
+        >>> grid = SequenceModelGrid(5, spacing=10.0)
+        >>> grid.y_of_row
+        array([  0.,  1.,  2.])
+        >>> grid.x_of_column
+        array([ 0.,  10.,  20.,  30.,  40.])
+
+        >>> grid = SequenceModelGrid((3, 5), spacing=(10000.0, 10.0))
+        >>> grid.y_of_row
+        array([  0.,  10000.,  20000.,  30000., 40000.])
+        >>> grid.x_of_column
+        array([ 0.,  10.,  20.,  30.,  40.])
         """
-        super().__init__((3, n_cols), xy_spacing=(spacing, 1.0))
+        row_col_shape: list[int] = np.atleast_1d(np.asarray(shape, dtype=int))
+        row_col_spacing: list[float] = np.atleast_1d(np.asarray(spacing, dtype=float))
+
+        if (len(row_col_shape) == 1 and len(row_col_spacing) != 1) or (
+            len(row_col_shape) != 1 and len(row_col_spacing) != len(row_col_shape)
+        ):
+            raise ValueError(
+                f"spacing dimension ({len(row_col_spacing)}) does not match shape"
+                f" dimension ({len(row_col_shape)})"
+            )
+
+        if len(row_col_shape) == 1:
+            n_rows, n_cols = 1, row_col_shape[0]
+        elif len(row_col_shape) == 2:
+            n_rows, n_cols = row_col_shape
+        else:
+            raise ValueError(
+                f"invalid number of dimensions for grid ({len(row_col_shape)})"
+            )
+
+        if len(row_col_shape) == 1:
+            row_spacing, col_spacing = 1.0, row_col_spacing[0]
+        elif len(row_col_shape) == 2:
+            row_spacing, col_spacing = row_col_spacing
+
+        super().__init__((n_rows + 2, n_cols), xy_spacing=(col_spacing, row_spacing))
 
         self.status_at_node[self.nodes_at_top_edge] = self.BC_NODE_IS_CLOSED
         self.status_at_node[self.nodes_at_bottom_edge] = self.BC_NODE_IS_CLOSED
 
         self.at_node["sediment_deposit__thickness"] = self.zeros(at="node")
         self.at_grid["sea_level__elevation"] = 0.0
 
+        # self.new_field_location("row", size=int(n_rows + 2))
+        self.new_field_location("row", size=int(n_rows))
+
+    @property
+    def x_of_column(self) -> NDArray:
+        """X-coordinate for each column of the grid."""
+        return self.x_of_node[self.nodes_at_top_edge]
+
+    @property
+    def number_of_rows(self) -> int:
+        """Number of rows of nodes."""
+        return self.shape[0]
+        # return self.shape[0] - 2
+
+    @property
+    def number_of_columns(self) -> int:
+        """Number of columns of nodes."""
+        return self.shape[1]
+
+    @property
+    def y_of_row(self) -> NDArray:
+        """Y-coordinate for each row of the grid."""
+        return self.y_of_node[self.nodes_at_left_edge]
+
     def get_profile(self, name: str) -> NDArray:
         """Return the values of a field along the grid's profile.
 
@@ -55,7 +115,8 @@ def get_profile(self, name: str) -> NDArray:
         values : ndarray
             The values of the field located at the middle row of nodes.
         """
-        return self.at_node[name].reshape(self.shape)[1]
+        return self.at_node[name].reshape(self.shape)[1:-1]
+        # return self.at_node[name].reshape(self.shape)[row]
 
     @classmethod
     def from_toml(cls, filepath: os.PathLike[str]) -> "SequenceModelGrid":
@@ -85,19 +146,36 @@ def from_dict(cls, params: dict) -> "SequenceModelGrid":
         params : dict
             A dictionary that contains the parameters needed to
             create the grid.
+
+        Examples
+        --------
+        >>> from sequence import SequenceModelGrid
+        >>> params = {"shape": 5, "spacing": 10.0}
+        >>> grid = SequenceModelGrid.from_dict(params)
+        >>> grid.y_of_row
+        array([  0.,  1.,  2.])
+        >>> grid.x_of_column
+        array([ 0.,  10.,  20.,  30.,  40.])
+
+        >>> params = {"shape": (3, 5), "spacing": (10000.0, 10.0)}
+        >>> grid = SequenceModelGrid.from_dict(params)
+        >>> grid.y_of_row
+        array([  0.,  10000.,  20000.,  30000., 40000.])
+        >>> grid.x_of_column
+        array([ 0.,  10.,  20.,  30.,  40.])
         """
-        if "n_cols" in params:
-            n_cols = params["n_cols"]
-        elif "shape" in params:
-            n_cols = params["shape"][1]
+        if "shape" in params:
+            shape = params["shape"]
+        elif "n_cols" in params:
+            shape = params["n_cols"]
         else:
-            raise KeyError("n_cols")
+            raise KeyError("shape")
 
         if "spacing" in params:
             spacing = params["spacing"]
         elif "xy_spacing" in params:
-            spacing = np.broadcast_to(params["xy_spacing"], 2)[0]
+            spacing = np.atleast_1d(params["xy_spacing"])[::-1]
         else:
             raise KeyError("spacing")
 
-        return cls(n_cols, spacing=spacing)
+        return cls(shape, spacing=spacing)

sequence/cli.py

@@ -17,7 +17,7 @@
 from numpy.typing import ArrayLike
 from tqdm import tqdm
 
-from .errors import MissingRequiredVariable
+from .errors import OutputValidationError
 from .input_reader import TimeVaryingConfig
 from .logging import LoggingHandler
 from .plot import plot_file, plot_layers
@@ -381,12 +381,20 @@ def setup(set: str) -> None:
 
 
 @sequence.command()
-@click.option("--set", multiple=True, help="Set model parameters")
+@click.option("--set", "-S", multiple=True, help="Set model parameters")
+@click.argument(
+    "netcdf_file",
+    type=click.Path(
+        exists=True, file_okay=True, dir_okay=False, path_type=pathlib.Path
+    ),
+    nargs=1,
+)
 @click.pass_context
-def plot(ctx: Any, set: str) -> None:
+def plot(ctx: Any, set: str, netcdf_file) -> None:
     """Plot a Sequence output file."""
     verbose = ctx.parent.params["verbose"]
     folder = pathlib.Path.cwd()
+    path_to_file = folder / netcdf_file
 
     config = PLOT_KEYWORDS.copy()
 
@@ -398,7 +406,6 @@ def plot(ctx: Any, set: str) -> None:
         )
 
     config.update(**_load_params_from_strings(set))
-
     if verbose and len(config) > 0:
         logger.info(
             os.linesep.join(
@@ -409,14 +416,11 @@ def plot(ctx: Any, set: str) -> None:
             )
         )
 
-    logger.info(f"Plotting {folder / 'sequence.nc'}")
+    logger.info(f"Plotting {path_to_file!s}")
     try:
-        plot_file(folder / "sequence.nc", **config)
-    except MissingRequiredVariable as error:
-        logger.error(
-            f"{folder / 'sequence.nc'}: output file is missing a required variable "
-            f"({error})"
-        )
+        plot_file(path_to_file, **config)
+    except OutputValidationError as error:
+        logger.error(f"{path_to_file!s}: output file is invalid ({error!s})")
         raise click.Abort() from error
 
 

sequence/errors.py

@@ -29,15 +29,33 @@ def __str__(self) -> str:
         return self._msg
 
 
-class MissingRequiredVariable(SequenceError):
+class OutputValidationError(SequenceError):
+    """Raise this exception if there is something wrong with an output file."""
+
+    pass
+
+
+class InvalidRowError(OutputValidationError):
+    """Raise this exception if a required variable is missing from an output file."""
+
+    def __init__(self, row: int, n_rows: int):
+        self._row = row
+        self._n_rows = n_rows
+
+    def __str__(self) -> str:
+        """Return error message that includes the requested row."""
+        return f"row {self._row!r} is out of bounds for output file with {self._n_rows} rows"
+
+
+class MissingRequiredVariable(OutputValidationError):
     """Raise this exception if a required variable is missing from an output file."""
 
     def __init__(self, name: str):
         self._name = name
 
-    def __str_(self) -> str:
+    def __str__(self) -> str:
         """Return error message that includes the name of the missing variable."""
-        return f"{self._name!r}"
+        return f"requireed variable ({self._name!r}) is missing from output file"
 
 
 class ParameterMismatchError(SequenceError):