From b26fac513a6c257a75ad28a8ec1b8782e7277704 Mon Sep 17 00:00:00 2001 From: Diego Alonso Alvarez Date: Tue, 12 Dec 2023 18:05:11 +0000 Subject: [PATCH 1/5] Add publish workflow, install prettier hook and run it --- .editorconfig | 21 ++ .github/workflows/ci.yml | 24 +- .github/workflows/publish.yml | 64 +++++ .pre-commit-config.yaml | 8 +- .zenodo.json | 12 +- README.md | 18 +- docker-compose.yaml | 2 +- docs/CODE_OF_CONDUCT.md | 21 +- docs/demo/data/processed/arcs.geojson | 260 ++++++++++++++++++-- docs/demo/data/processed/nodes.geojson | 170 +++++++++++-- docs/demo/data/raw/points_locations.geojson | 172 +++++++++++-- docs/demo/examples/quickstart_demo.yaml | 104 ++++---- docs/index.md | 32 +-- docs/paper/paper.md | 114 ++++----- docs/reference-arc.md | 2 +- docs/reference-core.md | 2 +- docs/reference-other.md | 2 +- docs/stylesheets/extra.css | 6 +- docs/wsimod_models.md | 6 +- mkdocs.yml | 7 +- model_file.yaml | 1 - 21 files changed, 798 insertions(+), 250 deletions(-) create mode 100644 .editorconfig create mode 100644 .github/workflows/publish.yml diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..88f73db --- /dev/null +++ b/.editorconfig @@ -0,0 +1,21 @@ +root = true + +[*] +charset = utf-8 +insert_final_newline = true +trim_trailing_whitespace = true +indent_style = space +indent_size = 4 +max_line_length = 88 + +[*.md] +indent_size = 2 + +[*.yaml] +indent_size = 2 + +[*.yml] +indent_size = 2 + +[Makefile] +indent_style = tab \ No newline at end of file diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b7b71cf..23c6ef2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,19 +15,19 @@ jobs: strategy: fail-fast: false matrix: - os: [ ubuntu-latest, windows-latest, macos-latest] - python-version: [ "3.9", "3.10", "3.11" ] + os: [ubuntu-latest, windows-latest, macos-latest] + python-version: ["3.9", "3.10", "3.11"] steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v4 - with: - python-version: ${{ matrix.python-version }} + - uses: actions/checkout@v4 + - uses: actions/setup-python@v4 + with: + python-version: ${{ matrix.python-version }} - - name: Install and build - run: | - python -m pip install -r requirements-dev.txt - python -m pip install . + - name: Install and build + run: | + python -m pip install -r requirements-dev.txt + python -m pip install . - - name: Run tests - run: python -m pytest + - name: Run tests + run: python -m pytest diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..98cf18c --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,64 @@ +on: [release] + +jobs: + test: + uses: ./.github/workflows/ci.yml + + build-wheel: + needs: test + name: Build source distribution + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Build sdist + run: | + python -m pip install --upgrade build + python -m build + + - uses: actions/upload-artifact@v3 + with: + path: dist/wsimod + + publish-TestPyPI: + needs: build-wheel + name: Publish WSIMOD to TestPyPI + runs-on: ubuntu-latest + permissions: + id-token: write + + steps: + - name: Download sdist artifact + uses: actions/download-artifact@v3 + with: + name: artifact + path: dist + + - name: Display structure of downloaded files + run: ls -R dist + + - name: Publish package distributions to TestPyPI + uses: pypa/gh-action-pypi-publish@release/v1 + with: + repository-url: https://test.pypi.org/legacy/ + skip-existing: true + + publish-PyPI: + needs: publish-TestPyPI + name: Publish WSIMOD to PyPI + runs-on: ubuntu-latest + permissions: + id-token: write + + steps: + - name: Download sdist artifact + uses: actions/download-artifact@v3 + with: + name: artifact + path: dist + + - name: Display structure of downloaded files + run: ls -R dist + + - name: Publish package distributions to PyPI + uses: pypa/gh-action-pypi-publish@release/v1 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index be7251e..217bf00 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -9,7 +9,7 @@ repos: hooks: - id: black - repo: https://github.com/astral-sh/ruff-pre-commit - rev: 'v0.1.3' + rev: "v0.1.3" hooks: - id: ruff args: [--fix, --exit-non-zero-on-fix] @@ -21,4 +21,8 @@ repos: rev: v0.37.0 hooks: - id: markdownlint - args: ["--disable", "MD013", "MD033", "--"] \ No newline at end of file + args: ["--disable", "MD013", "MD033", "--"] + - repo: https://github.com/pre-commit/mirrors-prettier + rev: v3.1.0 + hooks: + - id: prettier diff --git a/.zenodo.json b/.zenodo.json index 79531cb..f7cddeb 100644 --- a/.zenodo.json +++ b/.zenodo.json @@ -1,14 +1,14 @@ { - "description": "Release following the JOSS review process", + "description": "Release following the JOSS review process", "license": { "id": "bsd-3-clause", "title": "BSD 3-Clause License", "url": "https://opensource.org/licenses/BSD-3-Clause" - }, - "title": "Water Systems Integrated Modelling framework, WSIMOD: A Python package for integrated modelling of water quality and quantity across the water cycle", - "version": "0.3_joss_reviewed", - "upload_type": "software", - "publication_date": "2023-02-21", + }, + "title": "Water Systems Integrated Modelling framework, WSIMOD: A Python package for integrated modelling of water quality and quantity across the water cycle", + "version": "0.3_joss_reviewed", + "upload_type": "software", + "publication_date": "2023-02-21", "creators": [ { "name": "Dobson, Barnaby", diff --git a/README.md b/README.md index f661eed..e0233a5 100644 --- a/README.md +++ b/README.md @@ -20,9 +20,9 @@ with arcs, and create simulations. You can access our documentation below or at [https://imperialcollegelondon.github.io/wsi](https://imperialcollegelondon.github.io/wsi). -*Requires*: Python 3 (tested on versions >=3.7), [tqdm](https://tqdm.github.io/), [PyYAML](https://pyyaml.org/), [dill](https://dill.readthedocs.io/en/latest/) +_Requires_: Python 3 (tested on versions >=3.7), [tqdm](https://tqdm.github.io/), [PyYAML](https://pyyaml.org/), [dill](https://dill.readthedocs.io/en/latest/) -*Optional requirements to run demos*: [Pandas](https://pandas.pydata.org/), [GeoPandas](https://geopandas.org/en/stable/), [Matplotlib](https://matplotlib.org/), [Shapely](https://shapely.readthedocs.io/en/stable/manual.html) +_Optional requirements to run demos_: [Pandas](https://pandas.pydata.org/), [GeoPandas](https://geopandas.org/en/stable/), [Matplotlib](https://matplotlib.org/), [Shapely](https://shapely.readthedocs.io/en/stable/manual.html) Please consider [contributing](./docs/CONTRIBUTING.md) and note the [code of conduct](./docs/CODE_OF_CONDUCT.md) @@ -84,13 +84,13 @@ pip install -e .[dev,demos] If you would like to use our software, please cite it using the following: - > Dobson, B., Liu, L. and Mijic, A. (2023) - ‘Water Systems Integrated Modelling framework, WSIMOD: A Python package for integrated modelling of water quality and quantity across the water cycle’, - Journal of Open Source Software. - The Open Journal, - 8(83), - p. 4996. - doi: 10.21105/joss.04996. +> Dobson, B., Liu, L. and Mijic, A. (2023) +> ‘Water Systems Integrated Modelling framework, WSIMOD: A Python package for integrated modelling of water quality and quantity across the water cycle’, +> Journal of Open Source Software. +> The Open Journal, +> 8(83), +> p. 4996. +> doi: 10.21105/joss.04996. Find the bibtex citation below: diff --git a/docker-compose.yaml b/docker-compose.yaml index b420799..38e3f7c 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -1,4 +1,4 @@ -version: '3' +version: "3" services: wsimod: build: . diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md index 45d257b..8b4fcfd 100644 --- a/docs/CODE_OF_CONDUCT.md +++ b/docs/CODE_OF_CONDUCT.md @@ -1,4 +1,3 @@ - # Contributor Covenant Code of Conduct ## Our Pledge @@ -18,23 +17,23 @@ diverse, inclusive, and healthy community. Examples of behavior that contributes to a positive environment for our community include: -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience -* Focusing on what is best not just for us as individuals, but for the overall +- Focusing on what is best not just for us as individuals, but for the overall community Examples of unacceptable behavior include: -* The use of sexualized language or imagery, and sexual attention or advances of +- The use of sexualized language or imagery, and sexual attention or advances of any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email address, +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a +- Other conduct which could reasonably be considered inappropriate in a professional setting ## Enforcement Responsibilities diff --git a/docs/demo/data/processed/arcs.geojson b/docs/demo/data/processed/arcs.geojson index 2b3eea3..e96bab1 100644 --- a/docs/demo/data/processed/arcs.geojson +++ b/docs/demo/data/processed/arcs.geojson @@ -1,27 +1,237 @@ { -"type": "FeatureCollection", -"crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:EPSG::27700" } }, -"features": [ -{ "type": "Feature", "properties": { "name": "evenlode_to_thames" }, "geometry": { "type": "LineString", "coordinates": [ [ 444803.245803258207161, 209968.835814726597164 ], [ 445807.062961385643575, 209784.700089471472893 ] ] } }, -{ "type": "Feature", "properties": { "name": "thames_to_thames" }, "geometry": { "type": "LineString", "coordinates": [ [ 444553.757344728102908, 208671.116935172060039 ], [ 445807.062961385643575, 209784.700089471472893 ] ] } }, -{ "type": "Feature", "properties": { "name": "ray_to_cherwell" }, "geometry": { "type": "LineString", "coordinates": [ [ 452334.241451664071064, 213734.77082821552176 ], [ 452377.994378837756813, 213619.382871634908952 ] ] } }, -{ "type": "Feature", "properties": { "name": "cherwell_to_cherwell" }, "geometry": { "type": "LineString", "coordinates": [ [ 448322.315483848331496, 215990.659458106965758 ], [ 452377.994378837756813, 213619.382871634908952 ] ] } }, -{ "type": "Feature", "properties": { "name": "thames_to_farmoor" }, "geometry": { "type": "LineString", "coordinates": [ [ 445807.062961385643575, 209784.700089471472893 ], [ 447193.271648206980899, 210204.39720278698951 ] ] } }, -{ "type": "Feature", "properties": { "name": "farmoor_to_mixer" }, "geometry": { "type": "LineString", "coordinates": [ [ 447193.271648206980899, 210204.39720278698951 ], [ 453086.204326246981509, 200795.47163558145985 ] ] } }, -{ "type": "Feature", "properties": { "name": "cherwell_to_mixer" }, "geometry": { "type": "LineString", "coordinates": [ [ 452377.994378837756813, 213619.382871634908952 ], [ 453086.204326246981509, 200795.47163558145985 ] ] } }, -{ "type": "Feature", "properties": { "name": "wwtw_to_mixer" }, "geometry": { "type": "LineString", "coordinates": [ [ 454354.048711575742345, 201923.415951047907583 ], [ 453086.204326246981509, 200795.47163558145985 ] ] } }, -{ "type": "Feature", "properties": { "name": "sewer_overflow" }, "geometry": { "type": "LineString", "coordinates": [ [ 453023.939232126343995, 204102.352711724466644 ], [ 453086.204326246981509, 200795.47163558145985 ] ] } }, -{ "type": "Feature", "properties": { "name": "mixer_to_waste" }, "geometry": { "type": "LineString", "coordinates": [ [ 453086.204326246981509, 200795.47163558145985 ], [ 453593.342079813068267, 197857.570163376047276 ] ] } }, -{ "type": "Feature", "properties": { "name": "abstraction_to_farmoor" }, "geometry": { "type": "LineString", "coordinates": [ [ 447193.271648206980899, 210204.39720278698951 ], [ 444554.065823141369037, 205957.430792123777792 ] ] } }, -{ "type": "Feature", "properties": { "name": "distribution_to_demand" }, "geometry": { "type": "LineString", "coordinates": [ [ 448676.107366815034766, 205941.820039099082351 ], [ 450445.334339758381248, 207120.12633056694176 ] ] } }, -{ "type": "Feature", "properties": { "name": "demand_to_sewer" }, "geometry": { "type": "LineString", "coordinates": [ [ 450445.334339758381248, 207120.12633056694176 ], [ 453023.939232126343995, 204102.352711724466644 ] ] } }, -{ "type": "Feature", "properties": { "name": "land_to_sewer" }, "geometry": { "type": "LineString", "coordinates": [ [ 451479.573614976950921, 205754.92228964145761 ], [ 453023.939232126343995, 204102.352711724466644 ] ] } }, -{ "type": "Feature", "properties": { "name": "sewer_to_wwtw" }, "geometry": { "type": "LineString", "coordinates": [ [ 453023.939232126343995, 204102.352711724466644 ], [ 454354.048711575742345, 201923.415951047907583 ] ] } }, -{ "type": "Feature", "properties": { "name": "fwtw_to_sewer" }, "geometry": { "type": "LineString", "coordinates": [ [ 445129.387841082643718, 206490.570321662002243 ], [ 453023.939232126343995, 204102.352711724466644 ] ] } }, -{ "type": "Feature", "properties": { "name": "fwtw_to_distribution" }, "geometry": { "type": "LineString", "coordinates": [ [ 445129.387841082643718, 206490.570321662002243 ], [ 448676.107366815034766, 205941.820039099082351 ] ] } }, -{ "type": "Feature", "properties": { "name": "reservoir_to_fwtw" }, "geometry": { "type": "LineString", "coordinates": [ [ 444554.065823141369037, 205957.430792123777792 ], [ 445129.387841082643718, 206490.570321662002243 ] ] } }, -{ "type": "Feature", "properties": { "name": "land_to_gw" }, "geometry": { "type": "LineString", "coordinates": [ [ 451479.573614976950921, 205754.92228964145761 ], [ 451735.32843084493652, 207240.267565301968716 ] ] } }, -{ "type": "Feature", "properties": { "name": "garden_to_gw" }, "geometry": { "type": "LineString", "coordinates": [ [ 450445.334339758381248, 207120.12633056694176 ], [ 451735.32843084493652, 207240.267565301968716 ] ] } }, -{ "type": "Feature", "properties": { "name": "gw_to_mixer" }, "geometry": { "type": "LineString", "coordinates": [ [ 451735.32843084493652, 207240.267565301968716 ], [ 453086.204326246981509, 200795.47163558145985 ] ] } } -] + "type": "FeatureCollection", + "crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:EPSG::27700" } }, + "features": [ + { + "type": "Feature", + "properties": { "name": "evenlode_to_thames" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [444803.245803258207161, 209968.835814726597164], + [445807.062961385643575, 209784.700089471472893] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "thames_to_thames" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [444553.757344728102908, 208671.116935172060039], + [445807.062961385643575, 209784.700089471472893] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "ray_to_cherwell" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [452334.241451664071064, 213734.77082821552176], + [452377.994378837756813, 213619.382871634908952] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "cherwell_to_cherwell" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [448322.315483848331496, 215990.659458106965758], + [452377.994378837756813, 213619.382871634908952] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "thames_to_farmoor" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [445807.062961385643575, 209784.700089471472893], + [447193.271648206980899, 210204.39720278698951] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "farmoor_to_mixer" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [447193.271648206980899, 210204.39720278698951], + [453086.204326246981509, 200795.47163558145985] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "cherwell_to_mixer" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [452377.994378837756813, 213619.382871634908952], + [453086.204326246981509, 200795.47163558145985] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "wwtw_to_mixer" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [454354.048711575742345, 201923.415951047907583], + [453086.204326246981509, 200795.47163558145985] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "sewer_overflow" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [453023.939232126343995, 204102.352711724466644], + [453086.204326246981509, 200795.47163558145985] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "mixer_to_waste" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [453086.204326246981509, 200795.47163558145985], + [453593.342079813068267, 197857.570163376047276] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "abstraction_to_farmoor" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [447193.271648206980899, 210204.39720278698951], + [444554.065823141369037, 205957.430792123777792] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "distribution_to_demand" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [448676.107366815034766, 205941.820039099082351], + [450445.334339758381248, 207120.12633056694176] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "demand_to_sewer" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [450445.334339758381248, 207120.12633056694176], + [453023.939232126343995, 204102.352711724466644] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "land_to_sewer" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [451479.573614976950921, 205754.92228964145761], + [453023.939232126343995, 204102.352711724466644] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "sewer_to_wwtw" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [453023.939232126343995, 204102.352711724466644], + [454354.048711575742345, 201923.415951047907583] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "fwtw_to_sewer" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [445129.387841082643718, 206490.570321662002243], + [453023.939232126343995, 204102.352711724466644] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "fwtw_to_distribution" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [445129.387841082643718, 206490.570321662002243], + [448676.107366815034766, 205941.820039099082351] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "reservoir_to_fwtw" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [444554.065823141369037, 205957.430792123777792], + [445129.387841082643718, 206490.570321662002243] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "land_to_gw" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [451479.573614976950921, 205754.92228964145761], + [451735.32843084493652, 207240.267565301968716] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "garden_to_gw" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [450445.334339758381248, 207120.12633056694176], + [451735.32843084493652, 207240.267565301968716] + ] + } + }, + { + "type": "Feature", + "properties": { "name": "gw_to_mixer" }, + "geometry": { + "type": "LineString", + "coordinates": [ + [451735.32843084493652, 207240.267565301968716], + [453086.204326246981509, 200795.47163558145985] + ] + } + } + ] } diff --git a/docs/demo/data/processed/nodes.geojson b/docs/demo/data/processed/nodes.geojson index 47eafc9..eb971b3 100644 --- a/docs/demo/data/processed/nodes.geojson +++ b/docs/demo/data/processed/nodes.geojson @@ -1,24 +1,150 @@ { -"type": "FeatureCollection", -"crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:EPSG::27700" } }, -"features": [ -{ "type": "Feature", "properties": { "name": "farmoor_abstraction", "type_": "Node" }, "geometry": { "type": "Point", "coordinates": [ 447193.271648206980899, 210204.39720278698951 ] } }, -{ "type": "Feature", "properties": { "name": "thames", "type_": "Catchment" }, "geometry": { "type": "Point", "coordinates": [ 444553.757344728102908, 208671.116935172060039 ] } }, -{ "type": "Feature", "properties": { "name": "evenlode", "type_": "Catchment" }, "geometry": { "type": "Point", "coordinates": [ 444803.245803258207161, 209968.835814726597164 ] } }, -{ "type": "Feature", "properties": { "name": "ray", "type_": "Catchment" }, "geometry": { "type": "Point", "coordinates": [ 452334.241451664071064, 213734.77082821552176 ] } }, -{ "type": "Feature", "properties": { "name": "cherwell", "type_": "Catchment" }, "geometry": { "type": "Point", "coordinates": [ 448322.315483848331496, 215990.659458106965758 ] } }, -{ "type": "Feature", "properties": { "name": "oxford_fwtw", "type_": "FWTW" }, "geometry": { "type": "Point", "coordinates": [ 445129.387841082643718, 206490.570321662002243 ] } }, -{ "type": "Feature", "properties": { "name": "oxford_wwtw", "type_": "WWTW" }, "geometry": { "type": "Point", "coordinates": [ 454354.048711575742345, 201923.415951047907583 ] } }, -{ "type": "Feature", "properties": { "name": "thames_mixer", "type_": "Node" }, "geometry": { "type": "Point", "coordinates": [ 453086.204326246981509, 200795.47163558145985 ] } }, -{ "type": "Feature", "properties": { "name": "thames_above_abingdon", "type_": "Waste" }, "geometry": { "type": "Point", "coordinates": [ 453593.342079813068267, 197857.570163376047276 ] } }, -{ "type": "Feature", "properties": { "name": "oxford", "type_": "Demand" }, "geometry": { "type": "Point", "coordinates": [ 450445.334339758381248, 207120.12633056694176 ] } }, -{ "type": "Feature", "properties": { "name": "gw", "type_": "Groundwater" }, "geometry": { "type": "Point", "coordinates": [ 451735.32843084493652, 207240.267565301968716 ] } }, -{ "type": "Feature", "properties": { "name": "oxford_land", "type_": "Land" }, "geometry": { "type": "Point", "coordinates": [ 451479.573614976950921, 205754.92228964145761 ] } }, -{ "type": "Feature", "properties": { "name": "combined_sewer", "type_": "Sewer" }, "geometry": { "type": "Point", "coordinates": [ 453023.939232126343995, 204102.352711724466644 ] } }, -{ "type": "Feature", "properties": { "name": "oxford_distribution", "type_": "Node" }, "geometry": { "type": "Point", "coordinates": [ 448676.107366815034766, 205941.820039099082351 ] } }, -{ "type": "Feature", "properties": { "name": "evenlode_thames", "type_": "Node" }, "geometry": { "type": "Point", "coordinates": [ 445807.062961385643575, 209784.700089471472893 ] } }, -{ "type": "Feature", "properties": { "name": "cherwell_ray", "type_": "Node" }, "geometry": { "type": "Point", "coordinates": [ 452377.994378837756813, 213619.382871634908952 ] } }, -{ "type": "Feature", "properties": { "name": "cherwell_thames", "type_": "Node" }, "geometry": { "type": "Point", "coordinates": [ 451992.722700056387112, 205054.875454529828858 ] } }, -{ "type": "Feature", "properties": { "name": "farmoor", "type_": "Reservoir" }, "geometry": { "type": "Point", "coordinates": [ 444554.065823141369037, 205957.430792123777792 ] } } -] + "type": "FeatureCollection", + "crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:EPSG::27700" } }, + "features": [ + { + "type": "Feature", + "properties": { "name": "farmoor_abstraction", "type_": "Node" }, + "geometry": { + "type": "Point", + "coordinates": [447193.271648206980899, 210204.39720278698951] + } + }, + { + "type": "Feature", + "properties": { "name": "thames", "type_": "Catchment" }, + "geometry": { + "type": "Point", + "coordinates": [444553.757344728102908, 208671.116935172060039] + } + }, + { + "type": "Feature", + "properties": { "name": "evenlode", "type_": "Catchment" }, + "geometry": { + "type": "Point", + "coordinates": [444803.245803258207161, 209968.835814726597164] + } + }, + { + "type": "Feature", + "properties": { "name": "ray", "type_": "Catchment" }, + "geometry": { + "type": "Point", + "coordinates": [452334.241451664071064, 213734.77082821552176] + } + }, + { + "type": "Feature", + "properties": { "name": "cherwell", "type_": "Catchment" }, + "geometry": { + "type": "Point", + "coordinates": [448322.315483848331496, 215990.659458106965758] + } + }, + { + "type": "Feature", + "properties": { "name": "oxford_fwtw", "type_": "FWTW" }, + "geometry": { + "type": "Point", + "coordinates": [445129.387841082643718, 206490.570321662002243] + } + }, + { + "type": "Feature", + "properties": { "name": "oxford_wwtw", "type_": "WWTW" }, + "geometry": { + "type": "Point", + "coordinates": [454354.048711575742345, 201923.415951047907583] + } + }, + { + "type": "Feature", + "properties": { "name": "thames_mixer", "type_": "Node" }, + "geometry": { + "type": "Point", + "coordinates": [453086.204326246981509, 200795.47163558145985] + } + }, + { + "type": "Feature", + "properties": { "name": "thames_above_abingdon", "type_": "Waste" }, + "geometry": { + "type": "Point", + "coordinates": [453593.342079813068267, 197857.570163376047276] + } + }, + { + "type": "Feature", + "properties": { "name": "oxford", "type_": "Demand" }, + "geometry": { + "type": "Point", + "coordinates": [450445.334339758381248, 207120.12633056694176] + } + }, + { + "type": "Feature", + "properties": { "name": "gw", "type_": "Groundwater" }, + "geometry": { + "type": "Point", + "coordinates": [451735.32843084493652, 207240.267565301968716] + } + }, + { + "type": "Feature", + "properties": { "name": "oxford_land", "type_": "Land" }, + "geometry": { + "type": "Point", + "coordinates": [451479.573614976950921, 205754.92228964145761] + } + }, + { + "type": "Feature", + "properties": { "name": "combined_sewer", "type_": "Sewer" }, + "geometry": { + "type": "Point", + "coordinates": [453023.939232126343995, 204102.352711724466644] + } + }, + { + "type": "Feature", + "properties": { "name": "oxford_distribution", "type_": "Node" }, + "geometry": { + "type": "Point", + "coordinates": [448676.107366815034766, 205941.820039099082351] + } + }, + { + "type": "Feature", + "properties": { "name": "evenlode_thames", "type_": "Node" }, + "geometry": { + "type": "Point", + "coordinates": [445807.062961385643575, 209784.700089471472893] + } + }, + { + "type": "Feature", + "properties": { "name": "cherwell_ray", "type_": "Node" }, + "geometry": { + "type": "Point", + "coordinates": [452377.994378837756813, 213619.382871634908952] + } + }, + { + "type": "Feature", + "properties": { "name": "cherwell_thames", "type_": "Node" }, + "geometry": { + "type": "Point", + "coordinates": [451992.722700056387112, 205054.875454529828858] + } + }, + { + "type": "Feature", + "properties": { "name": "farmoor", "type_": "Reservoir" }, + "geometry": { + "type": "Point", + "coordinates": [444554.065823141369037, 205957.430792123777792] + } + } + ] } diff --git a/docs/demo/data/raw/points_locations.geojson b/docs/demo/data/raw/points_locations.geojson index 3a11bcc..9ef2370 100644 --- a/docs/demo/data/raw/points_locations.geojson +++ b/docs/demo/data/raw/points_locations.geojson @@ -1,25 +1,151 @@ { -"type": "FeatureCollection", -"name": "points_locations", -"crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:EPSG::27700" } }, -"features": [ -{ "type": "Feature", "properties": { "name": "farmoor_abstraction" }, "geometry": { "type": "Point", "coordinates": [ 447193.271648206980899, 210204.39720278698951 ] } }, -{ "type": "Feature", "properties": { "name": "thames" }, "geometry": { "type": "Point", "coordinates": [ 444553.757344728102908, 208671.116935172060039 ] } }, -{ "type": "Feature", "properties": { "name": "evenlode" }, "geometry": { "type": "Point", "coordinates": [ 444803.245803258207161, 209968.835814726597164 ] } }, -{ "type": "Feature", "properties": { "name": "ray" }, "geometry": { "type": "Point", "coordinates": [ 452334.241451664071064, 213734.77082821552176 ] } }, -{ "type": "Feature", "properties": { "name": "cherwell" }, "geometry": { "type": "Point", "coordinates": [ 448322.315483848331496, 215990.659458106965758 ] } }, -{ "type": "Feature", "properties": { "name": "oxford_fwtw" }, "geometry": { "type": "Point", "coordinates": [ 445129.387841082643718, 206490.570321662002243 ] } }, -{ "type": "Feature", "properties": { "name": "oxford_wwtw" }, "geometry": { "type": "Point", "coordinates": [ 454354.048711575742345, 201923.415951047907583 ] } }, -{ "type": "Feature", "properties": { "name": "thames_mixer" }, "geometry": { "type": "Point", "coordinates": [ 453086.204326246981509, 200795.47163558145985 ] } }, -{ "type": "Feature", "properties": { "name": "thames_above_abingdon" }, "geometry": { "type": "Point", "coordinates": [ 453593.342079813068267, 197857.570163376047276 ] } }, -{ "type": "Feature", "properties": { "name": "oxford" }, "geometry": { "type": "Point", "coordinates": [ 450445.334339758381248, 207120.12633056694176 ] } }, -{ "type": "Feature", "properties": { "name": "gw" }, "geometry": { "type": "Point", "coordinates": [ 451735.32843084493652, 207240.267565301968716 ] } }, -{ "type": "Feature", "properties": { "name": "oxford_land" }, "geometry": { "type": "Point", "coordinates": [ 451479.573614976950921, 205754.92228964145761 ] } }, -{ "type": "Feature", "properties": { "name": "combined_sewer" }, "geometry": { "type": "Point", "coordinates": [ 453023.939232126343995, 204102.352711724466644 ] } }, -{ "type": "Feature", "properties": { "name": "oxford_distribution" }, "geometry": { "type": "Point", "coordinates": [ 448676.107366815034766, 205941.820039099082351 ] } }, -{ "type": "Feature", "properties": { "name": "evenlode_thames" }, "geometry": { "type": "Point", "coordinates": [ 445807.062961385643575, 209784.700089471472893 ] } }, -{ "type": "Feature", "properties": { "name": "cherwell_ray" }, "geometry": { "type": "Point", "coordinates": [ 452377.994378837756813, 213619.382871634908952 ] } }, -{ "type": "Feature", "properties": { "name": "cherwell_thames" }, "geometry": { "type": "Point", "coordinates": [ 451992.722700056387112, 205054.875454529828858 ] } }, -{ "type": "Feature", "properties": { "name": "farmoor" }, "geometry": { "type": "Point", "coordinates": [ 444554.065823141369037, 205957.430792123777792 ] } } -] + "type": "FeatureCollection", + "name": "points_locations", + "crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:EPSG::27700" } }, + "features": [ + { + "type": "Feature", + "properties": { "name": "farmoor_abstraction" }, + "geometry": { + "type": "Point", + "coordinates": [447193.271648206980899, 210204.39720278698951] + } + }, + { + "type": "Feature", + "properties": { "name": "thames" }, + "geometry": { + "type": "Point", + "coordinates": [444553.757344728102908, 208671.116935172060039] + } + }, + { + "type": "Feature", + "properties": { "name": "evenlode" }, + "geometry": { + "type": "Point", + "coordinates": [444803.245803258207161, 209968.835814726597164] + } + }, + { + "type": "Feature", + "properties": { "name": "ray" }, + "geometry": { + "type": "Point", + "coordinates": [452334.241451664071064, 213734.77082821552176] + } + }, + { + "type": "Feature", + "properties": { "name": "cherwell" }, + "geometry": { + "type": "Point", + "coordinates": [448322.315483848331496, 215990.659458106965758] + } + }, + { + "type": "Feature", + "properties": { "name": "oxford_fwtw" }, + "geometry": { + "type": "Point", + "coordinates": [445129.387841082643718, 206490.570321662002243] + } + }, + { + "type": "Feature", + "properties": { "name": "oxford_wwtw" }, + "geometry": { + "type": "Point", + "coordinates": [454354.048711575742345, 201923.415951047907583] + } + }, + { + "type": "Feature", + "properties": { "name": "thames_mixer" }, + "geometry": { + "type": "Point", + "coordinates": [453086.204326246981509, 200795.47163558145985] + } + }, + { + "type": "Feature", + "properties": { "name": "thames_above_abingdon" }, + "geometry": { + "type": "Point", + "coordinates": [453593.342079813068267, 197857.570163376047276] + } + }, + { + "type": "Feature", + "properties": { "name": "oxford" }, + "geometry": { + "type": "Point", + "coordinates": [450445.334339758381248, 207120.12633056694176] + } + }, + { + "type": "Feature", + "properties": { "name": "gw" }, + "geometry": { + "type": "Point", + "coordinates": [451735.32843084493652, 207240.267565301968716] + } + }, + { + "type": "Feature", + "properties": { "name": "oxford_land" }, + "geometry": { + "type": "Point", + "coordinates": [451479.573614976950921, 205754.92228964145761] + } + }, + { + "type": "Feature", + "properties": { "name": "combined_sewer" }, + "geometry": { + "type": "Point", + "coordinates": [453023.939232126343995, 204102.352711724466644] + } + }, + { + "type": "Feature", + "properties": { "name": "oxford_distribution" }, + "geometry": { + "type": "Point", + "coordinates": [448676.107366815034766, 205941.820039099082351] + } + }, + { + "type": "Feature", + "properties": { "name": "evenlode_thames" }, + "geometry": { + "type": "Point", + "coordinates": [445807.062961385643575, 209784.700089471472893] + } + }, + { + "type": "Feature", + "properties": { "name": "cherwell_ray" }, + "geometry": { + "type": "Point", + "coordinates": [452377.994378837756813, 213619.382871634908952] + } + }, + { + "type": "Feature", + "properties": { "name": "cherwell_thames" }, + "geometry": { + "type": "Point", + "coordinates": [451992.722700056387112, 205054.875454529828858] + } + }, + { + "type": "Feature", + "properties": { "name": "farmoor" }, + "geometry": { + "type": "Point", + "coordinates": [444554.065823141369037, 205957.430792123777792] + } + } + ] } diff --git a/docs/demo/examples/quickstart_demo.yaml b/docs/demo/examples/quickstart_demo.yaml index 167dfc9..123d255 100644 --- a/docs/demo/examples/quickstart_demo.yaml +++ b/docs/demo/examples/quickstart_demo.yaml @@ -13,8 +13,8 @@ data: variable: value factor: "MM_TO_M" format: dict - index: ['variable', 'date'] - output: 'value' + index: ["variable", "date"] + output: "value" options: parse_dates=['date'] dates_data: @@ -24,64 +24,64 @@ data: dates: data:dates_data nodes: -- type_: Sewer - name: my_sewer - capacity: 0.04 + - 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_: 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_: Groundwater + name: my_groundwater + capacity: 100 + area: 100 -- type_: Node - name: my_river + - type_: Node + name: my_river -- type_: Waste - name: my_outlet + - type_: Waste + name: my_outlet arcs: -- type_: Arc - name: urban_drainage - in_port: my_land - out_port: my_sewer + - 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: percolation + in_port: my_land + out_port: my_groundwater -- type_: Arc - name: runoff - in_port: my_land - out_port: my_river + - 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: 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: baseflow + in_port: my_groundwater + out_port: my_river -- type_: Arc - name: catchment_outflow - in_port: my_river - out_port: my_outlet + - type_: Arc + name: catchment_outflow + in_port: my_river + out_port: my_outlet diff --git a/docs/index.md b/docs/index.md index 9c352ae..50a17d8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -32,43 +32,43 @@ and consists of: 3. [Tutorials](tutorials.md) - 3.1. [Quickstart](./demo/scripts/quickstart_demo.py) + 3.1. [Quickstart](./demo/scripts/quickstart_demo.py) - 3.2. [WSIMOD model demonstration - Oxford](./demo/scripts/oxford_demo.py) + 3.2. [WSIMOD model demonstration - Oxford](./demo/scripts/oxford_demo.py) - 3.3. [Land nodes - hydrology and agriculture](./demo/scripts/land_demo.py) + 3.3. [Land nodes - hydrology and agriculture](./demo/scripts/land_demo.py) - 3.4. [Model object - WSIMOD models](wsimod_models.md) + 3.4. [Model object - WSIMOD models](wsimod_models.md) 4. [How-To Guides](how-to.md) - 4.1. [Customise a node](./demo/scripts/customise_a_node.py) + 4.1. [Customise a node](./demo/scripts/customise_a_node.py) - 4.2. [Customise an arc](./demo/scripts/customise_an_arc.py) + 4.2. [Customise an arc](./demo/scripts/customise_an_arc.py) - 4.3. [Customise interactions](./demo/scripts/customise_interactions.py) + 4.3. [Customise interactions](./demo/scripts/customise_interactions.py) 5. [Component library](component-library.md) 6. [API reference](reference.md) - 6.1. [API reference - arc](reference-arc.md) + 6.1. [API reference - arc](reference-arc.md) - 6.2. [API reference - core](reference-core.md) + 6.2. [API reference - core](reference-core.md) - 6.3. [API reference - land](reference-land.md) + 6.3. [API reference - land](reference-land.md) - 6.4. [API reference - nodes](reference-nodes.md) + 6.4. [API reference - nodes](reference-nodes.md) - 6.5. [API reference - sewer](reference-sewer.md) + 6.5. [API reference - sewer](reference-sewer.md) - 6.6. [API reference - storage (reservoir, river, groundwater)](reference-storage.md) + 6.6. [API reference - storage (reservoir, river, groundwater)](reference-storage.md) - 6.7. [API reference - wtw](reference-wtw.md) + 6.7. [API reference - wtw](reference-wtw.md) - 6.8. [API reference - other components](reference-other.md) + 6.8. [API reference - other components](reference-other.md) - 6.9. [API reference - model](reference-model.md) + 6.9. [API reference - model](reference-model.md) 7. [Coverage](coverage.md) diff --git a/docs/paper/paper.md b/docs/paper/paper.md index 0c3d14b..f51dcfc 100644 --- a/docs/paper/paper.md +++ b/docs/paper/paper.md @@ -1,5 +1,5 @@ --- -title: 'Water Systems Integrated Modelling framework, WSIMOD: A Python package for integrated modelling of water quality and quantity across the water cycle' +title: "Water Systems Integrated Modelling framework, WSIMOD: A Python package for integrated modelling of water quality and quantity across the water cycle" tags: - Python - water quality @@ -17,93 +17,93 @@ authors: orcid: 0000-0001-7096-9405 affiliation: 1 affiliations: - - name: Department of Civil and Environmental Engineering, Imperial College London, UK - index: 1 + - name: Department of Civil and Environmental Engineering, Imperial College London, UK + index: 1 date: 04 November 2022 bibliography: paper.bib - --- # Summary -The water cycle is highly interconnected; water fluxes in one part depend on -physical and human processes throughout. For example, rivers are a water -supply, a receiver of wastewater, and an aggregate of many hydrological, +The water cycle is highly interconnected; water fluxes in one part depend on +physical and human processes throughout. For example, rivers are a water +supply, a receiver of wastewater, and an aggregate of many hydrological, biological, and chemical processes. Thus, simulations of the water cycle that -have highly constrained boundaries may miss key interactions that create -unanticipated impacts or unexpected opportunities [@Dobson:2020;@Liu:2022]. -Integrated environmental models aim to resolve the issue of boundary -conditions, however they have some key limitations [@Rauch:2017], and in -particular we find a significant need for a parsimonious, self-contained suite -that is accessible and easy to setup. +have highly constrained boundaries may miss key interactions that create +unanticipated impacts or unexpected opportunities [@Dobson:2020;@Liu:2022]. +Integrated environmental models aim to resolve the issue of boundary +conditions, however they have some key limitations [@Rauch:2017], and in +particular we find a significant need for a parsimonious, self-contained suite +that is accessible and easy to setup. # Statement of need -Traditional approaches to water system modelling broadly fall into highly -numerical models that excel in representing individual subsystems, or systems -dynamics models that create broad representations but that lack a physical -basis. Early attempts at a physical representation of the water cycle combined -existing numerical models through an integration framework [@Rauch:2017]. While -successful, this approach has an incredibly high user burden because each -subsystem model is so detailed, and as a consequence is also difficult to -customise. To illustrate, SWAT is one of the most widespread models of the -rural water cycle [@Arnold:2012], while SWMM is the same but for the urban -water cycle [@Gironas:2010]. It has been demonstrated that these two software -can interface using the OpenMI integration framework [@Shrestha:2013]. Despite -this seemingly powerful combination of two near-ubiquitous models, integrated -applications have been limited, and we propose that this is for the same -reasons presented in [@Rauch:2017]: user burden and customisation difficulty. +Traditional approaches to water system modelling broadly fall into highly +numerical models that excel in representing individual subsystems, or systems +dynamics models that create broad representations but that lack a physical +basis. Early attempts at a physical representation of the water cycle combined +existing numerical models through an integration framework [@Rauch:2017]. While +successful, this approach has an incredibly high user burden because each +subsystem model is so detailed, and as a consequence is also difficult to +customise. To illustrate, SWAT is one of the most widespread models of the +rural water cycle [@Arnold:2012], while SWMM is the same but for the urban +water cycle [@Gironas:2010]. It has been demonstrated that these two software +can interface using the OpenMI integration framework [@Shrestha:2013]. Despite +this seemingly powerful combination of two near-ubiquitous models, integrated +applications have been limited, and we propose that this is for the same +reasons presented in [@Rauch:2017]: user burden and customisation difficulty. -Because of this need, we provide a parsimonious and self-contained suite for integrated water cycle modelling in the WSIMOD Python package. It -brings together a range of software developed over the course of three years -on the [CAMELLIA project](https://www.camelliawater.org/). Urban water -processes are based on those presented and validated in the CityWat +Because of this need, we provide a parsimonious and self-contained suite for integrated water cycle modelling in the WSIMOD Python package. It +brings together a range of software developed over the course of three years +on the [CAMELLIA project](https://www.camelliawater.org/). Urban water +processes are based on those presented and validated in the CityWat model [@Dobson:2020;@Dobson:2021;@Dobson:2022;@Muhandes:2022], while -hydrological and agricultural processes are from the CatchWat +hydrological and agricultural processes are from the CatchWat model [@Liu:2022;@Liu:2022b]. WSIMOD also provides an interface for message -passing between different model components, enabling all parts of the water +passing between different model components, enabling all parts of the water cycle to interact with all other parts. The result is a simulation model that is easy to set up, highly flexible and ideal for representing water quality and -quantity in 'non-textbook' water systems (which in our experience is nearly -all of them). +quantity in 'non-textbook' water systems (which in our experience is nearly +all of them). -The package provides a variety of tutorials and examples to help modellers -create nodes (i.e., representations of subsystems within the water cycle), -connect them together with arcs (i.e., representing the fluxes between -subsystems), and orchestrate them into a model that creates simulations. +The package provides a variety of tutorials and examples to help modellers +create nodes (i.e., representations of subsystems within the water cycle), +connect them together with arcs (i.e., representing the fluxes between +subsystems), and orchestrate them into a model that creates simulations. ## Limitations -We highlight that WSIMOD is not intended to be a substitute for sophisticated -physical models, nor for a system dynamics approach. In applications where -detailed hydraulic/hydrological process representations are needed (e.g., + +We highlight that WSIMOD is not intended to be a substitute for sophisticated +physical models, nor for a system dynamics approach. In applications where +detailed hydraulic/hydrological process representations are needed (e.g., informing the design of specific pipes, cases where processes are hard to -quantify such as representing social drivers of population growth, etc.) there -are likely better tools available. Our case studies highlight -that WSIMOD is most useful in situations where physically representing -cross-sytem processes and thus capturing the impacts of cross-system -interactions are essential towards the questions you ask of your model. -Secondary benefits are that the parsimonious representations utilised are -computationally fast and flexible in capturing a wide range of system +quantify such as representing social drivers of population growth, etc.) there +are likely better tools available. Our case studies highlight +that WSIMOD is most useful in situations where physically representing +cross-sytem processes and thus capturing the impacts of cross-system +interactions are essential towards the questions you ask of your model. +Secondary benefits are that the parsimonious representations utilised are +computationally fast and flexible in capturing a wide range of system interventions. # Acknowledgements -WSIMOD was developed by [Barnaby Dobson](https://github.com/barneydobson) and [Leyang Liu](https://github.com/liuly12). +WSIMOD was developed by [Barnaby Dobson](https://github.com/barneydobson) and [Leyang Liu](https://github.com/liuly12). Theoretical support was provided by Ana Mijic. -Testing the WSIMOD over a variety of applications has been performed by +Testing the WSIMOD over a variety of applications has been performed by Fangjun Peng, Vladimir Krivstov and Samer Muhandes. -Software development support was provided by Imperial College's Research +Software development support was provided by Imperial College's Research Software Engineering service, in particular from Diego Alonso and Dan Davies. We are incredibly grateful for the detailed software reviews provided by [Taher Chegini](https://github.com/cheginit) and [Joshua Larsen](https://github.com/jlarsen-usgs) and editing by [Chris Vernon](https://github.com/crvernon). Their suggestions have significantly improved WSIMOD. -The design of WSIMOD was significantly influenced by -[CityDrain3](https://github.com/gregorburger/CityDrain3) [@Burger:2016], -[OpenMI](https://www.ogc.org/standards/openmi) [@Gregersen:2007], [smif](https://github.com/tomalrussell/smif) [@smif_paper;@smif_software], and the +The design of WSIMOD was significantly influenced by +[CityDrain3](https://github.com/gregorburger/CityDrain3) [@Burger:2016], +[OpenMI](https://www.ogc.org/standards/openmi) [@Gregersen:2007], [smif](https://github.com/tomalrussell/smif) [@smif_paper;@smif_software], and the following review [@Belete:2017]. -We acknowledge funding from the CAMELLIA project (Community Water Management -for a Liveable London), funded by the Natural Environment Research Council +We acknowledge funding from the CAMELLIA project (Community Water Management +for a Liveable London), funded by the Natural Environment Research Council (NERC) under grant NE/S003495/1. # References diff --git a/docs/reference-arc.md b/docs/reference-arc.md index 7a6ebf0..80a4bdc 100644 --- a/docs/reference-arc.md +++ b/docs/reference-arc.md @@ -1,5 +1,5 @@ # API Reference - Arcs -This section of the documentation provides a reference for the API of the arcs.arcs module. +This section of the documentation provides a reference for the API of the arcs.arcs module. ::: wsimod.arcs.arcs diff --git a/docs/reference-core.md b/docs/reference-core.md index 120868a..0eeb97a 100644 --- a/docs/reference-core.md +++ b/docs/reference-core.md @@ -1,6 +1,6 @@ # API Reference - Core -This section of the documentation provides a reference for the API of the core.core and core.constants modules. +This section of the documentation provides a reference for the API of the core.core and core.constants modules. ::: wsimod.core.core ::: wsimod.core.constants diff --git a/docs/reference-other.md b/docs/reference-other.md index f74e639..47dd9a0 100644 --- a/docs/reference-other.md +++ b/docs/reference-other.md @@ -1,6 +1,6 @@ # API Reference - Other Components -This section of the documentation provides a reference for the API of the nodes.catchment, nodes.demand, nodes.distribution, and nodes.waste modules. +This section of the documentation provides a reference for the API of the nodes.catchment, nodes.demand, nodes.distribution, and nodes.waste modules. ::: wsimod.nodes.catchment ::: wsimod.nodes.demand diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 2b6d2e0..310282a 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -1,14 +1,14 @@ /* Indentation. */ div.doc-contents:not(.first) { padding-left: 25px; - border-left: .05rem solid var(--md-typeset-table-color); + border-left: 0.05rem solid var(--md-typeset-table-color); } /* Mark external links as such. */ a.autorefs-external::after { /* https://primer.style/octicons/arrow-up-right-24 */ background-image: url('data:image/svg+xml,'); - content: ' '; + content: " "; display: inline-block; position: relative; @@ -24,4 +24,4 @@ a.autorefs-external::after { a.autorefs-external:hover::after { background-color: var(--md-accent-fg-color); -} \ No newline at end of file +} diff --git a/docs/wsimod_models.md b/docs/wsimod_models.md index 7b97577..711e970 100644 --- a/docs/wsimod_models.md +++ b/docs/wsimod_models.md @@ -3,9 +3,9 @@ 1. [Introduction](#introduction) 2. [What data do you need](#what-data-do-you-need) 3. [WSIMOD model](#wsimod-model) - 3.1. [Nodes](#nodes) - 3.2. [Arcs](#arcs) - 3.3. [Model properties](#model-properties) + 3.1. [Nodes](#nodes) + 3.2. [Arcs](#arcs) + 3.3. [Model properties](#model-properties) 4. [Input data](#input-data) 5. [Limitations](#limitations) diff --git a/mkdocs.yml b/mkdocs.yml index e69c37a..106e218 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,7 +6,6 @@ theme: extra_css: - stylesheets/extra.css - plugins: - mkdocstrings - mkdocs-jupyter: @@ -18,8 +17,8 @@ plugins: csl_file: "./docs/paper/apa.csl" cite_inline: false - coverage: - page_name: coverage # default - html_report_dir: htmlcov # default + page_name: coverage # default + html_report_dir: htmlcov # default markdown_extensions: - footnotes @@ -34,4 +33,4 @@ nav: - API reference: reference.md - Quickstart: ./demo/scripts/quickstart_demo.py - Coverage report: coverage.md - - WSIMOD repository: https://github.com/barneydobson/wsi \ No newline at end of file + - WSIMOD repository: https://github.com/barneydobson/wsi diff --git a/model_file.yaml b/model_file.yaml index 5853bc5..807c054 100644 --- a/model_file.yaml +++ b/model_file.yaml @@ -31,7 +31,6 @@ metadata: spec: inputs: - parameters: - name: WSIMOD_SETTINGS title: Settings file name From 01ea60f6884609db47cbca5ed4b70b4112de0a94 Mon Sep 17 00:00:00 2001 From: Diego Alonso Alvarez Date: Tue, 12 Dec 2023 18:17:54 +0000 Subject: [PATCH 2/5] Include all files when uploading --- .github/workflows/publish.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 98cf18c..8d96101 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -18,7 +18,7 @@ jobs: - uses: actions/upload-artifact@v3 with: - path: dist/wsimod + path: dist/wsimod* publish-TestPyPI: needs: build-wheel From 9949af9da3f8d7da09928d053e3a5214ae6feb08 Mon Sep 17 00:00:00 2001 From: Diego Alonso Alvarez Date: Wed, 13 Dec 2023 04:31:42 +0000 Subject: [PATCH 3/5] Revert "Add publish workflow, install prettier hook and run it" This reverts commit b26fac513a6c257a75ad28a8ec1b8782e7277704. --- .editorconfig | 21 -- .github/workflows/ci.yml | 24 +- .github/workflows/publish.yml | 64 ----- .pre-commit-config.yaml | 8 +- .zenodo.json | 12 +- README.md | 18 +- docker-compose.yaml | 2 +- docs/CODE_OF_CONDUCT.md | 21 +- docs/demo/data/processed/arcs.geojson | 260 ++------------------ docs/demo/data/processed/nodes.geojson | 170 ++----------- docs/demo/data/raw/points_locations.geojson | 172 ++----------- docs/demo/examples/quickstart_demo.yaml | 104 ++++---- docs/index.md | 32 +-- docs/paper/paper.md | 114 ++++----- docs/reference-arc.md | 2 +- docs/reference-core.md | 2 +- docs/reference-other.md | 2 +- docs/stylesheets/extra.css | 6 +- docs/wsimod_models.md | 6 +- mkdocs.yml | 7 +- model_file.yaml | 1 + 21 files changed, 250 insertions(+), 798 deletions(-) delete mode 100644 .editorconfig delete mode 100644 .github/workflows/publish.yml diff --git a/.editorconfig b/.editorconfig deleted file mode 100644 index 88f73db..0000000 --- a/.editorconfig +++ /dev/null @@ -1,21 +0,0 @@ -root = true - -[*] -charset = utf-8 -insert_final_newline = true -trim_trailing_whitespace = true -indent_style = space -indent_size = 4 -max_line_length = 88 - -[*.md] -indent_size = 2 - -[*.yaml] -indent_size = 2 - -[*.yml] -indent_size = 2 - -[Makefile] -indent_style = tab \ No newline at end of file diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 23c6ef2..b7b71cf 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,19 +15,19 @@ jobs: strategy: fail-fast: false matrix: - os: [ubuntu-latest, windows-latest, macos-latest] - python-version: ["3.9", "3.10", "3.11"] + os: [ ubuntu-latest, windows-latest, macos-latest] + python-version: [ "3.9", "3.10", "3.11" ] steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v4 - with: - python-version: ${{ matrix.python-version }} + - uses: actions/checkout@v4 + - uses: actions/setup-python@v4 + with: + python-version: ${{ matrix.python-version }} - - name: Install and build - run: | - python -m pip install -r requirements-dev.txt - python -m pip install . + - name: Install and build + run: | + python -m pip install -r requirements-dev.txt + python -m pip install . - - name: Run tests - run: python -m pytest + - name: Run tests + run: python -m pytest diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml deleted file mode 100644 index 8d96101..0000000 --- a/.github/workflows/publish.yml +++ /dev/null @@ -1,64 +0,0 @@ -on: [release] - -jobs: - test: - uses: ./.github/workflows/ci.yml - - build-wheel: - needs: test - name: Build source distribution - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - name: Build sdist - run: | - python -m pip install --upgrade build - python -m build - - - uses: actions/upload-artifact@v3 - with: - path: dist/wsimod* - - publish-TestPyPI: - needs: build-wheel - name: Publish WSIMOD to TestPyPI - runs-on: ubuntu-latest - permissions: - id-token: write - - steps: - - name: Download sdist artifact - uses: actions/download-artifact@v3 - with: - name: artifact - path: dist - - - name: Display structure of downloaded files - run: ls -R dist - - - name: Publish package distributions to TestPyPI - uses: pypa/gh-action-pypi-publish@release/v1 - with: - repository-url: https://test.pypi.org/legacy/ - skip-existing: true - - publish-PyPI: - needs: publish-TestPyPI - name: Publish WSIMOD to PyPI - runs-on: ubuntu-latest - permissions: - id-token: write - - steps: - - name: Download sdist artifact - uses: actions/download-artifact@v3 - with: - name: artifact - path: dist - - - name: Display structure of downloaded files - run: ls -R dist - - - name: Publish package distributions to PyPI - uses: pypa/gh-action-pypi-publish@release/v1 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 217bf00..be7251e 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -9,7 +9,7 @@ repos: hooks: - id: black - repo: https://github.com/astral-sh/ruff-pre-commit - rev: "v0.1.3" + rev: 'v0.1.3' hooks: - id: ruff args: [--fix, --exit-non-zero-on-fix] @@ -21,8 +21,4 @@ repos: rev: v0.37.0 hooks: - id: markdownlint - args: ["--disable", "MD013", "MD033", "--"] - - repo: https://github.com/pre-commit/mirrors-prettier - rev: v3.1.0 - hooks: - - id: prettier + args: ["--disable", "MD013", "MD033", "--"] \ No newline at end of file diff --git a/.zenodo.json b/.zenodo.json index f7cddeb..79531cb 100644 --- a/.zenodo.json +++ b/.zenodo.json @@ -1,14 +1,14 @@ { - "description": "Release following the JOSS review process", + "description": "Release following the JOSS review process", "license": { "id": "bsd-3-clause", "title": "BSD 3-Clause License", "url": "https://opensource.org/licenses/BSD-3-Clause" - }, - "title": "Water Systems Integrated Modelling framework, WSIMOD: A Python package for integrated modelling of water quality and quantity across the water cycle", - "version": "0.3_joss_reviewed", - "upload_type": "software", - "publication_date": "2023-02-21", + }, + "title": "Water Systems Integrated Modelling framework, WSIMOD: A Python package for integrated modelling of water quality and quantity across the water cycle", + "version": "0.3_joss_reviewed", + "upload_type": "software", + "publication_date": "2023-02-21", "creators": [ { "name": "Dobson, Barnaby", diff --git a/README.md b/README.md index e0233a5..f661eed 100644 --- a/README.md +++ b/README.md @@ -20,9 +20,9 @@ with arcs, and create simulations. You can access our documentation below or at [https://imperialcollegelondon.github.io/wsi](https://imperialcollegelondon.github.io/wsi). -_Requires_: Python 3 (tested on versions >=3.7), [tqdm](https://tqdm.github.io/), [PyYAML](https://pyyaml.org/), [dill](https://dill.readthedocs.io/en/latest/) +*Requires*: Python 3 (tested on versions >=3.7), [tqdm](https://tqdm.github.io/), [PyYAML](https://pyyaml.org/), [dill](https://dill.readthedocs.io/en/latest/) -_Optional requirements to run demos_: [Pandas](https://pandas.pydata.org/), [GeoPandas](https://geopandas.org/en/stable/), [Matplotlib](https://matplotlib.org/), [Shapely](https://shapely.readthedocs.io/en/stable/manual.html) +*Optional requirements to run demos*: [Pandas](https://pandas.pydata.org/), [GeoPandas](https://geopandas.org/en/stable/), [Matplotlib](https://matplotlib.org/), [Shapely](https://shapely.readthedocs.io/en/stable/manual.html) Please consider [contributing](./docs/CONTRIBUTING.md) and note the [code of conduct](./docs/CODE_OF_CONDUCT.md) @@ -84,13 +84,13 @@ pip install -e .[dev,demos] If you would like to use our software, please cite it using the following: -> Dobson, B., Liu, L. and Mijic, A. (2023) -> ‘Water Systems Integrated Modelling framework, WSIMOD: A Python package for integrated modelling of water quality and quantity across the water cycle’, -> Journal of Open Source Software. -> The Open Journal, -> 8(83), -> p. 4996. -> doi: 10.21105/joss.04996. + > Dobson, B., Liu, L. and Mijic, A. (2023) + ‘Water Systems Integrated Modelling framework, WSIMOD: A Python package for integrated modelling of water quality and quantity across the water cycle’, + Journal of Open Source Software. + The Open Journal, + 8(83), + p. 4996. + doi: 10.21105/joss.04996. Find the bibtex citation below: diff --git a/docker-compose.yaml b/docker-compose.yaml index 38e3f7c..b420799 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -1,4 +1,4 @@ -version: "3" +version: '3' services: wsimod: build: . diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md index 8b4fcfd..45d257b 100644 --- a/docs/CODE_OF_CONDUCT.md +++ b/docs/CODE_OF_CONDUCT.md @@ -1,3 +1,4 @@ + # Contributor Covenant Code of Conduct ## Our Pledge @@ -17,23 +18,23 @@ diverse, inclusive, and healthy community. Examples of behavior that contributes to a positive environment for our community include: -- Demonstrating empathy and kindness toward other people -- Being respectful of differing opinions, viewpoints, and experiences -- Giving and gracefully accepting constructive feedback -- Accepting responsibility and apologizing to those affected by our mistakes, +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience -- Focusing on what is best not just for us as individuals, but for the overall +* Focusing on what is best not just for us as individuals, but for the overall community Examples of unacceptable behavior include: -- The use of sexualized language or imagery, and sexual attention or advances of +* The use of sexualized language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Publishing others' private information, such as a physical or email address, +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, without their explicit permission -- Other conduct which could reasonably be considered inappropriate in a +* Other conduct which could reasonably be considered inappropriate in a professional setting ## Enforcement Responsibilities diff --git a/docs/demo/data/processed/arcs.geojson b/docs/demo/data/processed/arcs.geojson index e96bab1..2b3eea3 100644 --- a/docs/demo/data/processed/arcs.geojson +++ b/docs/demo/data/processed/arcs.geojson @@ -1,237 +1,27 @@ { - "type": "FeatureCollection", - "crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:EPSG::27700" } }, - "features": [ - { - "type": "Feature", - "properties": { "name": "evenlode_to_thames" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [444803.245803258207161, 209968.835814726597164], - [445807.062961385643575, 209784.700089471472893] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "thames_to_thames" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [444553.757344728102908, 208671.116935172060039], - [445807.062961385643575, 209784.700089471472893] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "ray_to_cherwell" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [452334.241451664071064, 213734.77082821552176], - [452377.994378837756813, 213619.382871634908952] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "cherwell_to_cherwell" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [448322.315483848331496, 215990.659458106965758], - [452377.994378837756813, 213619.382871634908952] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "thames_to_farmoor" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [445807.062961385643575, 209784.700089471472893], - [447193.271648206980899, 210204.39720278698951] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "farmoor_to_mixer" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [447193.271648206980899, 210204.39720278698951], - [453086.204326246981509, 200795.47163558145985] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "cherwell_to_mixer" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [452377.994378837756813, 213619.382871634908952], - [453086.204326246981509, 200795.47163558145985] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "wwtw_to_mixer" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [454354.048711575742345, 201923.415951047907583], - [453086.204326246981509, 200795.47163558145985] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "sewer_overflow" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [453023.939232126343995, 204102.352711724466644], - [453086.204326246981509, 200795.47163558145985] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "mixer_to_waste" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [453086.204326246981509, 200795.47163558145985], - [453593.342079813068267, 197857.570163376047276] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "abstraction_to_farmoor" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [447193.271648206980899, 210204.39720278698951], - [444554.065823141369037, 205957.430792123777792] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "distribution_to_demand" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [448676.107366815034766, 205941.820039099082351], - [450445.334339758381248, 207120.12633056694176] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "demand_to_sewer" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [450445.334339758381248, 207120.12633056694176], - [453023.939232126343995, 204102.352711724466644] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "land_to_sewer" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [451479.573614976950921, 205754.92228964145761], - [453023.939232126343995, 204102.352711724466644] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "sewer_to_wwtw" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [453023.939232126343995, 204102.352711724466644], - [454354.048711575742345, 201923.415951047907583] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "fwtw_to_sewer" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [445129.387841082643718, 206490.570321662002243], - [453023.939232126343995, 204102.352711724466644] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "fwtw_to_distribution" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [445129.387841082643718, 206490.570321662002243], - [448676.107366815034766, 205941.820039099082351] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "reservoir_to_fwtw" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [444554.065823141369037, 205957.430792123777792], - [445129.387841082643718, 206490.570321662002243] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "land_to_gw" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [451479.573614976950921, 205754.92228964145761], - [451735.32843084493652, 207240.267565301968716] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "garden_to_gw" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [450445.334339758381248, 207120.12633056694176], - [451735.32843084493652, 207240.267565301968716] - ] - } - }, - { - "type": "Feature", - "properties": { "name": "gw_to_mixer" }, - "geometry": { - "type": "LineString", - "coordinates": [ - [451735.32843084493652, 207240.267565301968716], - [453086.204326246981509, 200795.47163558145985] - ] - } - } - ] +"type": "FeatureCollection", +"crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:EPSG::27700" } }, +"features": [ +{ "type": "Feature", "properties": { "name": "evenlode_to_thames" }, "geometry": { "type": "LineString", "coordinates": [ [ 444803.245803258207161, 209968.835814726597164 ], [ 445807.062961385643575, 209784.700089471472893 ] ] } }, +{ "type": "Feature", "properties": { "name": "thames_to_thames" }, "geometry": { "type": "LineString", "coordinates": [ [ 444553.757344728102908, 208671.116935172060039 ], [ 445807.062961385643575, 209784.700089471472893 ] ] } }, +{ "type": "Feature", "properties": { "name": "ray_to_cherwell" }, "geometry": { "type": "LineString", "coordinates": [ [ 452334.241451664071064, 213734.77082821552176 ], [ 452377.994378837756813, 213619.382871634908952 ] ] } }, +{ "type": "Feature", "properties": { "name": "cherwell_to_cherwell" }, "geometry": { "type": "LineString", "coordinates": [ [ 448322.315483848331496, 215990.659458106965758 ], [ 452377.994378837756813, 213619.382871634908952 ] ] } }, +{ "type": "Feature", "properties": { "name": "thames_to_farmoor" }, "geometry": { "type": "LineString", "coordinates": [ [ 445807.062961385643575, 209784.700089471472893 ], [ 447193.271648206980899, 210204.39720278698951 ] ] } }, +{ "type": "Feature", "properties": { "name": "farmoor_to_mixer" }, "geometry": { "type": "LineString", "coordinates": [ [ 447193.271648206980899, 210204.39720278698951 ], [ 453086.204326246981509, 200795.47163558145985 ] ] } }, +{ "type": "Feature", "properties": { "name": "cherwell_to_mixer" }, "geometry": { "type": "LineString", "coordinates": [ [ 452377.994378837756813, 213619.382871634908952 ], [ 453086.204326246981509, 200795.47163558145985 ] ] } }, +{ "type": "Feature", "properties": { "name": "wwtw_to_mixer" }, "geometry": { "type": "LineString", "coordinates": [ [ 454354.048711575742345, 201923.415951047907583 ], [ 453086.204326246981509, 200795.47163558145985 ] ] } }, +{ "type": "Feature", "properties": { "name": "sewer_overflow" }, "geometry": { "type": "LineString", "coordinates": [ [ 453023.939232126343995, 204102.352711724466644 ], [ 453086.204326246981509, 200795.47163558145985 ] ] } }, +{ "type": "Feature", "properties": { "name": "mixer_to_waste" }, "geometry": { "type": "LineString", "coordinates": [ [ 453086.204326246981509, 200795.47163558145985 ], [ 453593.342079813068267, 197857.570163376047276 ] ] } }, +{ "type": "Feature", "properties": { "name": "abstraction_to_farmoor" }, "geometry": { "type": "LineString", "coordinates": [ [ 447193.271648206980899, 210204.39720278698951 ], [ 444554.065823141369037, 205957.430792123777792 ] ] } }, +{ "type": "Feature", "properties": { "name": "distribution_to_demand" }, "geometry": { "type": "LineString", "coordinates": [ [ 448676.107366815034766, 205941.820039099082351 ], [ 450445.334339758381248, 207120.12633056694176 ] ] } }, +{ "type": "Feature", "properties": { "name": "demand_to_sewer" }, "geometry": { "type": "LineString", "coordinates": [ [ 450445.334339758381248, 207120.12633056694176 ], [ 453023.939232126343995, 204102.352711724466644 ] ] } }, +{ "type": "Feature", "properties": { "name": "land_to_sewer" }, "geometry": { "type": "LineString", "coordinates": [ [ 451479.573614976950921, 205754.92228964145761 ], [ 453023.939232126343995, 204102.352711724466644 ] ] } }, +{ "type": "Feature", "properties": { "name": "sewer_to_wwtw" }, "geometry": { "type": "LineString", "coordinates": [ [ 453023.939232126343995, 204102.352711724466644 ], [ 454354.048711575742345, 201923.415951047907583 ] ] } }, +{ "type": "Feature", "properties": { "name": "fwtw_to_sewer" }, "geometry": { "type": "LineString", "coordinates": [ [ 445129.387841082643718, 206490.570321662002243 ], [ 453023.939232126343995, 204102.352711724466644 ] ] } }, +{ "type": "Feature", "properties": { "name": "fwtw_to_distribution" }, "geometry": { "type": "LineString", "coordinates": [ [ 445129.387841082643718, 206490.570321662002243 ], [ 448676.107366815034766, 205941.820039099082351 ] ] } }, +{ "type": "Feature", "properties": { "name": "reservoir_to_fwtw" }, "geometry": { "type": "LineString", "coordinates": [ [ 444554.065823141369037, 205957.430792123777792 ], [ 445129.387841082643718, 206490.570321662002243 ] ] } }, +{ "type": "Feature", "properties": { "name": "land_to_gw" }, "geometry": { "type": "LineString", "coordinates": [ [ 451479.573614976950921, 205754.92228964145761 ], [ 451735.32843084493652, 207240.267565301968716 ] ] } }, +{ "type": "Feature", "properties": { "name": "garden_to_gw" }, "geometry": { "type": "LineString", "coordinates": [ [ 450445.334339758381248, 207120.12633056694176 ], [ 451735.32843084493652, 207240.267565301968716 ] ] } }, +{ "type": "Feature", "properties": { "name": "gw_to_mixer" }, "geometry": { "type": "LineString", "coordinates": [ [ 451735.32843084493652, 207240.267565301968716 ], [ 453086.204326246981509, 200795.47163558145985 ] ] } } +] } diff --git a/docs/demo/data/processed/nodes.geojson b/docs/demo/data/processed/nodes.geojson index eb971b3..47eafc9 100644 --- a/docs/demo/data/processed/nodes.geojson +++ b/docs/demo/data/processed/nodes.geojson @@ -1,150 +1,24 @@ { - "type": "FeatureCollection", - "crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:EPSG::27700" } }, - "features": [ - { - "type": "Feature", - "properties": { "name": "farmoor_abstraction", "type_": "Node" }, - "geometry": { - "type": "Point", - "coordinates": [447193.271648206980899, 210204.39720278698951] - } - }, - { - "type": "Feature", - "properties": { "name": "thames", "type_": "Catchment" }, - "geometry": { - "type": "Point", - "coordinates": [444553.757344728102908, 208671.116935172060039] - } - }, - { - "type": "Feature", - "properties": { "name": "evenlode", "type_": "Catchment" }, - "geometry": { - "type": "Point", - "coordinates": [444803.245803258207161, 209968.835814726597164] - } - }, - { - "type": "Feature", - "properties": { "name": "ray", "type_": "Catchment" }, - "geometry": { - "type": "Point", - "coordinates": [452334.241451664071064, 213734.77082821552176] - } - }, - { - "type": "Feature", - "properties": { "name": "cherwell", "type_": "Catchment" }, - "geometry": { - "type": "Point", - "coordinates": [448322.315483848331496, 215990.659458106965758] - } - }, - { - "type": "Feature", - "properties": { "name": "oxford_fwtw", "type_": "FWTW" }, - "geometry": { - "type": "Point", - "coordinates": [445129.387841082643718, 206490.570321662002243] - } - }, - { - "type": "Feature", - "properties": { "name": "oxford_wwtw", "type_": "WWTW" }, - "geometry": { - "type": "Point", - "coordinates": [454354.048711575742345, 201923.415951047907583] - } - }, - { - "type": "Feature", - "properties": { "name": "thames_mixer", "type_": "Node" }, - "geometry": { - "type": "Point", - "coordinates": [453086.204326246981509, 200795.47163558145985] - } - }, - { - "type": "Feature", - "properties": { "name": "thames_above_abingdon", "type_": "Waste" }, - "geometry": { - "type": "Point", - "coordinates": [453593.342079813068267, 197857.570163376047276] - } - }, - { - "type": "Feature", - "properties": { "name": "oxford", "type_": "Demand" }, - "geometry": { - "type": "Point", - "coordinates": [450445.334339758381248, 207120.12633056694176] - } - }, - { - "type": "Feature", - "properties": { "name": "gw", "type_": "Groundwater" }, - "geometry": { - "type": "Point", - "coordinates": [451735.32843084493652, 207240.267565301968716] - } - }, - { - "type": "Feature", - "properties": { "name": "oxford_land", "type_": "Land" }, - "geometry": { - "type": "Point", - "coordinates": [451479.573614976950921, 205754.92228964145761] - } - }, - { - "type": "Feature", - "properties": { "name": "combined_sewer", "type_": "Sewer" }, - "geometry": { - "type": "Point", - "coordinates": [453023.939232126343995, 204102.352711724466644] - } - }, - { - "type": "Feature", - "properties": { "name": "oxford_distribution", "type_": "Node" }, - "geometry": { - "type": "Point", - "coordinates": [448676.107366815034766, 205941.820039099082351] - } - }, - { - "type": "Feature", - "properties": { "name": "evenlode_thames", "type_": "Node" }, - "geometry": { - "type": "Point", - "coordinates": [445807.062961385643575, 209784.700089471472893] - } - }, - { - "type": "Feature", - "properties": { "name": "cherwell_ray", "type_": "Node" }, - "geometry": { - "type": "Point", - "coordinates": [452377.994378837756813, 213619.382871634908952] - } - }, - { - "type": "Feature", - "properties": { "name": "cherwell_thames", "type_": "Node" }, - "geometry": { - "type": "Point", - "coordinates": [451992.722700056387112, 205054.875454529828858] - } - }, - { - "type": "Feature", - "properties": { "name": "farmoor", "type_": "Reservoir" }, - "geometry": { - "type": "Point", - "coordinates": [444554.065823141369037, 205957.430792123777792] - } - } - ] +"type": "FeatureCollection", +"crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:EPSG::27700" } }, +"features": [ +{ "type": "Feature", "properties": { "name": "farmoor_abstraction", "type_": "Node" }, "geometry": { "type": "Point", "coordinates": [ 447193.271648206980899, 210204.39720278698951 ] } }, +{ "type": "Feature", "properties": { "name": "thames", "type_": "Catchment" }, "geometry": { "type": "Point", "coordinates": [ 444553.757344728102908, 208671.116935172060039 ] } }, +{ "type": "Feature", "properties": { "name": "evenlode", "type_": "Catchment" }, "geometry": { "type": "Point", "coordinates": [ 444803.245803258207161, 209968.835814726597164 ] } }, +{ "type": "Feature", "properties": { "name": "ray", "type_": "Catchment" }, "geometry": { "type": "Point", "coordinates": [ 452334.241451664071064, 213734.77082821552176 ] } }, +{ "type": "Feature", "properties": { "name": "cherwell", "type_": "Catchment" }, "geometry": { "type": "Point", "coordinates": [ 448322.315483848331496, 215990.659458106965758 ] } }, +{ "type": "Feature", "properties": { "name": "oxford_fwtw", "type_": "FWTW" }, "geometry": { "type": "Point", "coordinates": [ 445129.387841082643718, 206490.570321662002243 ] } }, +{ "type": "Feature", "properties": { "name": "oxford_wwtw", "type_": "WWTW" }, "geometry": { "type": "Point", "coordinates": [ 454354.048711575742345, 201923.415951047907583 ] } }, +{ "type": "Feature", "properties": { "name": "thames_mixer", "type_": "Node" }, "geometry": { "type": "Point", "coordinates": [ 453086.204326246981509, 200795.47163558145985 ] } }, +{ "type": "Feature", "properties": { "name": "thames_above_abingdon", "type_": "Waste" }, "geometry": { "type": "Point", "coordinates": [ 453593.342079813068267, 197857.570163376047276 ] } }, +{ "type": "Feature", "properties": { "name": "oxford", "type_": "Demand" }, "geometry": { "type": "Point", "coordinates": [ 450445.334339758381248, 207120.12633056694176 ] } }, +{ "type": "Feature", "properties": { "name": "gw", "type_": "Groundwater" }, "geometry": { "type": "Point", "coordinates": [ 451735.32843084493652, 207240.267565301968716 ] } }, +{ "type": "Feature", "properties": { "name": "oxford_land", "type_": "Land" }, "geometry": { "type": "Point", "coordinates": [ 451479.573614976950921, 205754.92228964145761 ] } }, +{ "type": "Feature", "properties": { "name": "combined_sewer", "type_": "Sewer" }, "geometry": { "type": "Point", "coordinates": [ 453023.939232126343995, 204102.352711724466644 ] } }, +{ "type": "Feature", "properties": { "name": "oxford_distribution", "type_": "Node" }, "geometry": { "type": "Point", "coordinates": [ 448676.107366815034766, 205941.820039099082351 ] } }, +{ "type": "Feature", "properties": { "name": "evenlode_thames", "type_": "Node" }, "geometry": { "type": "Point", "coordinates": [ 445807.062961385643575, 209784.700089471472893 ] } }, +{ "type": "Feature", "properties": { "name": "cherwell_ray", "type_": "Node" }, "geometry": { "type": "Point", "coordinates": [ 452377.994378837756813, 213619.382871634908952 ] } }, +{ "type": "Feature", "properties": { "name": "cherwell_thames", "type_": "Node" }, "geometry": { "type": "Point", "coordinates": [ 451992.722700056387112, 205054.875454529828858 ] } }, +{ "type": "Feature", "properties": { "name": "farmoor", "type_": "Reservoir" }, "geometry": { "type": "Point", "coordinates": [ 444554.065823141369037, 205957.430792123777792 ] } } +] } diff --git a/docs/demo/data/raw/points_locations.geojson b/docs/demo/data/raw/points_locations.geojson index 9ef2370..3a11bcc 100644 --- a/docs/demo/data/raw/points_locations.geojson +++ b/docs/demo/data/raw/points_locations.geojson @@ -1,151 +1,25 @@ { - "type": "FeatureCollection", - "name": "points_locations", - "crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:EPSG::27700" } }, - "features": [ - { - "type": "Feature", - "properties": { "name": "farmoor_abstraction" }, - "geometry": { - "type": "Point", - "coordinates": [447193.271648206980899, 210204.39720278698951] - } - }, - { - "type": "Feature", - "properties": { "name": "thames" }, - "geometry": { - "type": "Point", - "coordinates": [444553.757344728102908, 208671.116935172060039] - } - }, - { - "type": "Feature", - "properties": { "name": "evenlode" }, - "geometry": { - "type": "Point", - "coordinates": [444803.245803258207161, 209968.835814726597164] - } - }, - { - "type": "Feature", - "properties": { "name": "ray" }, - "geometry": { - "type": "Point", - "coordinates": [452334.241451664071064, 213734.77082821552176] - } - }, - { - "type": "Feature", - "properties": { "name": "cherwell" }, - "geometry": { - "type": "Point", - "coordinates": [448322.315483848331496, 215990.659458106965758] - } - }, - { - "type": "Feature", - "properties": { "name": "oxford_fwtw" }, - "geometry": { - "type": "Point", - "coordinates": [445129.387841082643718, 206490.570321662002243] - } - }, - { - "type": "Feature", - "properties": { "name": "oxford_wwtw" }, - "geometry": { - "type": "Point", - "coordinates": [454354.048711575742345, 201923.415951047907583] - } - }, - { - "type": "Feature", - "properties": { "name": "thames_mixer" }, - "geometry": { - "type": "Point", - "coordinates": [453086.204326246981509, 200795.47163558145985] - } - }, - { - "type": "Feature", - "properties": { "name": "thames_above_abingdon" }, - "geometry": { - "type": "Point", - "coordinates": [453593.342079813068267, 197857.570163376047276] - } - }, - { - "type": "Feature", - "properties": { "name": "oxford" }, - "geometry": { - "type": "Point", - "coordinates": [450445.334339758381248, 207120.12633056694176] - } - }, - { - "type": "Feature", - "properties": { "name": "gw" }, - "geometry": { - "type": "Point", - "coordinates": [451735.32843084493652, 207240.267565301968716] - } - }, - { - "type": "Feature", - "properties": { "name": "oxford_land" }, - "geometry": { - "type": "Point", - "coordinates": [451479.573614976950921, 205754.92228964145761] - } - }, - { - "type": "Feature", - "properties": { "name": "combined_sewer" }, - "geometry": { - "type": "Point", - "coordinates": [453023.939232126343995, 204102.352711724466644] - } - }, - { - "type": "Feature", - "properties": { "name": "oxford_distribution" }, - "geometry": { - "type": "Point", - "coordinates": [448676.107366815034766, 205941.820039099082351] - } - }, - { - "type": "Feature", - "properties": { "name": "evenlode_thames" }, - "geometry": { - "type": "Point", - "coordinates": [445807.062961385643575, 209784.700089471472893] - } - }, - { - "type": "Feature", - "properties": { "name": "cherwell_ray" }, - "geometry": { - "type": "Point", - "coordinates": [452377.994378837756813, 213619.382871634908952] - } - }, - { - "type": "Feature", - "properties": { "name": "cherwell_thames" }, - "geometry": { - "type": "Point", - "coordinates": [451992.722700056387112, 205054.875454529828858] - } - }, - { - "type": "Feature", - "properties": { "name": "farmoor" }, - "geometry": { - "type": "Point", - "coordinates": [444554.065823141369037, 205957.430792123777792] - } - } - ] +"type": "FeatureCollection", +"name": "points_locations", +"crs": { "type": "name", "properties": { "name": "urn:ogc:def:crs:EPSG::27700" } }, +"features": [ +{ "type": "Feature", "properties": { "name": "farmoor_abstraction" }, "geometry": { "type": "Point", "coordinates": [ 447193.271648206980899, 210204.39720278698951 ] } }, +{ "type": "Feature", "properties": { "name": "thames" }, "geometry": { "type": "Point", "coordinates": [ 444553.757344728102908, 208671.116935172060039 ] } }, +{ "type": "Feature", "properties": { "name": "evenlode" }, "geometry": { "type": "Point", "coordinates": [ 444803.245803258207161, 209968.835814726597164 ] } }, +{ "type": "Feature", "properties": { "name": "ray" }, "geometry": { "type": "Point", "coordinates": [ 452334.241451664071064, 213734.77082821552176 ] } }, +{ "type": "Feature", "properties": { "name": "cherwell" }, "geometry": { "type": "Point", "coordinates": [ 448322.315483848331496, 215990.659458106965758 ] } }, +{ "type": "Feature", "properties": { "name": "oxford_fwtw" }, "geometry": { "type": "Point", "coordinates": [ 445129.387841082643718, 206490.570321662002243 ] } }, +{ "type": "Feature", "properties": { "name": "oxford_wwtw" }, "geometry": { "type": "Point", "coordinates": [ 454354.048711575742345, 201923.415951047907583 ] } }, +{ "type": "Feature", "properties": { "name": "thames_mixer" }, "geometry": { "type": "Point", "coordinates": [ 453086.204326246981509, 200795.47163558145985 ] } }, +{ "type": "Feature", "properties": { "name": "thames_above_abingdon" }, "geometry": { "type": "Point", "coordinates": [ 453593.342079813068267, 197857.570163376047276 ] } }, +{ "type": "Feature", "properties": { "name": "oxford" }, "geometry": { "type": "Point", "coordinates": [ 450445.334339758381248, 207120.12633056694176 ] } }, +{ "type": "Feature", "properties": { "name": "gw" }, "geometry": { "type": "Point", "coordinates": [ 451735.32843084493652, 207240.267565301968716 ] } }, +{ "type": "Feature", "properties": { "name": "oxford_land" }, "geometry": { "type": "Point", "coordinates": [ 451479.573614976950921, 205754.92228964145761 ] } }, +{ "type": "Feature", "properties": { "name": "combined_sewer" }, "geometry": { "type": "Point", "coordinates": [ 453023.939232126343995, 204102.352711724466644 ] } }, +{ "type": "Feature", "properties": { "name": "oxford_distribution" }, "geometry": { "type": "Point", "coordinates": [ 448676.107366815034766, 205941.820039099082351 ] } }, +{ "type": "Feature", "properties": { "name": "evenlode_thames" }, "geometry": { "type": "Point", "coordinates": [ 445807.062961385643575, 209784.700089471472893 ] } }, +{ "type": "Feature", "properties": { "name": "cherwell_ray" }, "geometry": { "type": "Point", "coordinates": [ 452377.994378837756813, 213619.382871634908952 ] } }, +{ "type": "Feature", "properties": { "name": "cherwell_thames" }, "geometry": { "type": "Point", "coordinates": [ 451992.722700056387112, 205054.875454529828858 ] } }, +{ "type": "Feature", "properties": { "name": "farmoor" }, "geometry": { "type": "Point", "coordinates": [ 444554.065823141369037, 205957.430792123777792 ] } } +] } diff --git a/docs/demo/examples/quickstart_demo.yaml b/docs/demo/examples/quickstart_demo.yaml index 123d255..167dfc9 100644 --- a/docs/demo/examples/quickstart_demo.yaml +++ b/docs/demo/examples/quickstart_demo.yaml @@ -13,8 +13,8 @@ data: variable: value factor: "MM_TO_M" format: dict - index: ["variable", "date"] - output: "value" + index: ['variable', 'date'] + output: 'value' options: parse_dates=['date'] dates_data: @@ -24,64 +24,64 @@ data: dates: data:dates_data nodes: - - type_: Sewer - name: my_sewer - capacity: 0.04 +- 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 +- 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_: Node + name: my_river - - type_: Waste - name: my_outlet +- type_: Waste + name: my_outlet arcs: - - type_: Arc - name: urban_drainage - in_port: my_land - out_port: my_sewer +- 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: percolation + in_port: my_land + out_port: my_groundwater - - type_: Arc - name: runoff - in_port: my_land - out_port: my_river +- 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: 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: baseflow + in_port: my_groundwater + out_port: my_river - - type_: Arc - name: catchment_outflow - in_port: my_river - out_port: my_outlet +- type_: Arc + name: catchment_outflow + in_port: my_river + out_port: my_outlet diff --git a/docs/index.md b/docs/index.md index 50a17d8..9c352ae 100644 --- a/docs/index.md +++ b/docs/index.md @@ -32,43 +32,43 @@ and consists of: 3. [Tutorials](tutorials.md) - 3.1. [Quickstart](./demo/scripts/quickstart_demo.py) + 3.1. [Quickstart](./demo/scripts/quickstart_demo.py) - 3.2. [WSIMOD model demonstration - Oxford](./demo/scripts/oxford_demo.py) + 3.2. [WSIMOD model demonstration - Oxford](./demo/scripts/oxford_demo.py) - 3.3. [Land nodes - hydrology and agriculture](./demo/scripts/land_demo.py) + 3.3. [Land nodes - hydrology and agriculture](./demo/scripts/land_demo.py) - 3.4. [Model object - WSIMOD models](wsimod_models.md) + 3.4. [Model object - WSIMOD models](wsimod_models.md) 4. [How-To Guides](how-to.md) - 4.1. [Customise a node](./demo/scripts/customise_a_node.py) + 4.1. [Customise a node](./demo/scripts/customise_a_node.py) - 4.2. [Customise an arc](./demo/scripts/customise_an_arc.py) + 4.2. [Customise an arc](./demo/scripts/customise_an_arc.py) - 4.3. [Customise interactions](./demo/scripts/customise_interactions.py) + 4.3. [Customise interactions](./demo/scripts/customise_interactions.py) 5. [Component library](component-library.md) 6. [API reference](reference.md) - 6.1. [API reference - arc](reference-arc.md) + 6.1. [API reference - arc](reference-arc.md) - 6.2. [API reference - core](reference-core.md) + 6.2. [API reference - core](reference-core.md) - 6.3. [API reference - land](reference-land.md) + 6.3. [API reference - land](reference-land.md) - 6.4. [API reference - nodes](reference-nodes.md) + 6.4. [API reference - nodes](reference-nodes.md) - 6.5. [API reference - sewer](reference-sewer.md) + 6.5. [API reference - sewer](reference-sewer.md) - 6.6. [API reference - storage (reservoir, river, groundwater)](reference-storage.md) + 6.6. [API reference - storage (reservoir, river, groundwater)](reference-storage.md) - 6.7. [API reference - wtw](reference-wtw.md) + 6.7. [API reference - wtw](reference-wtw.md) - 6.8. [API reference - other components](reference-other.md) + 6.8. [API reference - other components](reference-other.md) - 6.9. [API reference - model](reference-model.md) + 6.9. [API reference - model](reference-model.md) 7. [Coverage](coverage.md) diff --git a/docs/paper/paper.md b/docs/paper/paper.md index f51dcfc..0c3d14b 100644 --- a/docs/paper/paper.md +++ b/docs/paper/paper.md @@ -1,5 +1,5 @@ --- -title: "Water Systems Integrated Modelling framework, WSIMOD: A Python package for integrated modelling of water quality and quantity across the water cycle" +title: 'Water Systems Integrated Modelling framework, WSIMOD: A Python package for integrated modelling of water quality and quantity across the water cycle' tags: - Python - water quality @@ -17,93 +17,93 @@ authors: orcid: 0000-0001-7096-9405 affiliation: 1 affiliations: - - name: Department of Civil and Environmental Engineering, Imperial College London, UK - index: 1 + - name: Department of Civil and Environmental Engineering, Imperial College London, UK + index: 1 date: 04 November 2022 bibliography: paper.bib + --- # Summary -The water cycle is highly interconnected; water fluxes in one part depend on -physical and human processes throughout. For example, rivers are a water -supply, a receiver of wastewater, and an aggregate of many hydrological, +The water cycle is highly interconnected; water fluxes in one part depend on +physical and human processes throughout. For example, rivers are a water +supply, a receiver of wastewater, and an aggregate of many hydrological, biological, and chemical processes. Thus, simulations of the water cycle that -have highly constrained boundaries may miss key interactions that create -unanticipated impacts or unexpected opportunities [@Dobson:2020;@Liu:2022]. -Integrated environmental models aim to resolve the issue of boundary -conditions, however they have some key limitations [@Rauch:2017], and in -particular we find a significant need for a parsimonious, self-contained suite -that is accessible and easy to setup. +have highly constrained boundaries may miss key interactions that create +unanticipated impacts or unexpected opportunities [@Dobson:2020;@Liu:2022]. +Integrated environmental models aim to resolve the issue of boundary +conditions, however they have some key limitations [@Rauch:2017], and in +particular we find a significant need for a parsimonious, self-contained suite +that is accessible and easy to setup. # Statement of need -Traditional approaches to water system modelling broadly fall into highly -numerical models that excel in representing individual subsystems, or systems -dynamics models that create broad representations but that lack a physical -basis. Early attempts at a physical representation of the water cycle combined -existing numerical models through an integration framework [@Rauch:2017]. While -successful, this approach has an incredibly high user burden because each -subsystem model is so detailed, and as a consequence is also difficult to -customise. To illustrate, SWAT is one of the most widespread models of the -rural water cycle [@Arnold:2012], while SWMM is the same but for the urban -water cycle [@Gironas:2010]. It has been demonstrated that these two software -can interface using the OpenMI integration framework [@Shrestha:2013]. Despite -this seemingly powerful combination of two near-ubiquitous models, integrated -applications have been limited, and we propose that this is for the same -reasons presented in [@Rauch:2017]: user burden and customisation difficulty. +Traditional approaches to water system modelling broadly fall into highly +numerical models that excel in representing individual subsystems, or systems +dynamics models that create broad representations but that lack a physical +basis. Early attempts at a physical representation of the water cycle combined +existing numerical models through an integration framework [@Rauch:2017]. While +successful, this approach has an incredibly high user burden because each +subsystem model is so detailed, and as a consequence is also difficult to +customise. To illustrate, SWAT is one of the most widespread models of the +rural water cycle [@Arnold:2012], while SWMM is the same but for the urban +water cycle [@Gironas:2010]. It has been demonstrated that these two software +can interface using the OpenMI integration framework [@Shrestha:2013]. Despite +this seemingly powerful combination of two near-ubiquitous models, integrated +applications have been limited, and we propose that this is for the same +reasons presented in [@Rauch:2017]: user burden and customisation difficulty. -Because of this need, we provide a parsimonious and self-contained suite for integrated water cycle modelling in the WSIMOD Python package. It -brings together a range of software developed over the course of three years -on the [CAMELLIA project](https://www.camelliawater.org/). Urban water -processes are based on those presented and validated in the CityWat +Because of this need, we provide a parsimonious and self-contained suite for integrated water cycle modelling in the WSIMOD Python package. It +brings together a range of software developed over the course of three years +on the [CAMELLIA project](https://www.camelliawater.org/). Urban water +processes are based on those presented and validated in the CityWat model [@Dobson:2020;@Dobson:2021;@Dobson:2022;@Muhandes:2022], while -hydrological and agricultural processes are from the CatchWat +hydrological and agricultural processes are from the CatchWat model [@Liu:2022;@Liu:2022b]. WSIMOD also provides an interface for message -passing between different model components, enabling all parts of the water +passing between different model components, enabling all parts of the water cycle to interact with all other parts. The result is a simulation model that is easy to set up, highly flexible and ideal for representing water quality and -quantity in 'non-textbook' water systems (which in our experience is nearly -all of them). +quantity in 'non-textbook' water systems (which in our experience is nearly +all of them). -The package provides a variety of tutorials and examples to help modellers -create nodes (i.e., representations of subsystems within the water cycle), -connect them together with arcs (i.e., representing the fluxes between -subsystems), and orchestrate them into a model that creates simulations. +The package provides a variety of tutorials and examples to help modellers +create nodes (i.e., representations of subsystems within the water cycle), +connect them together with arcs (i.e., representing the fluxes between +subsystems), and orchestrate them into a model that creates simulations. ## Limitations - -We highlight that WSIMOD is not intended to be a substitute for sophisticated -physical models, nor for a system dynamics approach. In applications where -detailed hydraulic/hydrological process representations are needed (e.g., +We highlight that WSIMOD is not intended to be a substitute for sophisticated +physical models, nor for a system dynamics approach. In applications where +detailed hydraulic/hydrological process representations are needed (e.g., informing the design of specific pipes, cases where processes are hard to -quantify such as representing social drivers of population growth, etc.) there -are likely better tools available. Our case studies highlight -that WSIMOD is most useful in situations where physically representing -cross-sytem processes and thus capturing the impacts of cross-system -interactions are essential towards the questions you ask of your model. -Secondary benefits are that the parsimonious representations utilised are -computationally fast and flexible in capturing a wide range of system +quantify such as representing social drivers of population growth, etc.) there +are likely better tools available. Our case studies highlight +that WSIMOD is most useful in situations where physically representing +cross-sytem processes and thus capturing the impacts of cross-system +interactions are essential towards the questions you ask of your model. +Secondary benefits are that the parsimonious representations utilised are +computationally fast and flexible in capturing a wide range of system interventions. # Acknowledgements -WSIMOD was developed by [Barnaby Dobson](https://github.com/barneydobson) and [Leyang Liu](https://github.com/liuly12). +WSIMOD was developed by [Barnaby Dobson](https://github.com/barneydobson) and [Leyang Liu](https://github.com/liuly12). Theoretical support was provided by Ana Mijic. -Testing the WSIMOD over a variety of applications has been performed by +Testing the WSIMOD over a variety of applications has been performed by Fangjun Peng, Vladimir Krivstov and Samer Muhandes. -Software development support was provided by Imperial College's Research +Software development support was provided by Imperial College's Research Software Engineering service, in particular from Diego Alonso and Dan Davies. We are incredibly grateful for the detailed software reviews provided by [Taher Chegini](https://github.com/cheginit) and [Joshua Larsen](https://github.com/jlarsen-usgs) and editing by [Chris Vernon](https://github.com/crvernon). Their suggestions have significantly improved WSIMOD. -The design of WSIMOD was significantly influenced by -[CityDrain3](https://github.com/gregorburger/CityDrain3) [@Burger:2016], -[OpenMI](https://www.ogc.org/standards/openmi) [@Gregersen:2007], [smif](https://github.com/tomalrussell/smif) [@smif_paper;@smif_software], and the +The design of WSIMOD was significantly influenced by +[CityDrain3](https://github.com/gregorburger/CityDrain3) [@Burger:2016], +[OpenMI](https://www.ogc.org/standards/openmi) [@Gregersen:2007], [smif](https://github.com/tomalrussell/smif) [@smif_paper;@smif_software], and the following review [@Belete:2017]. -We acknowledge funding from the CAMELLIA project (Community Water Management -for a Liveable London), funded by the Natural Environment Research Council +We acknowledge funding from the CAMELLIA project (Community Water Management +for a Liveable London), funded by the Natural Environment Research Council (NERC) under grant NE/S003495/1. # References diff --git a/docs/reference-arc.md b/docs/reference-arc.md index 80a4bdc..7a6ebf0 100644 --- a/docs/reference-arc.md +++ b/docs/reference-arc.md @@ -1,5 +1,5 @@ # API Reference - Arcs -This section of the documentation provides a reference for the API of the arcs.arcs module. +This section of the documentation provides a reference for the API of the arcs.arcs module. ::: wsimod.arcs.arcs diff --git a/docs/reference-core.md b/docs/reference-core.md index 0eeb97a..120868a 100644 --- a/docs/reference-core.md +++ b/docs/reference-core.md @@ -1,6 +1,6 @@ # API Reference - Core -This section of the documentation provides a reference for the API of the core.core and core.constants modules. +This section of the documentation provides a reference for the API of the core.core and core.constants modules. ::: wsimod.core.core ::: wsimod.core.constants diff --git a/docs/reference-other.md b/docs/reference-other.md index 47dd9a0..f74e639 100644 --- a/docs/reference-other.md +++ b/docs/reference-other.md @@ -1,6 +1,6 @@ # API Reference - Other Components -This section of the documentation provides a reference for the API of the nodes.catchment, nodes.demand, nodes.distribution, and nodes.waste modules. +This section of the documentation provides a reference for the API of the nodes.catchment, nodes.demand, nodes.distribution, and nodes.waste modules. ::: wsimod.nodes.catchment ::: wsimod.nodes.demand diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 310282a..2b6d2e0 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -1,14 +1,14 @@ /* Indentation. */ div.doc-contents:not(.first) { padding-left: 25px; - border-left: 0.05rem solid var(--md-typeset-table-color); + border-left: .05rem solid var(--md-typeset-table-color); } /* Mark external links as such. */ a.autorefs-external::after { /* https://primer.style/octicons/arrow-up-right-24 */ background-image: url('data:image/svg+xml,'); - content: " "; + content: ' '; display: inline-block; position: relative; @@ -24,4 +24,4 @@ a.autorefs-external::after { a.autorefs-external:hover::after { background-color: var(--md-accent-fg-color); -} +} \ No newline at end of file diff --git a/docs/wsimod_models.md b/docs/wsimod_models.md index 711e970..7b97577 100644 --- a/docs/wsimod_models.md +++ b/docs/wsimod_models.md @@ -3,9 +3,9 @@ 1. [Introduction](#introduction) 2. [What data do you need](#what-data-do-you-need) 3. [WSIMOD model](#wsimod-model) - 3.1. [Nodes](#nodes) - 3.2. [Arcs](#arcs) - 3.3. [Model properties](#model-properties) + 3.1. [Nodes](#nodes) + 3.2. [Arcs](#arcs) + 3.3. [Model properties](#model-properties) 4. [Input data](#input-data) 5. [Limitations](#limitations) diff --git a/mkdocs.yml b/mkdocs.yml index 106e218..e69c37a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,6 +6,7 @@ theme: extra_css: - stylesheets/extra.css + plugins: - mkdocstrings - mkdocs-jupyter: @@ -17,8 +18,8 @@ plugins: csl_file: "./docs/paper/apa.csl" cite_inline: false - coverage: - page_name: coverage # default - html_report_dir: htmlcov # default + page_name: coverage # default + html_report_dir: htmlcov # default markdown_extensions: - footnotes @@ -33,4 +34,4 @@ nav: - API reference: reference.md - Quickstart: ./demo/scripts/quickstart_demo.py - Coverage report: coverage.md - - WSIMOD repository: https://github.com/barneydobson/wsi + - WSIMOD repository: https://github.com/barneydobson/wsi \ No newline at end of file diff --git a/model_file.yaml b/model_file.yaml index 807c054..5853bc5 100644 --- a/model_file.yaml +++ b/model_file.yaml @@ -31,6 +31,7 @@ metadata: spec: inputs: + parameters: - name: WSIMOD_SETTINGS title: Settings file name From 93420b5024172065ff78e4c23a9165121b8ab19f Mon Sep 17 00:00:00 2001 From: Diego Alonso Alvarez Date: Wed, 13 Dec 2023 04:34:21 +0000 Subject: [PATCH 4/5] Add publish workflow --- .github/workflows/publish.yml | 64 +++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 .github/workflows/publish.yml diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..8d96101 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,64 @@ +on: [release] + +jobs: + test: + uses: ./.github/workflows/ci.yml + + build-wheel: + needs: test + name: Build source distribution + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Build sdist + run: | + python -m pip install --upgrade build + python -m build + + - uses: actions/upload-artifact@v3 + with: + path: dist/wsimod* + + publish-TestPyPI: + needs: build-wheel + name: Publish WSIMOD to TestPyPI + runs-on: ubuntu-latest + permissions: + id-token: write + + steps: + - name: Download sdist artifact + uses: actions/download-artifact@v3 + with: + name: artifact + path: dist + + - name: Display structure of downloaded files + run: ls -R dist + + - name: Publish package distributions to TestPyPI + uses: pypa/gh-action-pypi-publish@release/v1 + with: + repository-url: https://test.pypi.org/legacy/ + skip-existing: true + + publish-PyPI: + needs: publish-TestPyPI + name: Publish WSIMOD to PyPI + runs-on: ubuntu-latest + permissions: + id-token: write + + steps: + - name: Download sdist artifact + uses: actions/download-artifact@v3 + with: + name: artifact + path: dist + + - name: Display structure of downloaded files + run: ls -R dist + + - name: Publish package distributions to PyPI + uses: pypa/gh-action-pypi-publish@release/v1 From 6231ab91c8244dac8b867f84a2ab45a896525b15 Mon Sep 17 00:00:00 2001 From: Diego Alonso Alvarez Date: Wed, 13 Dec 2023 04:41:31 +0000 Subject: [PATCH 5/5] Upload wheel as release artifact --- .github/workflows/publish.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 8d96101..b5eb761 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -20,6 +20,10 @@ jobs: with: path: dist/wsimod* + - uses: softprops/action-gh-release@v1 + with: + files: dist/wsimod* + publish-TestPyPI: needs: build-wheel name: Publish WSIMOD to TestPyPI