swmm_api: A Python Package for Automation, Customization, and Visualization in SWMM-Based Urban Drainage Modeling

Round 1

Reviewer 1 Report

Comments and Suggestions for Authors

The technical note "swmm_api: A Python Package for Automation, Customization, and Visualization in SWMM-based Urban Drainage Modeling" provides a significant contribution to the field of urban water management and modeling by offering a Python package designed to automate and enhance the use of the SWMM model. It addresses clearly identified gaps in existing tools and provides practical solutions through comprehensive software implementation. This technical note is generally clear, logically structured, and technically thorough. However, there is scope for improvement in various areas detailed below.

 

Comments:

• The technical note includes illustrative examples, more detailed information on specific case studies (such as the mentioned municipal application in Graz) would substantially enhance the paper’s applicability and demonstrate clear benefits. Real-world applications including numerical results (e.g., computational performance, reduced computational times) would make the argument for practical relevance stronger.
• A critical point currently lacking in the technical note is a structured validation of swmm_api against known benchmarks or standardized test cases. Including results from validation exercises to ensure model accuracy and consistency would strengthen the technical note ’s scientific rigor.
• The technical note addresses memory efficiency briefly (Section 2.3). However, more detailed analysis or benchmarking of performance (memory usage, processing time, scalability) under different modeling scenarios (large-scale systems, complex parameter sets) is essential for demonstrating the robustness of swmm_api in practical use.
• Ensure consistency of terms and abbreviations throughout the technical note . For instance, "subcatchment (SC)" appears inconsistently with "SC" sometimes used without a preceding definition.
• Ensure all figures (Figures 2 and 4) are of high quality with clear legends and annotations for better readability.
• Provide version numbers or specify recommended versions for critical dependencies to enhance reproducibility and ease of use.
• Briefly highlight specific available examples or notebooks that new users could directly adopt, further lowering the entry barrier to using swmm_api.
• Ensure the most recent and relevant literature, particularly regarding Python tools for urban hydrological modeling.

Author Response

Thank you very much for taking the time to review this manuscript. Please find the detailed responses below and the corresponding revisions/corrections in the re-submitted files.

Comments 1: The technical note includes illustrative examples, more detailed information on specific case studies (such as the mentioned municipal application in Graz) would substantially enhance the paper’s applicability and demonstrate clear benefits. Real-world applications including numerical results (e.g., computational performance, reduced computational times) would make the argument for practical relevance stronger.

Response 1: Thank you for the comment. I added further details to the municipal Graz model use case in Section 3 to better illustrate practical relevance. For points regarding computational performance, please see Responses 2 and 3.

Comments 2: A critical point currently lacking in the technical note is a structured validation of swmm_api against known benchmarks or standardized test cases. Including results from validation exercises to ensure model accuracy and consistency would strengthen the technical note ’s scientific rigor.

Response 2: Thank you for the comment. Since swmm_api does not introduce a new solver but relies on the official EPA SWMM engine (e.g., via runswmm or pyswmm), the package does not affect simulation accuracy or performance. Its role is limited to preparing input files and processing outputs, leaving the numerical results unchanged.

Comments 3: The technical note addresses memory efficiency briefly (Section 2.3). However, more detailed analysis or benchmarking of performance (memory usage, processing time, scalability) under different modeling scenarios (large-scale systems, complex parameter sets) is essential for demonstrating the robustness of swmm_api in practical use.

Response 3: Thank you for the constructive feedback. I added a new Section 4 presenting benchmarks on input and output file processing, covering different model sizes. The section includes performance metrics such as processing time, memory usage, and scalability, along with result tables. A reference to this benchmark section was also added in Section 2.3 to guide readers intuitively.

Comments 4: Ensure consistency of terms and abbreviations throughout the technical note . For instance, "subcatchment (SC)" appears inconsistently with "SC" sometimes used without a preceding definition.

Response 4: Thank you for pointing this out. I reviewed the manuscript for consistent use of abbreviations and corrected instances where "SC" appeared without prior definition. I also checked other abbreviations to ensure consistency throughout the text.

Comments 5: Ensure all figures (Figures 2 and 4) are of high quality with clear legends and annotations for better readability.

Response 5: Thank you for the comment. I increased the overall size of Figure 2, added more items to the legend, and enlarged the legend font for better readability. I also included a clear legend in Figure 4 to improve clarity and interpretation.

Comments 6: Provide version numbers or specify recommended versions for critical dependencies to enhance reproducibility and ease of use.

Response 6: Thank you for the suggestion. I have added a new subsection, 2.6.1 Recommended Software Versions, to explicitly list version numbers for key dependencies. This addition supports reproducibility and helps users set up their environment more easily.

Comments 7: Briefly highlight specific available examples or notebooks that new users could directly adopt, further lowering the entry barrier to using swmm_api.

Response 7: Thank you for the suggestion. A link to the documentation with example usage is provided in Section 2.7. Additionally, Sections 3.1 to 3.3 present advanced use cases, each linked to the corresponding example source code, helping new users get started quickly.

Comments 8: Ensure the most recent and relevant literature, particularly regarding Python tools for urban hydrological modeling.

Response 8: Thank you for the comment. I added references to recent Python-based tools for urban hydrological modeling—specifically pystorms, stormreactor, pipedream, and waterpybal—at the end of the Introduction to better reflect the current state of the field.

 

Reviewer 2 Report

Comments and Suggestions for Authors

The paper describes the features of a novel api named “swmm_api” extremely useful for managing SWMM models.

This api has been developed on Python and integrates SWMM model creation, editing, analysis and visualization within the Pithon’s ecosystem.

The api supports advanced GIS integration, sensitivity analysis, calibration and uncertainty estimation through GeoPandas, SALib and SPOTPY.

The results achieved demonstrated exceptional efficiency making batch simulations managing thousands of files.

The author presents a number of success cases where this api was used illustrating in this way its power.

I think that the description of the capabilities the api presented in this paper deserves to be disseminated between the scientific community through its publication in Water.

 

Minor issues:

Line 386: Please change “figure 6n” by “figure 6b”

Author Response

Thank you very much for taking the time to review this manuscript and thank you for that kind review.

Comments 1: Line 386: Please change “figure 6n” by “figure 6b”

Response 1: The typo was fixed.

Reviewer 3 Report

Comments and Suggestions for Authors

This manuscript presents swmm_api, a Python package designed to enhance the automation, customization, and visualization capabilities of SWMM (Storm Water Management Model) in urban drainage modeling. The work addresses a notable gap in the current SWMM ecosystem by enabling batch simulations, structural editing, and seamless integration with the Python data science stack. The manuscript is well-structured, technically sound, and demonstrates strong practical relevance through detailed application examples.

However, to further improve the quality and impact of the work, I recommend the authors consider the following suggestions, particularly concerning functionality completeness, user experience, and scientific rigor.

1. Section 2 is very long. Consider breaking it into clearly numbered subsections.
2. Use short summary lines to conclude key paragraphs and improve flow.
3. The package currently lacks built-in checks for data types, value ranges, or unit consistency.
4. Some macro functions assume metric units. The authors are encouraged to implement unit detection or provide clear warnings to prevent potential misuse.
5. While the package purposefully avoids overlapping with pyswmm, introducing minimal runtime interaction features—such as simulation progress monitoring or error alerts—could enhance usability.

Author Response

Thank you very much for taking the time to review this manuscript. Please find the detailed responses below and the corresponding revisions/corrections in the re-submitted files.

Comments 1: Section 2 is very long. Consider breaking it into clearly numbered subsections.

Response 1: Thank you for the helpful suggestion. Section 2 was already structured into eight subsections (2.1–2.8). However, subsection 2.2 was relatively long, spanning over 1.5 pages. To improve readability, it has now been split into two subsubsections (2.2.1 and 2.2.2), ensuring that no single subsection exceeds half a page.

Comments 2: Use short summary lines to conclude key paragraphs and improve flow.

Response 2: Thank you for the suggestion. I appreciate the intention to improve clarity. However, I chose not to include summary lines at the end of paragraphs to maintain a concise and scientific writing style. The content is already structured with clear sectioning and topic sentences, which I believe sufficiently guide the reader. Adding summary lines would introduce redundancy and potentially disrupt the compact flow of technical explanations.

Comments 3: The package currently lacks built-in checks for data types, value ranges, or unit consistency.

Response 3: Thank you for the valuable comment. While I agree that data validation is important, implementing strict value range checks is not practical, as many parameters can take a wide range of valid values depending on the scientific context. Where necessary, internal data type checks are already implemented, and in other cases, flexibility is intentional to allow broad user input. Unit consistency is addressed in a separate comment, but I note in Section 2.8 that users must ensure data correctness. Importantly, the package supports a complete workflow in Python, including running simulations and parsing report files for errors and warnings. This design preserves flexibility and ensures compatibility with future changes in SWMM input formats.

Comments 4: Some macro functions assume metric units. The authors are encouraged to implement unit detection or provide clear warnings to prevent potential misuse.

Response 4: Thank you for the helpful comment. Currently, macros involving GIS data—such as updating conduit lengths or subcatchment areas—are designed for metric units only. These functions raise an error if used with imperial units, preventing unintended misuse. As the package is open-source, users can easily copy and adapt these functions as needed. I welcome community contributions to extend support for other unit systems in future versions. I have also clarified this limitation in Section 2.7 and included a corresponding note in the documentation.

Comments 5: While the package purposefully avoids overlapping with pyswmm, introducing minimal runtime interaction features—such as simulation progress monitoring or error alerts—could enhance usability.

Response 5: Thank you for the suggestion. As described in Section 2.6, simulation progress monitoring is already supported via `pyswmm` in combination with `tqdm`, or by displaying the standard SWMM command-line output. Error messages and warnings are extracted from the report file using built-in functions, and they are automatically displayed if a simulation fails. These features provide runtime feedback while preserving the package’s focus on pre- and post-processing functionality.