Skip to content

Commit 6588b09

Browse files
wpbonelliwpbonelli
authored
trim srs scope (#163)
trim the requirements to fit a minimum viable product. the full SRS can go in the new flopy4 development branch in the old flopy repo.
1 parent af12022 commit 6588b09

File tree

1 file changed

+24
-136
lines changed

1 file changed

+24
-136
lines changed

‎docs/dev/srs.md‎

Lines changed: 24 additions & 136 deletions
Original file line numberDiff line numberDiff line change
@@ -18,134 +18,28 @@
1818

1919
## Introduction
2020

21-
This is the Software Requirement Specifications (SRS) document for FloPy 4, also called *the product*.
21+
This is the Software Requirement Specifications (SRS) document for the FloPy 4 minimum viable product, called the MVP.
2222

2323
### Product scope
2424

25-
The product will be able to run MODFLOW simulations.
26-
27-
The product will support pre- and post-processing MODFLOW-based model input and output.
28-
29-
Pre-processing includes tasks like preparing model input and mesh generation.
30-
31-
Post-processing includes tasks like loading model output, plotting/visualiation, rudimentary statistical analysis, and interop with 3rd party formats/tools.
32-
25+
The MVP will be able to load, write, and run MODFLOW 6 simulations.
3326

3427
### Product value
3528

36-
The product allows reproducible, versionable Python workflows for MODFLOW modeling applications.
37-
38-
The product wraps MODFLOW and other programs and provide a Pythonic interface to their functionality and input and output files.
39-
40-
The product is essential to the MODFLOW development process for testing existing and newly developed functionality.
29+
The MVP delivers a basic set of functionality which will become the core of FloPy 4.
4130

4231
### Intended audience
4332

44-
The product is for hydrologic scientists, engineers, and students who are familiar with the Python ecosystem and want to use MODFLOW for their hydrologic applications.
45-
46-
Another key audience is the MODFLOW development team.
33+
The MVP is an internal product for use by the MODFLOW 6 and FloPy development team, as well as external collaborators.
4734

4835
### Intended use
4936

50-
The product should be compatible with all major operating systems and hardware ranging from laptops to HPC systems.
51-
52-
The product may be used in standalone scripts, inside applications, from interactive notebooks, and any other common Python runtime.
53-
54-
Other libraries and tools may build upon the product to offer more advanced, domain-specific, or application-specific functionality.
55-
56-
### Use cases
57-
58-
- A hydrologist needs to determine an optimal pumping rate for a well field...
59-
60-
- A student wants to simulate salt water intrusion in a coastal aquifer and visualize results...
61-
62-
- A professor is teaching a groundwater modeling class...
63-
64-
- 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...
65-
66-
- A MODFLOW developer is debugging an issue in the UZF package and wants to create a complicated test with many cells and stress periods...
37+
The MVP is a developer-facing library supporting the core functionality describe above.
6738

68-
- A MODFLOW developer is setting up a worked example to demonstrate how to use a new feature...
69-
70-
- A MODFLOW 6 developer writes a new component specification and corresponding module, generates a compatible Python interface, and uses it to write integration tests for the new component...
71-
72-
```mermaid
73-
C4Context
74-
title [Context] Product use cases
75-
76-
Person(hydrologist, "Hydrologist", "determines optimal pumping rate for well field")
77-
Person(student, "Student", "simulates salt water intrusion in coastal aquifer")
78-
Person(professor, "Professor", "teaches groundwater modeling course")
79-
Person(institution, "Lab/Institution", "maintains pre-/post-processing extensions")
80-
Person(developer, "Developer", "debugs issues, develops features/models")
81-
82-
System(flopy, "FloPy")
83-
System(mf6, "MODFLOW 6")
84-
85-
Rel(flopy, mf6, "wraps")
86-
Rel(hydrologist, flopy, "uses")
87-
Rel(student, flopy, "uses")
88-
Rel(professor, flopy, "uses")
89-
Rel(institution, flopy, "extends")
90-
Rel(developer, flopy, "develops")
91-
UpdateRelStyle(hydrologist, flopy, $lineColor="blue")
92-
UpdateRelStyle(student, flopy, $lineColor="blue")
93-
UpdateRelStyle(professor, flopy, $lineColor="blue")
94-
UpdateRelStyle(institution, flopy, $lineColor="blue", $offsetX="-190", $offsetY="10")
95-
UpdateRelStyle(developer, flopy, $lineColor="blue")
96-
97-
```
98-
99-
```mermaid
100-
C4Context
101-
title [Context] Code generation workflow
102-
103-
Boundary(mf6, "MODFLOW 6"){
104-
SystemDb(dfn, "Specification")
105-
}
106-
107-
Boundary(flopy, "FloPy") {
108-
Boundary(devs, "Developer APIs") {
109-
System(fpycore, "Core framework")
110-
System(fpycodegen, "Code generation")
111-
}
112-
Boundary(users, "User APIs") {
113-
System(fpymf6, "MF6 module")
114-
}
115-
Rel(fpymf6, fpycore, "imports")
116-
117-
Rel(fpycodegen, dfn, "inspects")
118-
Rel(fpycodegen, fpymf6, "generates")
119-
}
120-
121-
Person(dev, "Developer", "")
122-
Person(user, "User", "")
123-
124-
Rel(dev, dfn, "develops")
125-
Rel(dev, fpycore, "develops")
126-
Rel(dev, fpycodegen, "develops/uses")
127-
Rel(user, fpymf6, "uses")
128-
UpdateRelStyle(dev, dfn, $lineColor="blue", $offsetX="-20" $offsetY="-30")
129-
UpdateRelStyle(dev, fpycore, $lineColor="blue", $offsetY="90")
130-
UpdateRelStyle(dev, fpycodegen, $lineColor="blue", $offsetY="50")
131-
UpdateRelStyle(user, fpymf6, $lineColor="blue", $offsetY="50")
132-
UpdateRelStyle(user, fpycore, $lineColor="blue", $offsetX="-20" $offsetY="-10")
133-
134-
```
39+
Other libraries and tools may build upon the MVP to offer more advanced, domain-specific, or application-specific functionality.
13540

13641
## Requirements
13742

138-
Broadly, the product should
139-
140-
- preserve existing `flopy.mf6` functionality
141-
- be consistent, user-friendly and pythonic
142-
- be easy to read, debug, diagnose and test
143-
- be memory-efficient and provide fast IO
144-
- separate concerns of users/developers
145-
- impose a minimal maintenance burden
146-
147-
Specific requirements are based on stakeholder interviews and internal research.
148-
14943
Requirements are prioritized according to the [MoSCoW method](https://en.wikipedia.org/wiki/MoSCoW_method), indicating which requirements Must, Should, Could, and Won't be included in the first iteration.
15044

15145
### Functional requirements
@@ -157,36 +51,30 @@ Requirements are prioritized according to the [MoSCoW method](https://en.wikiped
15751
| FUNC-3 | The product can run MODFLOW 6 simulations and provide access to their results. | M |
15852
| FUNC-4 | The product can programmatically create, access, and manipulate MODFLOW 6 simulations. | M |
15953
| FUNC-5 | The product supports existing MODFLOW 6 discretization types and can be extended to support new ones. | M |
160-
| FUNC-6 | The product supports parallel MODFLOW 6 simulations, including requisite pre-processing e.g. model splitting. | M |
161-
| FUNC-7 | The product can plot simulation results with extensible plotting APIs building on popular visualization libraries. | M |
162-
| FUNC-9 | The product can export data to popular data storage/interchange formats (e.g. NetCDF, VTK, geospatial standards. | M |
163-
| FUNC-10 | The product can validate simulations (i.e. check invariants) and warn the user of potential problems before running a simulation. | S |
164-
| FUNC-11 | The product supports extensible/user-defined validations. | C |
165-
| FUNC-12 | The product allows simulation subcomponents to be created independently of parent context, then combined programmatically. | M |
166-
| FUNC-14 | The product can round-trip (i.e. load, write, and run) an existing simulation and give identical results to previous runs. | C |
167-
| FUNC-15 | The product can manage larger-than-memory models and datasets. E.g., the product can be used to create an example model of the United States with a **?1 km?** grid resolution. | M |
168-
| FUNC-16 | The product can determine and report whether it is compatible with a given MODFLOW 6 version (and corresponding specification). | M |
169-
| FUNC-17 | The product is compatible with a wide range of MODFLOW 6 versions (and corresponding specifications) | S |
170-
| FUNC-18 | The product understands and can manage/convert spatial units. | C |
171-
| FUNC-19 | The product understands and can manage/convert temporal units (date and time). | C |
172-
| FUNC-20 | The product can generate a MODFLOW 6 interface layer (i.e. source code) from definition files. | M |
173-
| FUNC-21 | The product's MF6 interface layer can be inspected at runtime, e.g. to discover component attributes and variables. | M |
174-
| FUNC-22 | The product's MF6 interface layer can reproduce the specification used to generate it. | S |
175-
| FUNC-23 | The product provides appropriate, informative string dumps for simulation components. | M |
176-
| FUNC-24 | The product provides programmatic access from any component to any other component registered with the simulation. | S |
54+
| FUNC-6 | The product allows simulation subcomponents to be created independently of parent context, then combined programmatically. | M |
55+
| FUNC-7 | The product can round-trip (i.e. load, write, and run) an existing simulation and give identical results to previous runs. | C |
56+
| FUNC-8 | The product can manage larger-than-memory models and datasets. E.g., the product can be used to create an example model of the United States with a **?1 km?** grid resolution. | M |
57+
| FUNC-9 | The product can determine and report whether it is compatible with a given MODFLOW 6 version (and corresponding specification). | M |
58+
| FUNC-10 | The product is compatible with a wide range of MODFLOW 6 versions (and corresponding specifications) | S |
59+
| FUNC-11 | The product supports spatial and temporal units to the extent that MODFLOW 6 does. | C |
60+
| FUNC-12 | The product can generate a MODFLOW 6 interface layer (i.e. source code) from definition files. | M |
61+
| FUNC-13 | The product's MF6 interface layer can be inspected at runtime, e.g. to discover component attributes and variables. | M |
62+
| FUNC-14 | The product's MF6 interface layer can reproduce the specification used to generate it. | S |
63+
| FUNC-15 | The product provides appropriate, informative string dumps for simulation components. | M |
64+
| FUNC-16 | The product provides programmatic access from any component to any other component registered with the simulation. | S |
65+
| FUNC-17 | The product allows specifying the precision with which values are written to input files. | M |
17766

17867
### Non-functional requirements
17968

18069
| ID | Description | MoSCoW |
18170
| ------- | ----------- | ------ |
18271
| NFR-1 | The product's documentation makes a clear distinction between public and internal APIs. | M |
183-
| NFR-2 | The product's documentation provides a complete overview of the definition file specification. | M |
184-
| NFR-3 | The product behaves unsurprisingly, with reasonable defaults for common APIs and use cases. | M |
185-
| NFR-4 | The product provides clear and informative error messages to the user when an error occurs. | M |
186-
| NFR-5 | The product has consistent APIs for MODFLOW 6 and older MODFLOW programs. | S |
187-
| NFR-6 | The product can be easily extended e.g. to support new input/output file formats. | S |
188-
| NFR-7 | The product provides a well-documented, type-hinted public API. | S |
189-
| NFR-8 | The product consolidates entry points and emphasizes API discoverability. | S |
72+
| NFR-2 | The product behaves unsurprisingly, with reasonable defaults for common APIs and use cases. | M |
73+
| NFR-3 | The product provides clear and informative error messages to the user when an error occurs. | M |
74+
| NFR-4 | The product has consistent APIs for MODFLOW 6 and older MODFLOW programs. | S |
75+
| NFR-5 | The product can be easily extended e.g. to support new input/output file formats. | S |
76+
| NFR-6 | The product provides a well-documented, type-hinted public API. | S |
77+
| NFR-7 | The product consolidates entry points and emphasizes API discoverability. | S |
19078

19179
### System requirements
19280

0 commit comments

Comments
 (0)