diff --git a/.github/workflows/check-links.yml b/.github/workflows/check-links.yml index 4bfc95de..bbb7474a 100644 --- a/.github/workflows/check-links.yml +++ b/.github/workflows/check-links.yml @@ -13,3 +13,4 @@ jobs: with: use-quiet-mode: 'yes' use-verbose-mode: 'yes' + config-file: .markdown-link-check.json diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 10ff5f40..79ab2af7 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -8,6 +8,24 @@ permissions: id-token: write jobs: + test-docs: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: "3.11" + + - name: Install dependencies + run: | + pip install .[doc] + python -c "import pypandoc; pypandoc.download_pandoc()" + + - name: Test Docs + run: mkdocs build + test: uses: ./.github/workflows/ci_template.yml secrets: @@ -73,9 +91,29 @@ jobs: - name: Publish package distributions to PyPI uses: pypa/gh-action-pypi-publish@release/v1 + paper: + runs-on: ubuntu-latest + needs: publish-PyPI + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Build draft PDF + uses: openjournals/openjournals-draft-action@master + with: + journal: joss + # This should be the path to the paper within your repo. + paper-path: docs/paper/paper.md + - name: Upload + uses: actions/upload-artifact@v4 + with: + name: paper + # This is the output path where Pandoc will write the compiled + # PDF. Note, this should be the same directory as the input + # paper.md + path: docs/paper/paper.pdf publish-docs: - needs: publish-PyPI + needs: paper runs-on: ubuntu-latest steps: @@ -86,7 +124,9 @@ jobs: python-version: "3.11" - name: Install dependencies - run: pip install .[doc] + run: | + pip install .[doc] + python -c "import pypandoc; pypandoc.download_pandoc()" - name: Deploy Docs run: mkdocs gh-deploy --force diff --git a/.markdown-link-check.json b/.markdown-link-check.json new file mode 100644 index 00000000..c0991d9c --- /dev/null +++ b/.markdown-link-check.json @@ -0,0 +1,7 @@ +{ + "ignorePatterns": [ + { + "pattern": ".*/paper.pdf" + } + ] +} diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index a16efb62..25cc5175 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -5,7 +5,7 @@ repos: - id: check-merge-conflict - id: debug-statements - repo: https://github.com/astral-sh/ruff-pre-commit - rev: "v0.7.2" + rev: "v0.7.4" hooks: - id: ruff args: [--fix, --exit-non-zero-on-fix] @@ -20,7 +20,7 @@ repos: rev: v0.42.0 hooks: - id: markdownlint - args: ["--disable", "MD013", "--"] + args: ["--disable", "MD013", "--disable", "MD025", "--"] - repo: https://github.com/codespell-project/codespell rev: v2.3.0 diff --git a/README.md b/README.md index f4290ff6..0864d2ca 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@ [![Test and build](https://github.com/ImperialCollegeLondon/SWMManywhere/actions/workflows/ci.yml/badge.svg)](https://github.com/ImperialCollegeLondon/SWMManywhere/actions/workflows/ci.yml) [![DOI](https://zenodo.org/badge/741903266.svg)](https://zenodo.org/doi/10.5281/zenodo.13837741) [![codecov](https://codecov.io/gh/ImperialCollegeLondon/SWMManywhere/graph/badge.svg)](https://codecov.io/gh/ImperialCollegeLondon/SWMManywhere) +[![status](https://joss.theoj.org/papers/b9901c3b612b995bf6977377b65f368a/status.svg)](https://joss.theoj.org/papers/b9901c3b612b995bf6977377b65f368a) + SWMManywhere is a tool to synthesise urban drainage network models (UDMs) using diff --git a/docs/index.md b/docs/index.md index 1dae00ec..a65059ff 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,6 +6,7 @@ derive a synthetic urban drainage network anywhere in the world. ## Table of contents - [Home](index.md) +- [About](./paper/paper.pdf) - [Quickstart](quickstart.md) - Guides: - [Configuration file](config_guide.md) @@ -24,4 +25,5 @@ derive a synthetic urban drainage network anywhere in the world. - [Post processing](reference-post-processing.md) - [Preprocessing](reference-preprocessing.md) - [Config](reference-defs.md) - \ No newline at end of file +- [Coverage report](https://app.codecov.io/gh/ImperialCollegeLondon/SWMManywhere) + \ No newline at end of file diff --git a/docs/paper/apa.csl b/docs/paper/apa.csl new file mode 100644 index 00000000..2c50d03d --- /dev/null +++ b/docs/paper/apa.csl @@ -0,0 +1,1586 @@ + + diff --git a/docs/paper/extended_demo.png b/docs/paper/extended_demo.png new file mode 100644 index 00000000..3530973a Binary files /dev/null and b/docs/paper/extended_demo.png differ diff --git a/docs/paper/paper.bib b/docs/paper/paper.bib new file mode 100644 index 00000000..98109606 --- /dev/null +++ b/docs/paper/paper.bib @@ -0,0 +1,345 @@ +@ARTICLE{Blumensaat2012-hd, + title = "Sewer model development under minimum data requirements", + author = "Blumensaat, Frank and Wolfram, Martin and Krebs, Peter", + journal = "Environ. Earth Sci.", + publisher = "Springer Science and Business Media LLC", + volume = 65, + number = 5, + pages = "1427--1437", + month = mar, + year = 2012, + language = "en", + doi = "10.1007/s12665-011-1146-1" +} + +@ARTICLE{Chahinian2019-lg, + title = "Automatic mapping of urban wastewater networks based on manhole + cover locations", + author = "Chahinian, Nan{\'e}e and Delenne, Carole and Commandr{\'e}, + Benjamin and Derras, Mustapha and Deruelle, Laurent and Bailly, + Jean-St{\'e}phane", + journal = "Comput. Environ. Urban Syst.", + publisher = "Elsevier BV", + volume = 78, + number = 101370, + pages = "101370", + month = nov, + year = 2019, + language = "en", + doi = "10.1016/j.compenvurbsys.2019.101370", +} + +% The entry below contains non-ASCII chars that could not be converted +% to a LaTeX equivalent. +@ARTICLE{Dobson2022-wq, + title = "A reduced complexity model with graph partitioning for rapid + hydraulic assessment of sewer networks", + author = "Dobson, Barnaby and Watson-Hill, Hannah and Muhandes, Samer and + Borup, Morten and Mijic, Ana", + abstract = "AbstractExisting, high‐fidelity models for sewer network + modeling are accurate but too slow and inflexible for modern + applications such as optimization or scenario analysis. Reduced + complexity surrogate modeling has been applied in response to + this, however, current approaches are expensive to set up and + still require high‐fidelity simulations to derive parameters. In + this study, we compare and develop graph partitioning algorithms + to automatically group sections of sewer networks into + semi‐distributed compartments. These compartments can then be + simulated using sewer network information only in the integrated + modeling framework, CityWat‐SemiDistributed (CWSD), which has + been developed for application to sewer network modeling in this + study. We find that combining graph partitioning with CWSD can + produce accurate simulations 100--1,000$\times$ faster than + existing high‐fidelity modeling. Because we anticipate that many + CWSD users will not have high‐fidelity models available, we + demonstrate that the approach provides reasonable simulations + even under significant parametric uncertainty through a + sensitivity analysis. We compare multiple graph partitioning + techniques enabling users to specify the spatial aggregation of + the partitioned network, also enabling them to preserve key + locations for simulation. We test the impact of temporal + resolution, finding that accurate simulations can be produced + with timesteps up to one hour. Our experiments show a log‐log + relationship between temporal/spatial resolution and simulation + time, enabling users to pre‐specify the efficiency and accuracy + needed for their applications. We expect that the efficiency and + flexibility of our approach may facilitate novel applications of + sewer network models ranging from continuous simulations for + long‐term planning to spatially optimizing the placement of + network sensors.", + journal = "Water Resour. Res.", + publisher = "American Geophysical Union (AGU)", + volume = 58, + number = 1, + month = jan, + year = 2022, + copyright = "http://creativecommons.org/licenses/by/4.0/", + language = "en", + doi = "10.1029/2021wr030778" +} + +@ARTICLE{Rauch2017-jz, + title = "Modelling transitions in urban water systems", + author = "Rauch, W and Urich, C and Bach, P M and Rogers, B C and de Haan, + F J and Brown, R R and Mair, M and McCarthy, D T and Kleidorfer, + M and Sitzenfrei, R and Deletic, A", + abstract = "Long term planning of urban water infrastructure requires + acknowledgement that transitions in the water system are driven + by changes in the urban environment, as well as societal + dynamics. Inherent to the complexity of these underlying + processes is that the dynamics of a system's evolution cannot be + explained by linear cause-effect relationships and cannot be + predicted under narrow sets of assumptions. Planning therefore + needs to consider the functional behaviour and performance of + integrated flexible infrastructure systems under a wide range of + future conditions. This paper presents the first step towards a + new generation of integrated planning tools that take such an + exploratory planning approach. The spatially explicit model, + denoted DAnCE4Water, integrates urban development patterns, + water infrastructure changes and the dynamics of + socio-institutional changes. While the individual components of + the DAnCE4Water model (i.e. modules for simulation of urban + development, societal dynamics and evolution/performance of + water infrastructure) have been developed elsewhere, this paper + presents their integration into a single model. We explain the + modelling framework of DAnCE4Water, its potential utility and + its software implementation. The integrated model is validated + for the case study of an urban catchment located in Melbourne, + Australia.", + journal = "Water Res.", + publisher = "Elsevier BV", + volume = 126, + pages = "501--514", + month = dec, + year = 2017, + language = "en", + doi = "10.1016/j.watres.2017.09.039" +} + + +@ARTICLE{Thrysoe2019-pi, + title = "Identifying fit-for-purpose lumped surrogate models for large + urban drainage systems using {GLUE}", + author = "Thrys{\o}e, Cecilie and Arnbjerg-Nielsen, Karsten and Borup, + Morten", + journal = "J. Hydrol. (Amst.)", + publisher = "Elsevier BV", + volume = 568, + pages = "517--533", + month = jan, + year = 2019, + language = "en", + doi = "10.1016/j.jhydrol.2018.11.005" +} + +@ARTICLE{Chegini2022-oo, + title = "An algorithm for deriving the topology of belowground urban + stormwater networks", + author = "Chegini, Taher and Li, Hong-Yi", + abstract = "Abstract. Belowground urban stormwater networks (BUSNs) are + critical for removing excess rainfall from impervious urban + areas and preventing or mitigating urban flooding. However, + available BUSN data are sparse, preventing the modeling and + analysis of urban hydrologic processes at regional and larger + scales. We propose a novel algorithm for estimating BUSNs by + drawing on concepts from graph theory and existing, extensively + available land surface data, such as street network, topography, + and land use/land cover. First, we derive the causal + relationships between the topology of BUSNs and urban surface + features based on graph theory concepts. We then apply the + causal relationships and estimate BUSNs using web-service data + retrieval, spatial analysis, and high-performance computing + techniques. Finally, we validate the derived BUSNs in the + metropolitan areas of Los Angeles, Seattle, Houston, and + Baltimore in the US, where real BUSN data are partly available + to the public. Results show that our algorithm can effectively + capture 59 \%--76 \% of the topology of real BUSN data, + depending on the supporting data quality. This algorithm has + promising potential to support large-scale urban hydrologic + modeling and future urban drainage system planning.", + journal = "Hydrol. Earth Syst. Sci.", + publisher = "Copernicus GmbH", + volume = 26, + number = 16, + pages = "4279--4300", + month = aug, + year = 2022, + copyright = "https://creativecommons.org/licenses/by/4.0/", + language = "en", + doi = "10.5194/hess-26-4279-2022", +} + +@ARTICLE{Reyes-Silva2022-pr, + title = "An evaluation framework for urban pluvial flooding based on + open-access data", + author = "Reyes-Silva, Julian D and Novoa, Diego and Helm, Bj{\"o}rn and + Krebs, Peter", + abstract = "Identifying the location and estimating the magnitude of urban + pluvial flooding events is essential to assess their impacts, + particularly in areas where data are unavailable. The present + work focused on developing and exemplifying a tool to evaluate + urban pluvial flooding based on open-access information. The + tool has three separate submodules: (1) sewer network generation + and design; (2) hydrodynamic model development; (3) urban + pluvial flood evaluation. Application of the first two modules + in two catchments and comparison of these results with real data + indicated that the tool was able to generate systems with + realistic layouts and hydraulic properties. Hydrodynamic models + derived from this data were able to simulate realistic flow + dynamics. The third module was evaluated for one of the study + cases. The results of this indicated that the current approach + could be used to identify flood areas and associated flood + depths during different rainfall scenarios. The outcomes of this + study could be used in a wide variety of contexts. For example, + it could provide information in areas with data scarcity or + uncertainty or serve as a tool for prospective planning, design, + and decision making.", + journal = "Water (Basel)", + publisher = "MDPI AG", + volume = 15, + number = 1, + pages = "46", + month = dec, + year = 2022, + copyright = "https://creativecommons.org/licenses/by/4.0/", + language = "en", + doi = "10.3390/w15010046" +} + +@UNPUBLISHED{Dobson2024-dv, + title = "{SWMManywhere}: A global-scale workflow for generation and + sensitivity analysis of synthetic urban drainage models", + author = "Dobson, Barnaby and Jovanovic, Tijana and Alonso-{\'A}lvarez, + Diego and Chegini, Taher", + abstract = "Continual improvements in publicly available global geospatial + datasets provide an opportunity for deriving urban drainage + networks and simulation models of these networks (UDMs) + worldwide. We present SWMManywhere, which leverages such datasets + for generating synthetic UDMs and creating a Storm Water + Management Model for any urban area globally. SWMManywhere's + highly modular and parameterised approach enables significant + customisation to explore hydraulicly feasible network + configurations. Key novelties of our workflow are in network + topology derivation that accounts for combined effects of + impervious area and pipe slope. We assess SWMManywhere by + comparing pluvial flooding, drainage network outflows, and design + with known networks. The results demonstrate high quality + simulations are achievable with a synthetic approach even for + large networks. Our extensive sensitivity analysis shows that the + locations of manholes, outfalls, and underlying street network + are the most sensitive parameters. We find widespread sensitivity + across all parameters without clearly defined values that they + should take, thus, recommending an uncertainty driven approach to + synthetic drainage network modelling. This study showcases + significant potential of SWMManywhere for research and industry + applications to provide drainage network models in urban areas + where traditional approaches are impractical.", + journal = "EarthArXiv", + month = oct, + year = 2024, + doi = "10.31223/X5GT5X" +} + +@ARTICLE{Khurelbaatar2021-sp, + title = "Data reduced method for cost comparison of wastewater management + scenarios--case study for two settlements in Jordan and Oman", + author = "Khurelbaatar, Ganbaatar and Al Marzuqi, Bishara and Van + Afferden, Manfred and M{\"u}ller, Roland A and Friesen, Jan", + abstract = "Safe access to sanitation is at the core of the United Nations + Sustainable Development Goal (SDG) \#6. Currently, it is + estimated that this goal cannot be met by 2030. Despite all + kinds of administrational hurdles, meeting SDG\#6 depends on + considerable investment. In order to get a chance at fulfilling + SGD\#6, the most cost-effective wastewater management has to be + identified. Wastewater can be managed in different ways ranging + from central treatment plants connected to individual households + through sewer networks down to tanker fleets servicing each + household. Depending on the geographical setting, investment + costs, operation and maintenance as well as social acceptance + there is no single best solution. Instead, identifying the + optimal wastewater management is highly localized and + country-specific or even settlement-specific. Within this study + we present a data-reduced scenario generation and assessment for + wastewater management based on the ALLOWS method that can be + applied to individual settlements. Results provide cost-ranked + wastewater management scenarios that enable decision makers to + select the most cost-effective and feasible scenario. Our study + starts with a detailed step-by-step methodology of a + data-reduced ALLOWS approach. The approach is applied to two + small settlements in Jordan and Oman with comparable population + size for which a set of five scenarios along a decentralization + gradient is defined and generated: centralized, + semi-centralized, decentralized, and on-site/tanker. Considering + spatial specificities and country-specific cost data, the five + scenarios are cost-ranked and discussed in view of the two + settlement settings. For Jordan specific treatment costs range + from 3.8 to 6.9 USD/m3of treated water and for Oman from 2.3 to + 10.1 USD/m3. Although the scenario ranking differs, for both + settlements the decentralized scenario is identified as the most + cost effective, where wastewater is treated on-site for + less-populated parts and by small cluster treatment plants for + higher density parts. Further, potential extensions providing + users with more functionality depending upon data availability + for the data-reduced ALLOWS method are discussed. Using globally + available data, the data-reduced can be applied worldwide. In + view of SDG\#6, we present a methodology that closes the gap + between country-scale investment estimates and the most + cost-effective wastewater management scenarios at settlement + level.", + journal = "Front. Environ. Sci.", + publisher = "Frontiers Media SA", + volume = 9, + month = may, + year = 2021, + copyright = "https://creativecommons.org/licenses/by/4.0/", + doi = "10.3389/fenvs.2021.626634" +} + +@misc{VIDA2023, +author = {VIDA}, +title = {{Google-Microsoft Open Buildings}}, +url = {https://beta.source.coop/repositories/vida/google-microsoft-open-buildings}, +urldate = {2024-07-30}, +year = {2023} +} + +@article{Crippen2016, +abstract = {Abstract. NASADEM is a near-global elevation model that is being produced primarily by completely reprocessing the Shuttle Radar Topography Mission (SRTM) radar data and then merging it with refined ASTER GDEM elevations. The new and improved SRTM elevations in NASADEM result from better vertical control of each SRTM data swath via reference to ICESat elevations and from SRTM void reductions using advanced interferometric unwrapping algorithms. Remnant voids will be filled primarily by GDEM3, but with reduction of GDEM glitches (mostly related to clouds) and therefore with only minor need for secondary sources of fill.}, +author = {Crippen, R. and Buckley, S. and Agram, P. and Belz, E. and Gurrola, E. and Hensley, S. and Kobrick, M. and Lavalle, M. and Martin, J. and Neumann, M. and Nguyen, Q. and Rosen, P. and Shimada, J. and Simard, M. and Tung, W.}, +doi = {10.5194/isprs-archives-XLI-B4-125-2016}, +issn = {2194-9034}, +journal = {The International Archives of the Photogrammetry, Remote Sensing and Spatial Information Sciences}, +month = {jun}, +pages = {125--128}, +title = {{NASADEM GLOBAL ELEVATION MODEL: METHODS AND PROGRESS}}, +url = {https://isprs-archives.copernicus.org/articles/XLI-B4/125/2016/}, +volume = {XLI-B4}, +year = {2016} +} + +@article{Boeing2017, +author = {Boeing, Geoff}, +doi = {10.1016/j.compenvurbsys.2017.05.004}, +issn = {01989715}, +journal = {Computers, Environment and Urban Systems}, +month = {sep}, +pages = {126--139}, +title = {{OSMnx: New methods for acquiring, constructing, analyzing, and visualizing complex street networks}}, +url = {https://linkinghub.elsevier.com/retrieve/pii/S0198971516303970}, +volume = {65}, +year = {2017} +} + +@misc{OpenStreetMap, + author = {{OpenStreetMap contributors}}, + title = {{Planet dump retrieved from https://planet.osm.org }}, + howpublished = "\url{ https://www.openstreetmap.org }", + year = {2017}, +} + + @misc{OpenStreetMap-overture, + author = {{OpenStreetMap contributors}}, + title = {{Overture Maps Foundation}}, + howpublished = "\url{ https://overturemaps.org/ }", + year = {2024}, + } \ No newline at end of file diff --git a/docs/paper/paper.md b/docs/paper/paper.md new file mode 100644 index 00000000..0c3933b2 --- /dev/null +++ b/docs/paper/paper.md @@ -0,0 +1,76 @@ +--- +title: 'SWMManywhere: Synthesise Urban Drainage Network Models Anywhere in the World' +tags: + - python + - stormwater + - hydrology-stormwater-analysis + - swmm5 + - swmm + - hydraulic-modelling +authors: + - name: "Barnaby Dobson" + orcid: "0000-0002-0149-4124" + affiliation: 1 + - name: "Diego Alonso-Álvarez" + orcid: "0000-0002-0060-9495" + affiliation: 1 + - name: "Taher Chegini" + orcid: "0000-0002-5430-6000" + affiliation: 2 +affiliations: + - name: Imperial College London, UK + index: 1 + - name: Purdue University, US + index: 2 +date: 16 October 2024 +bibliography: paper.bib +--- + +## Summary + +Urban drainage network models (UDMs) are useful for a variety of purposes, most notably simulating and alleviating pluvial flooding. Despite the clear usefulness of UDMs, they are often not used owing to the difficulty and expense of creating them. This creates a significant gap for users attempting to generate UDMs if they are not able to perform an expensive underground survey. + +## Statement of need + +A variety of literature exists to derive UDMs from GIS data, producing hydraulically feasible models that closely approximate real-world systems [@Blumensaat2012-hd;@Chahinian2019-lg;@Reyes-Silva2022-pr;@Chegini2022-oo]. We identify some key limitations of these approaches, most notably the lack of automatic data acquisition and preprocessing, that all approaches are closed-source to date, and that a key feature of such an approach should be to facilitate extension and customisation. + +SWMManywhere is an open-source Python package designed for the global synthesis of urban drainage networks. SWMManywhere integrates publicly available geospatial data and automates data acquisition and preprocessing, reducing the technical burden on users. Designed for both researchers and practitioners in urban water management, SWMManywhere responds to the limitations of existing methods by providing an end-to-end, open-source, and customisable solution. + +## Features + +SWMManywhere includes a variety of key features aimed to improve useability and usefulness. A command line interface (CLI) offers a flexible workflow, providing an accessible entry point to using and customising synthesis. Its parameterized design enables detailed sensitivity analyses, allowing users to understand and manage uncertainties inherent in urban drainage modelling [@Dobson2024-dv]. By emphasizing user control, SWMManywhere allows tuning of outputs with parameters to meet local requirements, making it adaptable to a wide range of scenarios. We provide further details on the data and general approach below. + +### Data + +A variety of datasets were selected to enable SWMManywhere to be applied globally, \autoref{table:table1}. + +: SWMManywhere data sources. \label{table:table1} + +| Data Source | Description | Reference | +|-------------|-------------| --------- | +| **OpenStreetMap (OSM)** | Provides global street and river data, used to define potential pipe locations and outfall points for drainage networks. | [@Boeing2017;@OpenStreetMap] | +| **Google-Microsoft Open Buildings** | A dataset of global building footprints, used for estimating impervious surfaces essential for runoff calculations. | [@OpenStreetMap-overture] | +| **NASADEM** | Provides 30m resolution global digital elevation model (DEM) data to support sub-catchment delineation and slope calculation. | [@Crippen2016] | + +These datasets are global in their coverage, and we consider them of sufficient quality in locations that we have tested [@Dobson2024-dv], however, we urge users to check data in their specific case study. + +### Approach and customisation + +The core task in SWMManywhere is to begin with a 'starting graph' (e.g., an OSM street graph), refine this graph first into manhole locations and potential pipe locations, eliminate pipes from unnecessary locations, and then dimension the resulting pipe network so that it can be simulated in a software such as [SWMM](https://www.epa.gov/sites/default/files/2019-02/documents/epaswmm5_1_manual_master_8-2-15.pdf). These operations take place in an iterative approach, where each function takes a graph, and returns the transformed graph, thus each operation is referred to as a 'graph function'. The use of graph functions in SWMManywhere enables modular packaging of functions, easy customisation of the approach (e.g., by adding/removing/reordering graph functions), and explicit definition of parameters for each graph function. Explanations for making these customisations are available in the [documentation](https://imperialcollegelondon.github.io/SWMManywhere/). Ultimately, this customisability facilitates exploring uncertainty in urban drainage modelling in a way that reflects not just the model itself but the model creation process, as is demonstrated in [@Dobson2024-dv]. + +We visualise the example from the [extended demonstration](https://imperialcollegelondon.github.io/SWMManywhere/notebooks/extended_demo/) in the documentation to illustrate how changing relatively few parameter values in a strategic way can dramatically change the nature of the synthesised network \autoref{fig:fig1}. + +![Example of output customisation with SWMManywhere. Black nodes are manholes, black lines are pipes, red nodes are outfalls.\label{fig:fig1}](extended_demo.png) + +## Outlook + +While we believe that SWMManywhere is a useful tool it has a variety of current limitations that present an exciting outlook for future research. Key improvements to the overall realism of the approach may be made in the future, in particular, + +- Based on the findings of a sensitivity analysis [@Dobson2024-dv], better identification of manhole locations and outfalls will be critical to narrowing uncertainty in simulation outputs and improving realism. +- Capturing the gradual evolution of a network over time is known to be important in UDM synthesis [@Rauch2017-jz], and further illustrated by SWMManywhere results [@Dobson2024-dv]. We do not know of a global database that provides the information that would be necessary to capture this, but it may exist in the future or for local applications. + +# Acknowledgements + +BD is funded through the Imperial College Research Fellowship scheme, which also funded the software development. We acknowledge computational resources and support provided by the [Imperial College Research Computing Service](http://doi.org/10.14469/hpc/2232). + +# References diff --git a/mkdocs.yml b/mkdocs.yml index 039abfc1..0fecbca0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -15,7 +15,10 @@ plugins: execute: true - search - include-markdown - + - bibtex: + bib_file: "./docs/paper/paper.bib" + csl_file: "./docs/paper/apa.csl" + cite_inline: false repo_url: https://github.com/ImperialCollegeLondon/SWMManywhere site_url: https://imperialcollegelondon.github.io/SWMManywhere/ @@ -38,6 +41,7 @@ extra_javascript: nav: - Home: index.md + - About: ./paper/paper.pdf - Quickstart: quickstart.md - Guides: - Configuration guide: config_guide.md diff --git a/pyproject.toml b/pyproject.toml index 599b07fe..9d4f3af5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -77,11 +77,15 @@ optional-dependencies.dev = [ ] optional-dependencies.doc = [ "mkdocs", + "mkdocs-autorefs", + "mkdocs-bibtex", + "mkdocs-coverage", "mkdocs-include-markdown-plugin", "mkdocs-jupyter", "mkdocs-material", "mkdocs-material-extensions", "mkdocstrings[python]", + "pypandoc", ] urls.Documentation = "https://imperialcollegelondon.github.io/SWMManywhere/" urls.Issues = "https://github.com/ImperialCollegeLondon/SWMManywhere/issues" @@ -111,7 +115,7 @@ lint.isort.required-imports = [ "from __future__ import annotations" ] lint.pydocstyle.convention = "google" [tool.codespell] -skip = "src/swmmanywhere/defs/iso_converter.yml,*.inp" +skip = "src/swmmanywhere/defs/iso_converter.yml,*.inp,docs/paper/*" ignore-words-list = "gage,gages,Carrer" [tool.pytest.ini_options] diff --git a/src/swmmanywhere/graph_utilities.py b/src/swmmanywhere/graph_utilities.py index 9e1f601e..48306d01 100644 --- a/src/swmmanywhere/graph_utilities.py +++ b/src/swmmanywhere/graph_utilities.py @@ -8,6 +8,7 @@ import json import tempfile +import warnings from abc import ABC, abstractmethod from pathlib import Path from typing import Callable, List, Optional @@ -54,7 +55,9 @@ def save_graph(G: nx.Graph, fid: Path) -> None: G (nx.Graph): A graph fid (Path): The path to the file """ - json_data = nx.node_link_data(G) + with warnings.catch_warnings(): + warnings.simplefilter("ignore", FutureWarning) + json_data = nx.node_link_data(G) with fid.open("w") as file: json.dump(json_data, file, default=_serialize_line_string)