Add CLI to run WSIMOD

.github/workflows/ci.yml

@@ -23,9 +23,11 @@ jobs:
     - uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
-  
+
     - name: Install and build
-      run: python -m pip install -r requirements-dev.txt
+      run: |
+        python -m pip install -r requirements-dev.txt
+        python -m pip install .
 
     - name: Run tests
       run: python -m pytest

.gitignore

@@ -152,4 +152,8 @@ cython_debug/
 .idea/
 
 # VScode configuration
-.vscode
+.vscode
+
+# Scratch folder to do testing
+scratch
+results

docs/demo/examples/quickstart_demo.yaml

@@ -0,0 +1,87 @@
+inputs: docs/demo/data/processed
+outputs: results/quickstart_results
+
+data:
+  my_land_data:
+    filename: timeseries_data.csv
+    filter:
+      - where: site
+        is: oxford_land
+    scaling:
+      - where: variable
+        is: precipitation
+        variable: value
+        factor: "MM_TO_M"
+    format: dict
+    index: ['variable', 'date']
+    output: 'value'
+    options: parse_dates=['date']
+
+  dates_data:
+    filename: timeseries_data.csv
+    options: usecols=['date'],parse_dates=['date']
+
+dates: data:dates_data
+
+nodes:
+- type_: Sewer
+  name: my_sewer
+  capacity: 0.04
+
+- type_: Land
+  name: my_land
+  data_input_dict: data:my_land_data
+  surfaces:
+  - type_: ImperviousSurface
+    surface: urban
+    area: 10
+    pollutant_load:
+      phosphate: 1.0e-07
+  - type_: PerviousSurface
+    surface: rural
+    area: 100
+    depth: 0.5
+    pollutant_load:
+      phosphate: 1.0e-07
+
+- type_: Groundwater
+  name: my_groundwater
+  capacity: 100
+  area: 100
+
+- type_: Node
+  name: my_river
+
+- type_: Waste
+  name: my_outlet
+
+arcs:
+- type_: Arc
+  name: urban_drainage
+  in_port: my_land
+  out_port: my_sewer
+
+- type_: Arc
+  name: percolation
+  in_port: my_land
+  out_port: my_groundwater
+
+- type_: Arc
+  name: runoff
+  in_port: my_land
+  out_port: my_river
+
+- type_: Arc
+  name: storm_outflow
+  in_port: my_sewer
+  out_port: my_river
+
+- type_: Arc
+  name: baseflow
+  in_port: my_groundwater
+  out_port: my_river
+
+- type_: Arc
+  name: catchment_outflow
+  in_port: my_river
+  out_port: my_outlet

pyproject.toml

@@ -19,9 +19,13 @@ requires-python = ">=3.9"
 dependencies = [
     "PyYAML",
     "tqdm",
-    "dill"
+    "dill",
+    "pandas"
 ]
 
+[project.scripts]
+wsimod = "wsimod.__main__:run"
+
 [project.optional-dependencies]
 dev = [
     "pytest",
@@ -33,7 +37,6 @@ dev = [
 ]
 
 demos = [
-    "pandas",
     "geopandas",
     "matplotlib",
     "shapely"

requirements-dev.txt

@@ -36,11 +36,15 @@ mypy-extensions==1.0.0
     # via black
 nodeenv==1.8.0
     # via pre-commit
+numpy==1.26.2
+    # via pandas
 packaging==23.2
     # via
     #   black
     #   build
     #   pytest
+pandas==2.1.3
+    # via wsimod (pyproject.toml)
 pathspec==0.11.2
     # via black
 pip-tools==7.3.0
@@ -61,14 +65,22 @@ pytest==7.4.3
     #   wsimod (pyproject.toml)
 pytest-cov==4.1.0
     # via wsimod (pyproject.toml)
+python-dateutil==2.8.2
+    # via pandas
+pytz==2023.3.post1
+    # via pandas
 pyyaml==6.0.1
     # via
     #   pre-commit
     #   wsimod (pyproject.toml)
 ruff==0.1.4
     # via wsimod (pyproject.toml)
+six==1.16.0
+    # via python-dateutil
 tqdm==4.66.1
     # via wsimod (pyproject.toml)
+tzdata==2023.3
+    # via pandas
 virtualenv==20.24.6
     # via pre-commit
 wheel==0.41.3

requirements.txt

@@ -2,13 +2,25 @@
 # This file is autogenerated by pip-compile with Python 3.11
 # by the following command:
 #
-#    pip-compile
+#    pip-compile --output-file=requirements.txt
 #
 colorama==0.4.6
     # via tqdm
 dill==0.3.7
     # via wsimod (pyproject.toml)
+numpy==1.26.2
+    # via pandas
+pandas==2.1.3
+    # via wsimod (pyproject.toml)
+python-dateutil==2.8.2
+    # via pandas
+pytz==2023.3.post1
+    # via pandas
 pyyaml==6.0.1
     # via wsimod (pyproject.toml)
+six==1.16.0
+    # via python-dateutil
 tqdm==4.66.1
     # via wsimod (pyproject.toml)
+tzdata==2023.3
+    # via pandas

tests/test_example_files.py

@@ -0,0 +1,20 @@
+from pytest import mark
+from pathlib import Path
+import subprocess
+
+
+def collect_examples() -> list[Path]:
+    root = Path.cwd() / "docs" / "demo" / "examples"
+    return list(root.glob("**/*.yaml"))
+
+
+@mark.parametrize("example", collect_examples())
+def test_examples(example: Path, tmp_path: Path) -> None:
+    result = subprocess.run(
+        f"wsimod {str(example)} -o {str(tmp_path)}",
+        shell=True,
+        check=True,
+    )
+    assert (tmp_path / "flows.csv").exists()
+    assert (tmp_path / "tanks.csv").exists()
+    assert (tmp_path / "surfaces.csv").exists()

wsimod/__main__.py

@@ -0,0 +1,72 @@
+"""The entry point for the myproject program."""
+from argparse import ArgumentParser
+from pathlib import Path
+from typing import Any, cast
+
+import pandas as pd
+
+from wsimod.orchestration.model import Model
+from wsimod.validation import assign_data_to_settings, load_data_files, validate_io_args
+
+
+def create_parser() -> ArgumentParser:
+    """Create the CLI argument parser."""
+    parser = ArgumentParser(prog="WSIMOD")
+    parser.add_argument(
+        "settings",
+        type=Path,
+        help="Path to the WSIMOD input file, in YAML format.",
+    )
+    parser.add_argument(
+        "--inputs",
+        "-i",
+        type=Path,
+        help="Base directory for all input files. If present, overwrites value in the"
+        " settings file.",
+    )
+    parser.add_argument(
+        "--outputs",
+        "-o",
+        type=Path,
+        help="Base directory for all output files. If present, overwrites value in the"
+        " settings file.",
+    )
+
+    return parser
+
+
+def run_model(settings: dict[str, Any], outputs: Path) -> None:
+    """Runs the mode with the chosen settings and saves the outputs as csv.
+
+    Args:
+        settings (dict[str, Any]): Settings dictionary with loaded data.
+        outputs(Path): Directory where to save the outputs.
+    """
+    model = Model()
+
+    model.dates = cast(pd.Series, settings["dates"]).drop_duplicates()
+    model.add_nodes(settings["nodes"])
+    model.add_arcs(settings["arcs"])
+
+    flows, tanks, _, surfaces = model.run()
+
+    pd.DataFrame(flows).to_csv(outputs / "flows.csv")
+    pd.DataFrame(tanks).to_csv(outputs / "tanks.csv")
+    pd.DataFrame(surfaces).to_csv(outputs / "surfaces.csv")
+
+
+def run() -> None:
+    """Main entry point of the application."""
+    args = vars(create_parser().parse_args())
+    settings = validate_io_args(**args)
+
+    inputs = settings.pop("inputs")
+    outputs = settings.pop("outputs")
+    loaded_data = load_data_files(settings.pop("data", {}), inputs)
+    loaded_settings = assign_data_to_settings(settings, loaded_data)
+
+    run_model(loaded_settings, outputs)
+
+
+if __name__ == "__main__":
+    run()