An open-source package with interactive Jupyter Notebooks to enhance the accessibility of reservoir operations simulation and optimisation

In this paper we present the interactive Reservoir Operations Notebooks and Software (iRONS) toolbox for reservoir modelling and optimisation. The toolbox is meant to serve the research and professional community in hydrology and water resource management and contribute to bridge the gaps between them. iRONS is composed of a package of Python core functions and a set of interactive Jupyter Notebooks. Core functions implement typical reservoir modelling tasks and the interactive Jupyter Notebooks illustrate, with practical examples, the key functionalities of iRONS. We describe our development philosophy, the key features of iRONS, and report some results of evaluating the effectiveness of interactive Jupyter Notebooks for training and knowledge transfer. The paper may be of interest also beyond the water resources management field, as an example of how Jupyter Notebooks and interactive visualisation help improving the documentation and sharing of opensource code and the communication of underpinning methodologies.

• Funding Source: Development was partially supported by an EPSRC "Living with Environmental Uncertainty Fellowship" on "Robust and transparent planning and operation of water resource infrastructure" [EP/R007330/1].

Introduction
Mathematical models of reservoirs' operations can be useful computational tools to support reservoir development or re-operation studies. Such modelling tools are especially relevant nowadays given the renewed interest in dam construction for hydropower development (Zarfl et al., 2015) and in finding more environmental-friendly operations of existing dams (e.g., Poff and Schmidt (2016); Chen and Olden (2017)). In hydrology, reservoir modelling has attracted increasing interest as one of the key steps to improve predictions of large-scale hydrological models in human-impacted river basins (Rougé et al., 2021, Yassin et al., 2019, Dang et al., 2020. Despite an ever growing scientific literature about reservoirs operation modelling and optimisation (see e.g. reviews by Labadie (2004), Ahmad et al. (2014) and Dobson et al. (2019)) the uptake of these methods by practitioners is still very limited (Brown et al., 2015, Pianosi et al., 2020a, as is the inclusion of reservoir simulation routines -set aside optimisation ones -into large-scale hydrological models (and most recent attempts are somehow disconnected from the scientific literature on reservoir operation optimisation mentioned above; a notable exception being Turner and Galelli (2016)). We think that the availability of simple-to-use software for reservoir operations simulation and optimisation may help close these gaps. We also claim that this software should have some key characteristics: it should be modular and minimal; and it should be open and accessible.
By modularity we intend that basic tasks (such as the generation of reservoir inflow time series, the determination of optimal releases from current storage or other information, etc.) should be implemented in separate functions so to maximise the possibility for users to re-apply them in different contexts ( Figure 1). This helps finding a coherent approach to tasks that, despite having different hydrological (e.g. short-term forecasting vs long-term prediction) or practical (day-to-day operations vs long-term planning) meaning, share a common mathematical formulation. It also facilitates the integration with other toolboxes already available for specialised tasks (e.g. optimization algorithms) so to avoid duplication of efforts whenever possible. Last, modularity enables the users to approach the software in different ways: either by plugging their tools (e.g. demand models) into the software, or by plugging-out of the software the specific components (e.g. the reservoir mass balance function or a specific reservoir operating rule) for integration into their tools (e.g. large-scale hydrological models). Figure 1 Modular structure of the approach used in iRONS to implement the optimisation of reservoir operation simulation and optimisation. Individual tasks can be performed according to different models or methods; the Figure highlights as an example some of those currently implemented in iRONS, integrated from other Python packages, or to be developed in future releases.
By openness we intend that, firstly, the code must be open-source, so to enable users to scrutinise its functioning and set the ground for the reproducibility and re-usability of its outputs. The lack of reproducibility of many hydrological and water resources modelling studies have been a topic of growing concern (Stagge et al., 2019, Hutton et al., 2016. Reproducibility is important both in an academic setting, to help knowledge sharing and accumulation, and in a practical setting, where transparency in decision making tools is required for different purposes (Badham et al., 2019) such as internal assurance process, regulators' approval, etc. However, sharing open-source code is not sufficient without also providing information for users to understand what the code does and to check whether it does it correctly when applied to other datasets or case studies. Modelling must be understandable, easy, transparent and even fun (Loucks and van Beek, 2017). This is what we mean by accessibility, which ideally should encompass users with diverse skills and level of modelling expertise.
A huge opportunity to this end comes from increasingly powerful tools to develop rich and interactive documentation in an efficient way, such as R Markdown or Jupyter Notebooks. These are literate programming environments that combine executable code, rich media, computational output and explanatory text in a single document. Through the Notebooks, users can execute the code, visualise the results, modify the code and repeat, in a kind of iterative conversation (Perkel, 2018). The result is a computational narrative that builds stronger links between model, data and results (Perez andGranger, 2007, Kluyver et al., 2016). Jupyter Notebooks have been proposed as an effective approach to implement and enhance reproducible modelling (Choi et al., 2021). Moreover, Jupyter Notebooks can be run on the cloud by using online platforms, such as Binder (https://mybinder.org/), so that they are accessible by a web browser without requiring the installation of Python.
Another opportunity provided by Notebooks, in an enhancement to static documentation, is the possibility to include interactive visualization libraries such as Bqplot (https://bqplot.readthedocs.io/) and Plotly (https://plotly.com/) and implement reactive plots such as markers and intuitive elements such as sliders within the figures of a Jupyter Notebook. When the user interacts with one of these interactive plots or elements, for instance by mouse clicking or dragging, the information shown in the figure and other complementary figures is automatically updated. Interactive visualisation of modelling results is key to enhance the accessibility and value of model predictions, to facilitate the communication of results beyond traditional static documents, and ultimately to support complex decision-making problems (Woodruff et al., 2013). As water resource management becomes increasingly multi-dimensional and multi-objective, interactive visualisation has been proposed in particular to enable the exploration of tradeoffs between multiple objectives, e.g. via interactive multi-dimensional Pareto fronts and parallel coordinate plots (Kwakkel, 2017, Hadka et al., 2015, Kasprzyk et al., 2013, Yang et al., 2016, Matrosov et al., 2015, although their effectiveness may diminish with increasing number of dimensions (Parker et al., 2015). The use of more intuitive elements such as sliders or coloured 2D scatter plots may provide a more effective mechanism to communicate complex modelling concepts to a non-technical audience such as decision-makers and stakeholders within and outside water companies.
In this paper we present the interactive Reservoir Operation Notebooks and Software (iRONS), a Python toolbox that implements several functions for the simulation and optimisation of reservoir operations, and is based on the above principles of modularity, minimalism, openness and accessibility. The target users of iRONS are students, researchers and practitioners that need a simple to use, and yet rigorous, Python code for reservoir simulation and/or optimisation -be it for supporting shortterm operational decisions, long-term reservoir operation planning, or to simulate dammed river basins. Our paper may also be of interest for modellers and developers of research software beyond the reservoir operation application field, as an illustration of ways by which Jupyter Notebooks and interactive visualisation can contribute to improve the documentation and sharing of open-source code and the communication of underpinning methodologies. It also provides a demonstration of the potential of interactive Jupyter Notebooks for training and knowledge transfer from more to less specialised user groups. Given the ease with which interactive Jupyter Notebooks can be developed, they can potentially revolutionise the documentation and sharing of research software towards an unprecedented level of transparency for relatively low effort (at least for sufficiently 'parsimonious' models -i.e. models that can be run on a desktop computer or on a cloud server in a matter of seconds/minutes).
The reminder of the paper is organised as follows. In the next Section, we briefly present the structure and characteristics of the two key parts of iRONS: the software and the Notebooks. We then present the results of some evaluation experiments we ran with students and early-career researchers to evaluate the effectiveness of Jupyter Notebooks for knowledge transfer.

Structure, content and style
The interactive Reservoir Operations Notebooks and Software (iRONS) is organised into two parts: a suite of functions (the 'Software') implementing several tasks related to the simulation and optimisation of reservoir operations; and a set of Jupyter Notebooks (the 'Notebooks') that demonstrate key functionalities of the software through practical examples, and that can be run either locally or remotely via a web browser.

The Software
At the time of writing, the iRONS functions cover the following tasks ( Figure 1): generation of short and mid-term (days to weeks) and long-term (months) forecasts or projections of reservoir inflows and demands; simulation and multi-objective optimization of the reservoir operations; and interactive visualization of the reservoir performance, including trade-offs between different purposes and under uncertainty. The software can be used to simulate and/or support reservoir operations over the shortterm, i.e. to optimise the reservoir' release scheduling over the coming days/weeks, or in the longterm, i.e. through the optimisation and evaluation of the reservoir's operating policy (Dobson et al., 2019). Thanks to its modular structure, any of these components can be easily linked/integrated into other water resource system software, such as Pywr (Tomlinson et al., 2020).
Few different options are available for the shape of the operating policy, including a piece-wise linear function and a log-exponential function (Rougé et al., 2021, Proussevitch et al., 2013 -but more can be easily integrated. Optimisation of both (short-term) release scheduling and (long-term) operating policy is performed by linking iRONS to the Platypus Multi-Objective Evolutionary Algorithm (MOEA) (https://github.com/Project-Platypus/Platypus). In the former case the decision variables optimised by Platypus MOEA are the reservoir releases, whereas in the latter case the decision variables to be optimised are the parameters of the operating policy. The current version of iRONS also includes the python implementation of a lumped hydrological model, the rainfall-runoff HBV model (Bergström and Singh, 1995), which is used in several Notebooks to show the modelling chain from meteorological inputs to reservoir inflows. However, depending on the application, the user may want to instead import here a time series of inflow records or inflows generated elsewhere by a different model (Dal Molin et al., 2020).
While Python is an object-oriented language, iRONS uses a functional programming style instead which, in our opinion, requires lower coding skills to be read and (if needed) revised and which has been successfully applied by widely adopted toolboxes such as SAFE (Pianosi et al., 2020b). Moreover, whenever possible, the code is written in "math-like" style aiming to maximise readability, occasionally using less efficient but more legible coding options (for example, a for loop in place of vectorisation). Computational efficiency is regained by making the code compatible with the Numba just-in-time compiler (http://numba.pydata.org/; Lam et al. (2015); Marowka (2018)) so that "math-like" functions can still be used within computationally expensive tasks. An illustration of the concept is given in Figure 2. Figure 2. Example of different coding options for the task of transforming cumulative data (such as the ensemble seasonal precipitation forecast released by the European Centre for Medium-Range Weather Forecasts, ECMWF) into daily data (as used for reservoir daily mass balance equation). Using the just-in-time compiler Numba (option C) allows to mitigate the tradeoff between pursuing readability (option A) and speed of execution (option B).

The Notebooks
The Jupyter Notebooks are divided in two sections: 1) Knowledge Transfer Notebooks: a set of simple examples to demonstrate the value of simulation and optimisation tools for reservoir operations by application to 'proof-of-concept' systems. The Notebooks cover a range of concepts relevant to reservoir operation, such as: manual vs automatic calibration of rainfall-runoff models used to generate reservoir inflows; what-if analysis vs optimisation of reservoir releases; optimisation under conflicting objectives and under uncertainty; optimisation of release releases scheduling vs optimisation of an operating policy; different shapes of operating policies for different reservoir purposes such as domestic or irrigation supply, flood control, or hydropower production.
2) Implementation Notebooks: a set of workflow examples showing how to apply the iRONS functions to real-world data and problems, including: generating inflow forecasts through a rainfall-runoff model, including bias correcting weather forecasts; optimising release scheduling against an inflow scenario or a forecast ensemble; optimising an operating policy against time series of historical or synthetic inflows. These Notebooks are meant to serve as a 'learn-by-doing' alternative to a User manual and a starting point for the user's own application workflows (Pianosi et al. 2018).
The intended learning objective of the two types of notebooks and their key features are summarised in Table 1. Some examples of interactive visualisations included in the Knowledge Transfer Notebooks are given in Figure 3 Examples of interactive visualisations included in the Knowledge Transfer Notebooks.

Knowledge Transfer (KT) Notebooks Implementation Notebooks
Objective: familiarise non-specialists with key concepts of reservoir operations simulation and optimisation Objective: illustrate how to implement reservoir operations simulation and optimisation tasks using iRONs Key features: 1) Simplified case study 2) Only most salient pieces of code shown 3) Interactive visualisation to stimulate user engagement (for example, sliders to change variable values, such as weekly reservoir release scheduling, in order to 'beat' a specified performance target)

Key
features: 1) Real-world (or realistic) case studies 2) Full code shown and explained step by step 3) Interactive visualisation to enable increasingly in-depth exploration of the results (for example, click-drag interactions such as zoom, pan, select, or mouseover to display additional information about a specific datapoint)

Evaluation of interactive Jupyter Notebooks
To our knowledge, the efficacy of interactive Jupyter Notebooks for knowledge transfer has been claimed but never actually measured. Previous studies have looked at the efficacy of interactive visualisation in teaching settings, coming to mixed conclusions (Chou, 2003). For example, Chien and Chang (2012) and Akinlofa et al. (2013) both found that full interactions with visualisation tools was more effective for learning than watching (non-interactive) animations of videos. However, Pedra et al. (2015) showed that incorporating sophisticated interactivity features into lessons increased the interest of students, but this was not translated into better learning outcomes. In this section we present the results of some experiments we ran to measure the efficacy of our Knowledge Transfer (KT) Notebooks.
Specifically, we shared two of the Knowledge Transfer (KT) Notebooks available in iRONS (the one on "Calibration and evaluation of a rainfall-runoff model" and the one on "Recursive decisions and multiobjective optimisation") during online workshops or after online talks, and asked the participants to go through them at their pace. Before and after going through the KT Notebooks, participants filled in a questionnaire to measure their familiarity and understanding of the concepts covered by the KT Notebooks. By comparing responses before and after, we can thus assess whether their knowledge was increased by using the Notebooks. Overall, we ran one in-person and two online workshops for a total of 25 participants, and obtained responses by email from another 7 participants -consisting of 26 PhD students with diverse backgrounds (13 of them in Hydrology and Water Informatics, 6 in Agronomy, 5 in Biogeochemical flows and 2 in Fine Chemistry) and 6 master's degree students (all of them in Environmental Hydraulics). While this number of participants is limited, we think the results are nonetheless worth sharing, as is our assessment approach in the first place. Familiarity to a concept is self-assessed by the participants using a scale from 1 ("not confident") to 5 ("very confident"). Understanding of a concept is instead measured by the ability to give the correct answer to a close-ended question about that concept. The survey also includes direct questions to the participants about their opinion of our interactive Notebooks compared to other learning methods such as lecture slides, textbooks or online videos.
The majority of participants (72%) said that the interactive Notebooks are "better" than other learning methods that they had previously used and found very effective, about a third (28%) responded that they are "as good" and no participant said they are "worse". "Code explanations", "Interactivity" and "step-by-step structure" were among the reasons most commonly given for the better effectiveness for learning. Figure 4 reports the average increase in familiarity (x axis) against the increase in understanding (y axis) after engaging with the Notebooks. In general, the participants increased both their familiarity and understanding of the different technical concepts covered by the Notebooks, however there is not necessarily a clear relationship between the two. A possible explanation is that most participants felt considerably more confident initially about some of the concepts covered in the KT Notebooks than others. For instance, the initial average familiarity of the participants to the concepts of calibration and evaluation of hydrological models was 2.8 and 3.0 respectively, while for the concepts of reservoir' hedging rules and trade-off/Pareto front it was 1.6 and 2.0 respectively. As a consequence, the room for improvement in familiarity is smaller for some of the concepts and the increase of familiarity with respect to the increase of understanding does not correspond in the same way.
In the future we hope to be able to run more similar workshops with a more diverse range of users so to expand our understanding of the benefits -and limitations -of using Notebooks for model documentation and training.

Conclusions
In this paper we presented our interactive Reservoir Operations Notebooks and Software (iRONS) toolbox for reservoir modelling and optimisation. We illustrated our development philosophy and presented some results of our first attempts at evaluating the effectiveness of interactive Jupyter Notebooks for knowledge transfer. These results suggest that the characteristics of the Notebooks (literate programming and step-by-step structure) combined with visual interactivity do enhance learning and are appreciated by users.
Future work will move along two directions. First, we plan to expand the range of core functions of iRONS, for instance by implementing more operating policy functions, or simple demand simulation models. Second, we plan to further evaluate the efficacy of the interactive Jupyter Notebooks particularly as a knowledge transfer tool for practitioners -including water resource managers, consultants and regulators.