Modelling water quantity and quality for integrated water cycle management with the WSIMOD software

Dobson, Barnaby; Liu, Leyang; Mijic, Ana

doi:https://doi.org/10.5194/egusphere-2023-1662

Preprints

https://doi.org/10.5194/egusphere-2023-1662

Preprints

13 Oct 2023

| 13 Oct 2023

Modelling water quantity and quality for integrated water cycle management with the WSIMOD software

Barnaby Dobson, Leyang Liu, and Ana Mijic

Abstract. Problems of water system integration occur when a model’s boundaries are too narrow to capture interactions and feedbacks across the water cycle. We propose that integrated water systems models are required to overcome them, and are necessary to understand emergent system behaviour, to expand model boundaries, to evaluate interventions, and to ensure simulations reflect stakeholder goals. We present the Water Systems Integrated Modelling Framework (WSIMOD) software as one such approach and describe its theoretical basis, covering the node and arc nature of simulations, the integration framework that enables communication between model elements, and the model orchestration to customise interactions. We highlight data requirements for creating such a model and the potential for future development and refinement. WSIMOD offers a flexible and powerful approach to represent water systems, and we hope it will encourage further research and application into using model integration towards achieving sustainable and resilient water management.

Received: 19 Jul 2023 – Discussion started: 13 Oct 2023

Download & links

Barnaby Dobson, Leyang Liu, and Ana Mijic

Status: closed

AC1: 'Comment on egusphere-2023-1662', Barnaby Dobson, 01 Nov 2023

Please note that the ownership of the repository for WSIMOD has changed to ImperialCollegeLondon, and so documentation links can now be found at: https://imperialcollegelondon.github.io/wsi/

Citation: https://doi.org/10.5194/egusphere-2023-1662-AC1
CEC1:
'Comment on egusphere-2023-1662', Juan Antonio Añel, 03 Nov 2023

Dear authors,
Unfortunately, after checking your manuscript, it has come to our attention that it does not comply with our "Code and Data Policy".
https://www.geoscientific-model-development.net/policies/code_and_data_policy.html
You have archived your code on GitHub. However, GitHub is not a suitable repository for scientific publication. GitHub itself instructs authors to use other alternatives for long-term archival and publishing, such as Zenodo. Therefore, please, publish your code in one of the appropriate repositories, and reply to this comment with the relevant information (link and DOI) as soon as possible, as it should be available before the Discussions stage. Also, please, include the relevant primary input/output data.

In this way, if you do not fix this problem, we will have to reject your manuscript for publication in our journal. I should note that, actually, your manuscript should not have been accepted in Discussions, given this lack of compliance with our policy. Therefore, the current situation with your manuscript is irregular.

Also, you must include in a potentially reviewed version of your manuscript the modified 'Code and Data Availability' section, the DOI of the code (and another DOI for the dataset if necessary).

Please, note that the link for the GitHub repository in your manuscript does not work.

Juan A. Añel
Geosci. Model Dev. Executive Editor

Citation: https://doi.org/10.5194/egusphere-2023-1662-CEC1
- AC2:
  'Reply on CEC1', Barnaby Dobson, 06 Nov 2023
  
  Dear Juan,
  
  Many thanks - please find the Zenodo DOI: https://doi.org/10.5281/zenodo.7662569
  
  Apologies regarding the GitHub link and documentation links in the current manuscript - the ownership of the repository has changed from my personal account to my organisation - so the GitHub link is now:
  https://github.com/ImperialCollegeLondon/wsi
  And documentation now:
  https://imperialcollegelondon.github.io/wsi/
  
  I will of course update all of these links and add the zenodo doi when revising the manuscript.
  Please let me know if anything further is required.
  
  Best,
  Barney
  
  Citation: https://doi.org/10.5194/egusphere-2023-1662-AC2
  - CEC2: 'Reply on AC2', Juan Antonio Añel, 07 Nov 2023
    
    Dear authors,
    Many thanks for fixing these issues. We can now consider your manuscript compliant with our code policy.
    However, please note that Git repositories in institutional servers are not in compliance with it, so you should move all the documentation to Zenodo, too.
    Regards,
    Juan A. Añel
    Geosci. Model Dev. Executive Editor
    
    Citation: https://doi.org/10.5194/egusphere-2023-1662-CEC2
    
    AC3: 'Reply on CEC2', Barnaby Dobson, 07 Nov 2023
    
    Dear Juan,
    
    Apologies - I didn't mean to imply that the institutional repo was a substitute, just that it was why the links weren't working.
    
    The documentation already exists in the zenodo repo under docs, including instructions to compile it into a readthedocs webpage. Is this under the code and data policy - it doesn't seem to make any provision to the format of wiki-style documentation.
    
    Best,
    Barney
    
    Citation: https://doi.org/10.5194/egusphere-2023-1662-AC3
RC1:
'Comment on egusphere-2023-1662', Hongyi Li, 18 Nov 2023

I enjoyed reading this manuscript. I also applaud the authors for such a nice contribution to the modeling community. Given that GMD is highly interdisciplinary and has a broad audience, I encourage the authors to better define some terminologies upfront. A few specific, minor comments are listed below.
1. Line 26-28. "water cycle" --> "terrestrial water cycle" since the components listed here do not include atmospheric or ocean components. It seems different people have different definitions or understandings about the "components" in a water cycle. To help the readers better understand, a conceptual diagram might be useful here to illustrate the various components (particularly those represented in the model) and their physical and anthropogenic linkages. Lastly, by "hydrological catchments" do the authors mean the surface areas where rain falls and runoff is generated and routed into rivers? If so, I'd suggest placing it at the very beginning of this list, since the terrestrial water cycles (at the catchment, regional, or global scales) begin with rainfall and runoff processes.
2. Line 28. What is the difference between "hydrological catchments" and "river catchments"? If they are the same, please just use "catchments" after the definition upfront.
3. Line 74, "abstracts". Please use another word if possible to avoid confusion. For example, "abstraction" could mean "rainfall infiltration and/o retention" to some hydrologists.
4 . Line 457-460. It would be better to move this example upfront in the introduction, perhaps along with another couple of classic ones. This way, the readers will have a better sense of what are "boundary conditions" and then the authors intend to achieve. I did not get this puzzle resolved until reading to this point.

Citation: https://doi.org/10.5194/egusphere-2023-1662-RC1
- AC4: 'Reply on RC1', Barnaby Dobson, 23 Nov 2023
  
  Dear Prof Li,
  
  Thankyou for the kind remarks. We completely agree with your request for more clarifications in the terminology to make the paper understandable to a wider audience. We will make these changes and review the paper for other areas where clarity could be added when we revise the manuscript after the open discussion.
  
  Best,
  Barney
  
  Citation: https://doi.org/10.5194/egusphere-2023-1662-AC4
RC2:
'Comment on egusphere-2023-1662', Anonymous Referee #2, 26 Mar 2024

The authors present an open-source Python tool to make integrated model of the water cycle, including water quantity and quality. They start with a review of the state of the art, then present the conceptual structure of the model, very briefly introduce a demonstration and then focus on discussing the need for the tool. Finally they present some conclusions.
The work that the authors present is interesting and, in my opinion, within the scope of GMD. Their tool being a library, may serve to others researchers to adapt it to their needs, either using the already developed classes, either by modifying the code. I think the paper may deserved to be published in GMD, however I have a major concern about the paper structure.
Section 2 presents a conceptualization of the model, which is not evident to follow. Such a conceptualization is important, because it allows to extend the model in an easy way and to represent similar elements with a minimal amount of code. However, conceptualizations are difficult to grasp, so I would suggest that the authors combine section 3 (which currently is not very illustrative, probably because the link provided is not working for me -I get a 404 error-) with section 2 in such a way that they first explain a canonical case in water management, that anyone could understand, and from there, they present the conceptualization.
In this way, the reader would be able to put "some meat" in the concepts presented, making it easier for the reader to apply the WSIMOD software to their own problems. Without such a change, the presentation may not be clear enough to ensure an understanding.
Moreover, after having checked the paper where the source code was published, I am also missing some more technical details. They may be better suited to supplementary material, but I believe that an explanation of the technical details and equations behind the model elements would be interesting. Not only to have all that information in a citable location, but also to have it all concentrated in one place, so that when problems arise, the users of the library may try to troubleshoot problems with the equations looking at just one section of the paper. (This information may be somewhere in the documentation, but I have not been able to find it).
* Minor comments

+ Line 19/20: Improve use of verbs.

+ Line 201: "our" seems to be out of place.

+ Line 354: adjudged may not be the term the authors intended to use

Citation: https://doi.org/10.5194/egusphere-2023-1662-RC2
- AC5: 'Reply on RC2', Barnaby Dobson, 26 Mar 2024
  
  Dear Reviewer,
  Thankyou so much for your review and encouraging comments. We will address this review alongside the other review in one large revision.
  Though I will just briefly highlight that since the paper was originally submitted (rather a while ago!) the documentation and code is now hosted by Imperial College London:
  https://github.com/ImperialCollegeLondon/wsi
  https://imperialcollegelondon.github.io/wsi/
  
  We will of course update the hyperlinks appropriately in this revision.
  
  Citation: https://doi.org/10.5194/egusphere-2023-1662-AC5

Status: closed

AC1: 'Comment on egusphere-2023-1662', Barnaby Dobson, 01 Nov 2023

Please note that the ownership of the repository for WSIMOD has changed to ImperialCollegeLondon, and so documentation links can now be found at: https://imperialcollegelondon.github.io/wsi/

Citation: https://doi.org/10.5194/egusphere-2023-1662-AC1
CEC1:
'Comment on egusphere-2023-1662', Juan Antonio Añel, 03 Nov 2023

Dear authors,
Unfortunately, after checking your manuscript, it has come to our attention that it does not comply with our "Code and Data Policy".
https://www.geoscientific-model-development.net/policies/code_and_data_policy.html
You have archived your code on GitHub. However, GitHub is not a suitable repository for scientific publication. GitHub itself instructs authors to use other alternatives for long-term archival and publishing, such as Zenodo. Therefore, please, publish your code in one of the appropriate repositories, and reply to this comment with the relevant information (link and DOI) as soon as possible, as it should be available before the Discussions stage. Also, please, include the relevant primary input/output data.

In this way, if you do not fix this problem, we will have to reject your manuscript for publication in our journal. I should note that, actually, your manuscript should not have been accepted in Discussions, given this lack of compliance with our policy. Therefore, the current situation with your manuscript is irregular.

Also, you must include in a potentially reviewed version of your manuscript the modified 'Code and Data Availability' section, the DOI of the code (and another DOI for the dataset if necessary).

Please, note that the link for the GitHub repository in your manuscript does not work.

Juan A. Añel
Geosci. Model Dev. Executive Editor

Citation: https://doi.org/10.5194/egusphere-2023-1662-CEC1
- AC2:
  'Reply on CEC1', Barnaby Dobson, 06 Nov 2023
  
  Dear Juan,
  
  Many thanks - please find the Zenodo DOI: https://doi.org/10.5281/zenodo.7662569
  
  Apologies regarding the GitHub link and documentation links in the current manuscript - the ownership of the repository has changed from my personal account to my organisation - so the GitHub link is now:
  https://github.com/ImperialCollegeLondon/wsi
  And documentation now:
  https://imperialcollegelondon.github.io/wsi/
  
  I will of course update all of these links and add the zenodo doi when revising the manuscript.
  Please let me know if anything further is required.
  
  Best,
  Barney
  
  Citation: https://doi.org/10.5194/egusphere-2023-1662-AC2
  - CEC2: 'Reply on AC2', Juan Antonio Añel, 07 Nov 2023
    
    Dear authors,
    Many thanks for fixing these issues. We can now consider your manuscript compliant with our code policy.
    However, please note that Git repositories in institutional servers are not in compliance with it, so you should move all the documentation to Zenodo, too.
    Regards,
    Juan A. Añel
    Geosci. Model Dev. Executive Editor
    
    Citation: https://doi.org/10.5194/egusphere-2023-1662-CEC2
    
    AC3: 'Reply on CEC2', Barnaby Dobson, 07 Nov 2023
    
    Dear Juan,
    
    Apologies - I didn't mean to imply that the institutional repo was a substitute, just that it was why the links weren't working.
    
    The documentation already exists in the zenodo repo under docs, including instructions to compile it into a readthedocs webpage. Is this under the code and data policy - it doesn't seem to make any provision to the format of wiki-style documentation.
    
    Best,
    Barney
    
    Citation: https://doi.org/10.5194/egusphere-2023-1662-AC3
RC1:
'Comment on egusphere-2023-1662', Hongyi Li, 18 Nov 2023

I enjoyed reading this manuscript. I also applaud the authors for such a nice contribution to the modeling community. Given that GMD is highly interdisciplinary and has a broad audience, I encourage the authors to better define some terminologies upfront. A few specific, minor comments are listed below.
1. Line 26-28. "water cycle" --> "terrestrial water cycle" since the components listed here do not include atmospheric or ocean components. It seems different people have different definitions or understandings about the "components" in a water cycle. To help the readers better understand, a conceptual diagram might be useful here to illustrate the various components (particularly those represented in the model) and their physical and anthropogenic linkages. Lastly, by "hydrological catchments" do the authors mean the surface areas where rain falls and runoff is generated and routed into rivers? If so, I'd suggest placing it at the very beginning of this list, since the terrestrial water cycles (at the catchment, regional, or global scales) begin with rainfall and runoff processes.
2. Line 28. What is the difference between "hydrological catchments" and "river catchments"? If they are the same, please just use "catchments" after the definition upfront.
3. Line 74, "abstracts". Please use another word if possible to avoid confusion. For example, "abstraction" could mean "rainfall infiltration and/o retention" to some hydrologists.
4 . Line 457-460. It would be better to move this example upfront in the introduction, perhaps along with another couple of classic ones. This way, the readers will have a better sense of what are "boundary conditions" and then the authors intend to achieve. I did not get this puzzle resolved until reading to this point.

Citation: https://doi.org/10.5194/egusphere-2023-1662-RC1
- AC4: 'Reply on RC1', Barnaby Dobson, 23 Nov 2023
  
  Dear Prof Li,
  
  Thankyou for the kind remarks. We completely agree with your request for more clarifications in the terminology to make the paper understandable to a wider audience. We will make these changes and review the paper for other areas where clarity could be added when we revise the manuscript after the open discussion.
  
  Best,
  Barney
  
  Citation: https://doi.org/10.5194/egusphere-2023-1662-AC4
RC2:
'Comment on egusphere-2023-1662', Anonymous Referee #2, 26 Mar 2024

The authors present an open-source Python tool to make integrated model of the water cycle, including water quantity and quality. They start with a review of the state of the art, then present the conceptual structure of the model, very briefly introduce a demonstration and then focus on discussing the need for the tool. Finally they present some conclusions.
The work that the authors present is interesting and, in my opinion, within the scope of GMD. Their tool being a library, may serve to others researchers to adapt it to their needs, either using the already developed classes, either by modifying the code. I think the paper may deserved to be published in GMD, however I have a major concern about the paper structure.
Section 2 presents a conceptualization of the model, which is not evident to follow. Such a conceptualization is important, because it allows to extend the model in an easy way and to represent similar elements with a minimal amount of code. However, conceptualizations are difficult to grasp, so I would suggest that the authors combine section 3 (which currently is not very illustrative, probably because the link provided is not working for me -I get a 404 error-) with section 2 in such a way that they first explain a canonical case in water management, that anyone could understand, and from there, they present the conceptualization.
In this way, the reader would be able to put "some meat" in the concepts presented, making it easier for the reader to apply the WSIMOD software to their own problems. Without such a change, the presentation may not be clear enough to ensure an understanding.
Moreover, after having checked the paper where the source code was published, I am also missing some more technical details. They may be better suited to supplementary material, but I believe that an explanation of the technical details and equations behind the model elements would be interesting. Not only to have all that information in a citable location, but also to have it all concentrated in one place, so that when problems arise, the users of the library may try to troubleshoot problems with the equations looking at just one section of the paper. (This information may be somewhere in the documentation, but I have not been able to find it).
* Minor comments

+ Line 19/20: Improve use of verbs.

+ Line 201: "our" seems to be out of place.

+ Line 354: adjudged may not be the term the authors intended to use

Citation: https://doi.org/10.5194/egusphere-2023-1662-RC2
- AC5: 'Reply on RC2', Barnaby Dobson, 26 Mar 2024
  
  Dear Reviewer,
  Thankyou so much for your review and encouraging comments. We will address this review alongside the other review in one large revision.
  Though I will just briefly highlight that since the paper was originally submitted (rather a while ago!) the documentation and code is now hosted by Imperial College London:
  https://github.com/ImperialCollegeLondon/wsi
  https://imperialcollegelondon.github.io/wsi/
  
  We will of course update the hyperlinks appropriately in this revision.
  
  Citation: https://doi.org/10.5194/egusphere-2023-1662-AC5

Barnaby Dobson, Leyang Liu, and Ana Mijic

Viewed

Total article views: 591 (including HTML, PDF, and XML)

HTML	PDF	XML	Total	BibTeX	EndNote
343	210	38	591	19	20

HTML: 343
PDF: 210
XML: 38
Total: 591
BibTeX: 19
EndNote: 20

Views and downloads (calculated since 13 Oct 2023)

Month	HTML	PDF	XML	Total
Oct 2023	120	70	9	199
Nov 2023	96	25	15	136
Dec 2023	17	14	3	34
Jan 2024	24	31	1	56
Feb 2024	21	38	3	62
Mar 2024	35	24	3	62
Apr 2024	30	8	4	42

Cumulative views and downloads (calculated since 13 Oct 2023)

Month	HTML	PDF	XML	Total
Oct 2023	120	70	9	199
Nov 2023	96	25	15	136
Dec 2023	17	14	3	34
Jan 2024	24	31	1	56
Feb 2024	21	38	3	62
Mar 2024	35	24	3	62
Apr 2024	30	8	4	42

Viewed (geographical distribution)

Total article views: 578 (including HTML, PDF, and XML) Thereof 578 with geography defined and 0 with unknown origin.

Country	#	Views	%

Latest update: 26 Apr 2024

Short summary

Water management is challenging when models don't capture the entire water cycle. We propose using integrated models facilitates management and improves understanding. Thus, we introduce a software tool designed for this task. We discuss its foundation, how it simulates water system components and their interactions, and its customization. We provide a flexible way to represent water systems, and we hope it will inspire more research and practical applications for sustainable water management.


Total:	0
HTML:	0
PDF:	0
XML:	0