Skip to content

trim srs scope #163

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 17, 2025
Merged

trim srs scope #163

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 24 additions & 136 deletions docs/dev/srs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,134 +18,28 @@

## Introduction

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

### Product scope

The product will be able to run MODFLOW simulations.

The product will support pre- and post-processing MODFLOW-based model input and output.

Pre-processing includes tasks like preparing model input and mesh generation.

Post-processing includes tasks like loading model output, plotting/visualiation, rudimentary statistical analysis, and interop with 3rd party formats/tools.

The MVP will be able to load, write, and run MODFLOW 6 simulations.

### Product value

The product allows reproducible, versionable Python workflows for MODFLOW modeling applications.

The product wraps MODFLOW and other programs and provide a Pythonic interface to their functionality and input and output files.

The product is essential to the MODFLOW development process for testing existing and newly developed functionality.
The MVP delivers a basic set of functionality which will become the core of FloPy 4.

### Intended audience

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.

Another key audience is the MODFLOW development team.
The MVP is an internal product for use by the MODFLOW 6 and FloPy development team, as well as external collaborators.

### Intended use

The product should be compatible with all major operating systems and hardware ranging from laptops to HPC systems.

The product may be used in standalone scripts, inside applications, from interactive notebooks, and any other common Python runtime.

Other libraries and tools may build upon the product to offer more advanced, domain-specific, or application-specific functionality.

### Use cases

- A hydrologist needs to determine an optimal pumping rate for a well field...

- A student wants to simulate salt water intrusion in a coastal aquifer and visualize results...

- A professor is teaching a groundwater modeling class...

- 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...

- A MODFLOW developer is debugging an issue in the UZF package and wants to create a complicated test with many cells and stress periods...
The MVP is a developer-facing library supporting the core functionality describe above.

- A MODFLOW developer is setting up a worked example to demonstrate how to use a new feature...

- 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...

```mermaid
C4Context
title [Context] Product use cases

Person(hydrologist, "Hydrologist", "determines optimal pumping rate for well field")
Person(student, "Student", "simulates salt water intrusion in coastal aquifer")
Person(professor, "Professor", "teaches groundwater modeling course")
Person(institution, "Lab/Institution", "maintains pre-/post-processing extensions")
Person(developer, "Developer", "debugs issues, develops features/models")

System(flopy, "FloPy")
System(mf6, "MODFLOW 6")

Rel(flopy, mf6, "wraps")
Rel(hydrologist, flopy, "uses")
Rel(student, flopy, "uses")
Rel(professor, flopy, "uses")
Rel(institution, flopy, "extends")
Rel(developer, flopy, "develops")
UpdateRelStyle(hydrologist, flopy, $lineColor="blue")
UpdateRelStyle(student, flopy, $lineColor="blue")
UpdateRelStyle(professor, flopy, $lineColor="blue")
UpdateRelStyle(institution, flopy, $lineColor="blue", $offsetX="-190", $offsetY="10")
UpdateRelStyle(developer, flopy, $lineColor="blue")

```

```mermaid
C4Context
title [Context] Code generation workflow

Boundary(mf6, "MODFLOW 6"){
SystemDb(dfn, "Specification")
}

Boundary(flopy, "FloPy") {
Boundary(devs, "Developer APIs") {
System(fpycore, "Core framework")
System(fpycodegen, "Code generation")
}
Boundary(users, "User APIs") {
System(fpymf6, "MF6 module")
}
Rel(fpymf6, fpycore, "imports")

Rel(fpycodegen, dfn, "inspects")
Rel(fpycodegen, fpymf6, "generates")
}

Person(dev, "Developer", "")
Person(user, "User", "")

Rel(dev, dfn, "develops")
Rel(dev, fpycore, "develops")
Rel(dev, fpycodegen, "develops/uses")
Rel(user, fpymf6, "uses")
UpdateRelStyle(dev, dfn, $lineColor="blue", $offsetX="-20" $offsetY="-30")
UpdateRelStyle(dev, fpycore, $lineColor="blue", $offsetY="90")
UpdateRelStyle(dev, fpycodegen, $lineColor="blue", $offsetY="50")
UpdateRelStyle(user, fpymf6, $lineColor="blue", $offsetY="50")
UpdateRelStyle(user, fpycore, $lineColor="blue", $offsetX="-20" $offsetY="-10")

```
Other libraries and tools may build upon the MVP to offer more advanced, domain-specific, or application-specific functionality.

## Requirements

Broadly, the product should

- preserve existing `flopy.mf6` functionality
- be consistent, user-friendly and pythonic
- be easy to read, debug, diagnose and test
- be memory-efficient and provide fast IO
- separate concerns of users/developers
- impose a minimal maintenance burden

Specific requirements are based on stakeholder interviews and internal research.

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.

### Functional requirements
Expand All @@ -157,36 +51,30 @@ Requirements are prioritized according to the [MoSCoW method](https://en.wikiped
| FUNC-3 | The product can run MODFLOW 6 simulations and provide access to their results. | M |
| FUNC-4 | The product can programmatically create, access, and manipulate MODFLOW 6 simulations. | M |
| FUNC-5 | The product supports existing MODFLOW 6 discretization types and can be extended to support new ones. | M |
| FUNC-6 | The product supports parallel MODFLOW 6 simulations, including requisite pre-processing e.g. model splitting. | M |
| FUNC-7 | The product can plot simulation results with extensible plotting APIs building on popular visualization libraries. | M |
| FUNC-9 | The product can export data to popular data storage/interchange formats (e.g. NetCDF, VTK, geospatial standards. | M |
| FUNC-10 | The product can validate simulations (i.e. check invariants) and warn the user of potential problems before running a simulation. | S |
| FUNC-11 | The product supports extensible/user-defined validations. | C |
| FUNC-12 | The product allows simulation subcomponents to be created independently of parent context, then combined programmatically. | M |
| FUNC-14 | The product can round-trip (i.e. load, write, and run) an existing simulation and give identical results to previous runs. | C |
| 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 |
| FUNC-16 | The product can determine and report whether it is compatible with a given MODFLOW 6 version (and corresponding specification). | M |
| FUNC-17 | The product is compatible with a wide range of MODFLOW 6 versions (and corresponding specifications) | S |
| FUNC-18 | The product understands and can manage/convert spatial units. | C |
| FUNC-19 | The product understands and can manage/convert temporal units (date and time). | C |
| FUNC-20 | The product can generate a MODFLOW 6 interface layer (i.e. source code) from definition files. | M |
| FUNC-21 | The product's MF6 interface layer can be inspected at runtime, e.g. to discover component attributes and variables. | M |
| FUNC-22 | The product's MF6 interface layer can reproduce the specification used to generate it. | S |
| FUNC-23 | The product provides appropriate, informative string dumps for simulation components. | M |
| FUNC-24 | The product provides programmatic access from any component to any other component registered with the simulation. | S |
| FUNC-6 | The product allows simulation subcomponents to be created independently of parent context, then combined programmatically. | M |
| FUNC-7 | The product can round-trip (i.e. load, write, and run) an existing simulation and give identical results to previous runs. | C |
| 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 |
| FUNC-9 | The product can determine and report whether it is compatible with a given MODFLOW 6 version (and corresponding specification). | M |
| FUNC-10 | The product is compatible with a wide range of MODFLOW 6 versions (and corresponding specifications) | S |
| FUNC-11 | The product supports spatial and temporal units to the extent that MODFLOW 6 does. | C |
| FUNC-12 | The product can generate a MODFLOW 6 interface layer (i.e. source code) from definition files. | M |
| FUNC-13 | The product's MF6 interface layer can be inspected at runtime, e.g. to discover component attributes and variables. | M |
| FUNC-14 | The product's MF6 interface layer can reproduce the specification used to generate it. | S |
| FUNC-15 | The product provides appropriate, informative string dumps for simulation components. | M |
| FUNC-16 | The product provides programmatic access from any component to any other component registered with the simulation. | S |
| FUNC-17 | The product allows specifying the precision with which values are written to input files. | M |

### Non-functional requirements

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

### System requirements

Expand Down