You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Update SRS with more details and applying the MoSCoW model to prioritize what we want to have for our first version.
---------
Co-authored-by: langevin-usgs <[email protected]>
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
24
28
@@ -29,92 +33,53 @@ called *the product* or flopy4.
29
33
30
34
### Product scope
31
35
32
-
flopy4 will be a software product to pre- and post-Process MODFLOW-based
33
-
model input and output.
36
+
flopy4 will be a software product to pre- and post-process MODFLOW-based model input and output.
37
+
Pre-processing will be limited to preparing model input datasets, mesh generation, and model input manipulation capabilities.
38
+
Post-processing will be limited to reading model output into internal data formats that can be used by the product, plotting utilities, and rudimentary analysis capabilities.
39
+
For specific use cases, model input and output data will be processed by the product into formats that can be analyzed in other libraries.
34
40
35
-
Pre-processing will be limited to preparing model input datasets.
41
+
The product will be able to run MODFLOW simulations.
36
42
37
-
Post-processing will be limited to reading model output into internal data formats
38
-
that can be used by the product.
43
+
The product can load existing model input datasets that were not necessarily created by the product, but conform to MODFLOW input and output specifications.
39
44
40
-
For specific use cases, model input and output data will be processed by the
41
-
product into formats that can be analyzed in other libraries.
42
-
43
-
The product will also be able to run MODFLOW simulations.
44
-
45
-
The product can load existing model input datasets that were not necessarily
46
-
created by the product but conform to MODFLOW input and output specifications.
47
-
48
-
flopy4 will replace the MODFLOW 6 targeted capabilities of the current FloPy 3.
49
-
50
-
flopy4 will also replace the following capabilities of FloPy 3:
51
-
* PEST (?)
52
-
* capability 2 (discuss)
45
+
flopy4 will replace the MODFLOW 6 targeted capabilities of the current FloPy 3 library.
53
46
54
47
### Product value
55
48
56
49
The product will allow defining reproducible, versionable Python workflows for
57
-
MODFLOW modeling applications.
58
-
59
-
The product will wrap MODFLOW and other programs and provide a Pythonic interface
60
-
to their functionality and input and output files.
61
-
62
-
flopy4 is essential to the MODFLOW development process for testing existing and
63
-
newly developed functionality.
64
-
65
-
### Intended audience:
66
-
67
-
Hydrologic scientists, engineers, and students who are familiar with the Python
68
-
ecosystem and want to use MODFLOW for their hydrologic applications. The other
69
-
key audience is the team of MODFLOW software developers.
50
+
MODFLOW modeling applications.
70
51
71
-
### Intended use:
52
+
The product will wrap MODFLOW and other programs and provide a Pythonic interface to their functionality and input and output files.
72
53
73
-
The product should be available on the major operating systems
74
-
(Windows, Linux, MacOS) and hardware ranging from laptops to HPC systems.
54
+
flopy4 is essential to the MODFLOW development process for testing existing and newly developed functionality.
75
55
76
-
The product will be used through Python scripts and Jupyter notebooks.
56
+
flopy4 will be compatible with the definition files (DFNs) that come with MODFLOW 6, and will thus always be up-to-date with the latest MODFLOW 6 capabilities.
77
57
78
-
The product can be relied upon as a core component by other libraries and
79
-
tools that offer more advanced or domain specific or application specific
80
-
functionality.
58
+
### Intended audience
81
59
82
-
#### Use cases
60
+
Hydrologic scientists, engineers, and students who are familiar with the Python ecosystem and want to use MODFLOW for their hydrologic applications.
61
+
The other key audience is the team of MODFLOW software developers.
83
62
84
-
* A hydrologist needs to determine an optimal pumping rate for a well field...
63
+
### Intended use
85
64
86
-
* A student wants to simulate salt water intrusion in a coastal aquifer and
87
-
visualize results...
65
+
The product should be available on the major operating systems (Windows, Linux, MacOS) and hardware ranging from laptops to HPC systems.
66
+
The product will be used through Python scripts, Jupyter notebooks, pytest, and ipython.
88
67
89
-
* A professor is teaching a groundwater modeling class...
68
+
The product can be relied upon as a core component by other libraries and tools that offer more advanced, domain specific, or application specific functionality.
90
69
91
-
* A hydrologic institute maintains their own suite of advanced pre- and
92
-
post-processing utilities that can rely on flopy4 as a component for its
93
-
core capabilities...
70
+
### Use cases
94
71
95
-
* A MODFLOW developer is debugging an issue in the UZF package and wants to
96
-
create a complicated test with many cells and stress periods...
72
+
- A hydrologist needs to determine an optimal pumping rate for a well field...
97
73
98
-
* A MODFLOW developer is setting up a worked example to demonstrate how to
99
-
use a new feature...
74
+
- A student wants to simulate salt water intrusion in a coastal aquifer and visualize results...
100
75
101
-
## System requirements and functional requirements
102
-
tbd
103
-
104
-
## External interface requirements
105
-
tbd
76
+
- A professor is teaching a groundwater modeling class...
106
77
107
-
## Non-functional requirements (NRFs)
108
-
tbd
78
+
- A hydrologic institute maintains their own suite of advanced pre- and post-processing utilities that can rely on flopy4 as a component for its core capabilities...
109
79
110
-
**Maintainability**
111
-
112
-
flopy4 should maintain a separation of concerns with respect to hydrology and
113
-
software engineering. The hydrologic modeler should not be concerned with the
114
-
technical details of flopy4's internal data storage or parallel processing
115
-
implementation, for example, and a software engineer should be able to work
116
-
on the code without detailed knowledge on complex hydrologic concepts.
80
+
- A MODFLOW developer is debugging an issue in the UZF package and wants to create a complicated test with many cells and stress periods...
117
81
82
+
- A MODFLOW developer is setting up a worked example to demonstrate how to use a new feature...
118
83
119
84
## Motivation
120
85
@@ -129,63 +94,106 @@ in several areas:
129
94
130
95
### Consistency
131
96
132
-
The `flopy.mf6` module departs considerably from the older `flopy.modflow`
133
-
module. This requires more memorization (or more R'ing TFM) for users and
134
-
developers alike, and makes maintenance harder.
135
-
97
+
The `flopy.mf6` module departs considerably from the older `flopy.modflow` module.
98
+
This requires more memorization (or more R'ing TFM) for users and developers alike, and makes maintenance harder.
136
99
Both modules are strongly coupled to the relevant programs' input format.
137
100
138
-
We would like a consistent core framework for any modeling program, which
139
-
can be applied to MODFLOW 6, older MODFLOW programs, and other hydrologic
140
-
simulators. The framework should be agnostic to the IO format used by any
141
-
particular program.
101
+
We would like a consistent core framework for any modeling program, which can be applied to MODFLOW 6, older MODFLOW programs, and other hydrologic simulators.
102
+
The framework should be agnostic to the IO format used by any particular program.
142
103
143
104
### Maintenance
144
105
145
-
The `flopy.mf6` module is large and developers have struggled to maintain
146
-
it. Deep abstraction in the object model raises barriers to comprehension
147
-
and error messages are not easy to trace back to the offending component.
106
+
The `flopy.mf6` module is large and developers have struggled to maintain it.
107
+
Deep abstraction in the object model raises barriers to comprehension and error messages are not easy to trace back to the offending component.
148
108
Debugging is also difficult.
149
109
150
110
### Introspection
151
111
152
-
Component classes reproduce their input specification verbatim. This is
153
-
redundant and yet not particularly useful or Pythonic; more informative
154
-
would be a format-agnostic specification in terms of Python primitives,
155
-
containers, and classes, which can be translated into any given format
156
-
upon request. This allows flexibility to translate DFN specifications
157
-
to a different format, e.g. TOML, YAML or JSON.
112
+
Component classes reproduce their input specification verbatim.
113
+
This is redundant and yet not particularly useful or pythonic;
114
+
more informative would be a format-agnostic specification in terms of Python primitives, containers, and classes, which can be translated into any given format upon request.
115
+
This allows flexibility to translate DFN specifications to a different format, e.g. TOML, YAML or JSON.
158
116
159
-
Component classes also provide a data access layer via `.get_data()` and
160
-
`set_data()`— it would be simpler just to get/set the attributes
161
-
normally and intercept these behind the scenes for any magic necessary.
117
+
Component classes also provide a data access layer via `.get_data()` and `set_data()`— it would be simpler just to get/set the attributes normally and intercept these behind the scenes for any magic necessary.
162
118
163
119
### Performance
164
120
165
121
TODO: describe current issues
166
122
167
123
### Invariants
168
124
169
-
FloPy 3 has a "check" mechanism for validating simulation configurations,
170
-
but this must be run manually by the user, and no straightforward method
171
-
for extension is available.
125
+
FloPy 3 has a "check" mechanism for validating simulation configurations, but this must be run manually by the user, and no straightforward method for extension is available.
126
+
This allows simulations to be initialized in an invalid state, which may go unnoticed until runtime, producing less than informative errors from the modeling program.
127
+
The most obvious example is that grid dimensions can be changed with no warning to the user, and no attempt to coerce package array data to the new shape.
128
+
We would like automatic enforcement of invariants whenever a simulation changes.
172
129
173
-
This allows simulations to be initialized in an invalid state, which may
174
-
go unnoticed until runtime, producing less than informative errors from
175
-
the modeling program.
130
+
### Maintainability
176
131
177
-
The most obvious example is that grid dimensions can be changed with no warning to the user, and no attempt to coerce package array data to the
178
-
new shape.
179
-
180
-
We would like automatic enforcement of invariants whenever a simulation
181
-
changes.
132
+
flopy4 should maintain a separation of concerns with respect to hydrology and software engineering.
133
+
The hydrologic modeler should not be concerned with the technical details of flopy4's internal data storage or parallel processing implementation,
134
+
for example, and a software engineer should be able to work on the code without detailed knowledge on complex hydrologic concepts.
182
135
183
136
## Goals
184
137
185
-
With the above in mind, we want the next version of FloPy to
138
+
With the above in mind, we want the next version of FloPy to:
186
139
187
140
- preserve existing `flopy.mf6` functionality
188
-
- be consistent, user-friendly and Pythonic
141
+
- be consistent, user-friendly and pythonic
189
142
- be easy to read, debug, diagnose and test
190
143
- be memory-efficient and provide fast IO
191
144
- impose a minimal maintenance burden
145
+
146
+
## System requirements and functional requirements
147
+
148
+
The requirements below are written up through interviews with stakeholders and internal research of the flopy code base.
149
+
150
+
The requirements are categorized through the [MoSCoW method](https://en.wikipedia.org/wiki/MoSCoW_method), prioritizing which requirements Must, Should, Could, and Won't go into the first iteration of the flopy 4 project.
151
+
152
+
### Functional requirements
153
+
154
+
| ID | Description | MoSCoW |
155
+
| ------- | ----------- | ------ |
156
+
| FUNC-1 | flopy4 must be able to read and write MODFLOW 6 input files and read MODFLOW 6 output files. | M |
157
+
| FUNC-2 | flopy4 must be able to run MODFLOW 6 simulations and report back on the run status. | M |
158
+
| FUNC-3 | flopy4 must work with multiple versions of MODFLOW 6, based on the DFN files. And it must support all packages that come with that version of MODFLOW 6. | M |
159
+
| FUNC-4 | The product lets the user define a model domain, including grid dimensions, cell sizes, and boundary conditions. | M |
160
+
| FUNC-5 | flopy4 can create grid definitions in different formats: structured (DIS), vertex (DISV), unstructured (DISU). And is open for expansion of new grid definitions. | M |
161
+
| FUNC-6 | flopy4 can create MODFLOW models that support parallel processing. It can pre-process models by splitting them up, ready for parallel computation. | M |
162
+
| FUNC-7 | The product contains functions to plot model output and gives the user configurable or extendable options for customization. | M |
163
+
| FUNC-8 | The product contains functions to plot model input and gives the user configurable or extendable options for customization. | M |
164
+
| FUNC-9 | The product can export its internal data model to different types of file formats, such as NetCDF, VTK, and geospatial standards. | M |
165
+
| FUNC-10 | Extensive and optional validation on the final input model can be used to ensure that the model is free from detectable errors and to warn the user of potential errors before running the simulation. | S |
166
+
| FUNC-11 | The validation can be extended by the user to include custom checks. | C |
167
+
| FUNC-12 | Instantiation of packages and models should work in an intuitive way that does not depend on the specific order of function calls. E.g., packages can be created without creating a simulation or model first. | M |
168
+
| FUNC-13 | Functionality is in place to set up example simulations with predefined setup combinations of models and packages already configured. | C |
169
+
| FUNC-14 | Flopy is a non-intrusive package when it comes to reading, writing, and running the model. When writing out a model that was read, the simulation output must give the exact same results. | C |
170
+
171
+
### External interface requirements
172
+
173
+
| ID | Description | MoSCoW |
174
+
| ------- | ----------- | ------ |
175
+
| API-1 | flopy4 should give the opportunity for external libraries to extend its capabilities by providing a plugin system. This can be useful for new plotting mechanisms, file export formats, or custom input file formats that can be converted to MODFLOW data. | C |
176
+
| API-2 | New DFN files are compatible with flopy4, and the product should be able to generate a definition of the packages that are applicable to that version of MODFLOW 6. | M |
177
+
| API-3 | The product strives for a consistency in its public API between MODFLOW 6 and older MODFLOW packages. | S |
178
+
| API-4 | The product has programmatic access to example models, to make it quick for the user to run an example model, or to alter the examples to their liking. | C |
179
+
| API-5 | Input parameters have clear units to avoid confusion. E.g., using SI units only, or by providing usage of a python units package. | C |
180
+
| API-6 | The product has a unified understanding of date and time. | M |
181
+
| API-7 | The user is aided in their development process by providing python type hints directly from the API with accompanying documentation on all the input parameters. | M |
182
+
183
+
### Non-functional requirements
184
+
185
+
| ID | Description | MoSCoW |
186
+
| ------- | ----------- | ------ |
187
+
| NFR-1 | The product must be able to create large models that are larger than the available memory on the user's machine. | M |
188
+
| NFR-2 | The product should be able to create an example model of the United States with a **?1 km?** grid resolution. | ? |
189
+
| NFR-3 | Clear and informative error messages should be provided to the user when an error occurs, also during model input validation. | M |
190
+
| NFR-4 | The user documentation makes a clear distinction in user public and internal API. | M |
191
+
| NFR-5 | The user documentation provides a complete overview of the definition file specification. | M |
192
+
193
+
### System requirements
194
+
195
+
| ID | Description | MoSCoW |
196
+
| ------- | ----------- | ------ |
197
+
| SYS-1 | flopy4 must be able to run within a python environment supporting versions that comply with scientific-python.org guidelines: <https://scientific-python.org/specs/spec-0000/>. This is due to its dependency on the Numpy, Matplotlib, and XArray libraries, and flopy4 should not be conflicting with user installed libraries. | M |
198
+
| SYS-2 | The product must be able to run on the following operating systems: Windows, Linux, MacOS. | M |
199
+
| SYS-3 | The product must be distributed via the Python Package Index (PyPI) and be installable via pip. Additionally, the product must be installable via conda-forge. | M |
0 commit comments