diff --git a/doc/paper/2023/simhydro/paper.odt b/doc/paper/2023/simhydro/paper.odt index ddef222bf1a384edff859db1001e624e6cc9187a..befb89f0c266d453ab184ac09704387861df073d 100644 Binary files a/doc/paper/2023/simhydro/paper.odt and b/doc/paper/2023/simhydro/paper.odt differ diff --git a/doc/paper/2023/simhydro/paper.txt b/doc/paper/2023/simhydro/paper.txt index 3de63619d42c6195f163c033ed6e139d6542702c..43e659e5491d8bc1bd8d258a52f7c46e3e133f90 100644 --- a/doc/paper/2023/simhydro/paper.txt +++ b/doc/paper/2023/simhydro/paper.txt @@ -10,7 +10,11 @@ In numerical river simulation, one-dimensional models are commonly used to study 1. introduction Numerous tools are available to simulate river flow. Among them, one-dimensional (1D) numerical hydraulic models have the advantage of being accurate while being inexpensive in terms of computation time, making it possible to simulate long rivers over very long timescales. A lot of 1D numerical solvers for river hydraulics are available, including HEC-RAS2, Mike 113 and Mascaret4 for example. However, in order to investigate specific research issues it is essential to have the ability to edit the source code of numeric solvers and to have an ergonomic Graphical User Interace (GUI). Most of the widespread 1D modeling tools are either written with a proprietary source code (such as HEC-RAS and Mike 11) or are research tools with irregularly maintained GUI. On its side, INRAE has been developing two 1D solvers for over 40 years: Mage5 and RubarBE6. In parallel, a GUI named PAMHyR has been developed to enable modelers to build river models, parameterize calculations, launch Mage [5] and RubarBE solvers and post-process the results [3]. - PAMHyR, developed in Java since 1998, now suffers from complexity due to highly specific interface, as well as a significant technological debt [4]: old external library no longer maintained, numerous modifications by multiple developers over short periods of time, with no vision of long-term maintainability. What's more, the software is only in French and the code is closed (the sources are not available), which is a hindrance to the notoriety of the software as well as to the vitality of development. No significant changes have been made in the application since 2016, even if PAMHyR is still often used for river modeling [4]. + PAMHyR, developed in Java since the end of 90s (originally named X-NT), it was written with the following constraints in mind: + • Multi-platform Windows, Unix-like, + • no dependence on an external graphics library with a paid license for user, + • generate as much code as possible from a UML diagram. +Now, PAMHyR suffers from complexity due to highly specific interface, as well as a significant technological debt [4]: old external library no longer maintained, over dated project architecture, and numerous modifications by multiple developers (and internship) over short periods of time, with no vision of long-term maintainability. What's more, the software is only in French and the code is closed (the sources are not available), which is a hindrance to the notoriety of the software as well as to the vitality of development. In addition, no significant changes have been made in the application since 2016, even if PAMHyR is still often used for river modeling [4]. INRAE needs a new tool to keep up with today’s technologies and with the development of its numerical solvers. In this paper we introduce the current work on the new graphical user interface Pamhyr2. 2. Objective 2.1 History and need @@ -22,9 +26,9 @@ PAMHyR is available for two solvers, with two different types of studies: Mage a 2.2 Technical choices From a technical point of view, choices were made on the basis of the above-mentioned objectives (modernity, maintainability, multiplatform, multilingual, user-friendliness, flexibility), as well as: the ease of learning the technology to facilitate contribution to the software, the popularity of the technology in the scientific community and the interoperability of this technology. - We chose Python7 as our programming language. It is a popular language in the scientific world, but also in many other fields, with lot of very active software libraries to facilitate development. What's more, it's a simple and interpreted language, often recommended for beginners, and practiced by beginners and experienced developers. In addition, there is the PyQT8 software library that lets you use the Qt9 GUI library, which is ideal for this project. It is very popular and active, and available on many platforms (GNU/Linux, Windows, MacOS, Unix, BSD, Android, iOS). Qt also includes a number of tools for translating interfaces into different languages. For graphics and visualization, the choice fell on MatPlotLib10, which is very popular in the scientific community and can be used to draw a wide variety of graphics. For saving studies, the choice was made to use SQLite11, unlike the previous version which used a text file formatted in XML. The advantages of a SQLite database, in addition to being supplied with Python, include ease of use, interoperability, fast, formal structuring by table and consistency checking between tables. We have chosen to version the database to allow it to evolve with the software, now it is possible to add columns to tables or make other minor modifications to the database without breaking the compatibility of studies from previous versions. However, PAMHyR and Pamhyr2 study files are incompatible, and old studies have to be recreated for this version. + We chose Python7 as our programming language. It is a popular language in the scientific world, but also in many other fields, with lot of very active software libraries. What's more, it's a simple and interpreted language, often recommended for beginners, and practiced by beginners and experienced developers. In addition, there is the PyQT8 software library that lets you use the Qt9 GUI library, which is ideal for this project. It is very popular and active, and available on many platforms (GNU/Linux, Windows, MacOS, Unix, BSD, Android, iOS). Qt also includes a number of tools for translating interfaces into different languages. Here we use the community version of Qt, with no paid features. For graphics and visualization, the choice fell on MatPlotLib10, which is very popular in the scientific community and can be used to draw a wide variety of graphics. For saving studies, the choice was made to use SQLite11, unlike the previous version which used a text file formatted in XML. The advantages of a SQLite database, in addition to being supplied with Python, include ease of use, interoperability, fast, formal structuring by table and consistency checking between tables. We have chosen to version the database to allow it to evolve with the software, now it is possible to add columns to tables or make other minor modifications to the database without breaking the compatibility of studies from previous versions. However, PAMHyR and Pamhyr2 study files are incompatible, and old studies have to be recreated for this version. - This new version of PAMHyR remains closely linked to the Mage solver with which it is supplied. But the ambition of flexibility and generalization gives us the opportunity to develop an interface that can be adapted to other solvers. There can be two solutions for using a solver with Pamhyr2: either the solver adapt to Pamhyr2, or Pamhyr2 adapt to the solver. So Pamhyr2 must integrate a generic output containing the study data that can be used by other solvers, which will be launched via an external executable, and then a generic result input that must be supplied by the solver. In addition, Pamhyr2 must be able to handle the execution and reading of results for specific solvers, and the addition of a solver to PAMHYR must be reasonably easy for the solver developer. We have opted for a free (as in freedom/liberty) and open source software (FOSS) [6] license the GPLv312, which guarantees freedom to access, study, modify, redistribute and share. In addition, it guarantees that Pamhyr2's code will remain free and will not be able to add any closed-source modifications. However, it will still be possible to use closed-source solvers, because solver is not a part of Pamhyr2. + This new version of PAMHyR remains closely linked to the Mage solver with which it is supplied. But the ambition of flexibility and generalization gives us the opportunity to develop an interface that can be adapted to other solvers. There can be two solutions for using a solver with Pamhyr2: either the solver adapt to Pamhyr2, or Pamhyr2 adapt to the solver. So Pamhyr2 must integrate a generic output containing the study data that can be used by other solvers, which will be launched via an external executable, and then a generic result input that must be supplied by the solver. In addition, Pamhyr2 must be able to handle the execution and reading of results for specific solvers, and the addition of a solver to PAMHYR must be reasonably easy for the solver developer. We have opted for a free (as in freedom/liberty) and open source software (FOSS) [6] licence the GPLv312, which guarantees freedom to access, study, modify, redistribute and share. In addition, it guarantees that Pamhyr2's code will remain free and will not be able to add any closed-source modifications. However, it will still be possible to use closed-source solvers, because solver is not a part of Pamhyr2. 3. DEVELOPMENTS 3.1 New version of PAMHYR Pamhyr2 currently features the following interfaces: Editing of river network, geometry, boundary conditions, lateral contribution, friction, initial conditions, solver numerical parameters, as well as the interface for launching a solver and displaying hydraulic and sediment results. @@ -66,7 +70,7 @@ The initial conditions (Figure 5) are also linked to the reach, corresponding to Figure 5: Initial conditions edition window for the Saar study and the Saar reach. Initial conditions initialized with minimal height of 3 meter and a constant flow rate of 100 m3/s. 3.1.6 Running a solver -Solver numerical parameters are defined using a key/value table specific to each type of solver known to Pamhyr2. You can select and run the desired solver from the list of configured solvers. Then a window appears with a text area where you can follow the progress of file export and solver output in (Figure 6 zone 3). You can also pause, stop or restart the solver using buttons (zone 1). Once the simulation has finished, you can open a solver trace file, and if the simulation has finished correctly, you can open the results using the “results†button (zone 2). +Solver numerical parameters are defined using a key/value table specific to each type of solver known to Pamhyr2. You can select and run the desired solver from the list of configured solvers. Then a window appears with a text area where you can follow the progress of file export and solver output in Figure 6 (zone 3). You can also pause, stop or restart the solver using buttons (zone 1). Once the simulation has finished, you can open a solver trace file, and if the simulation has finished correctly, you can open the results using the “results†button (zone 2). @@ -105,9 +109,9 @@ Functionalities that may or may not have been present in the old PAMHYR, enablin • SQLite, because it's easy to use and the library is compatible with most programming languages, • HDF513, a hierarchical file format widely used in scientific circles and compatible with many programming languages. - As the project progresses, it becomes more and more complicated to test all the functionalities by hand. A suite of tests and unit tests is needed to prevent regression bugs and ensure that the code remains maintainable. For the moment, no test have been defined. Unit tests will have to be developed on the model and each sub-module will have to include tests, but higher-level functionalities will also have to be tested, such as the recording and playback of a complete study. It will be difficult to test the graphical par automatically, so tests will continue to be carried out manually. + As the project progresses, it becomes more and more complicated to test all the functionalities by hand. A suite of tests and unit tests is needed to prevent regression bugs and ensure that the code remains maintainable. For the moment, no test have been defined. Unit tests will have to be developed on the model and each module will have to include tests, but higher-level functionalities will also have to be tested, such as the recording and playback of a complete study. It will be difficult to test the graphical par automatically, so tests will continue to be carried out manually. - Full documentation must also be provided to give users an overview of the features offered by Pamhyr2. This documentation must include descriptions of the configuration options, as well as explanations and examples of how to use each feature. In addition, this documentation must include a section for contributors and developers, with a technical presentation of the application, as well as a presentation of the translation, development and debugging tools available. + Full documentation must also be provided to give users an overview of the features offered by Pamhyr2. This documentation must include descriptions of the configuration options, as well as explanations and examples of how to use each feature. In addition, this documentation must include a section for contributors and developers, with a technical presentation of the application, as well as a presentation of the translation, development, and debugging tools available. The French translation of Pamhyr2 is still incomplete, and work is needed on translating technical terms. For translations into other languages, we hope that external contributors will take on this work, but no languages other than English and French are currently planned from the development team.