repository·develop·Indexed 17 days ago
https://github.com/modflowpy/flopyFloPy is a Python library used to create, run, and post-process MODFLOW-based groundwater models. It supports various MODFLOW engines including MODFLOW 6, MODFLOW-2005, MODFLOW-NWT, MODFLOW-USG, and MODFLOW-2000, as well as transport and particle tracking models such as MODPATH (versions 6 and 7), MT3DMS, MT3D-USGS, and SEAWAT.
FloPy provides support for a wide range of MODFLOW-based models, including:
FloPy provides support for a wide range of MODFLOW-based models, including:
The flopy.mf6.data.mfstructure.MFStructure class is a singleton that represents the entire MODFLOW 6 input specification. It stores meta-data for all package files in a structured hierarchy, which FloPy uses to read/write files, create interfaces, and validate data constraints.
The hierarchy follows this composition pattern:
MFModelStructure and MFInputFileStructure (for simulation-level packages like tdis, ims).MFInputFileStructure for each package in that model.MFBlockStructure for each block in the package.MFDataStructure for each data structure in the block.generate_classes function in flopy.mf6.utils to automatically generate Python source code from these DFN files.In the flopy.mf6 module, package and data classes are organized to map the physical structure of MODFLOW 6 files to Python objects:
MFInputFileStructure (defining file structure) and a dictionary of MFBlock objects.MFBlockStructure and a dictionary of MFData objects (subclasses of MFData), along with a list of MFBlockHeader objects (containing block names and optional items like iprn).MFData subclasses contain an MFDataStructure defining their expected types and structure.There are three primary data types derived from MFData:
numpy recarrays.numpy ndarrays.Data defined for each stress period (e.g., period blocks) uses transient subclasses of the types above:
MFTransientList (subclass of MFList)MFTransientArray (subclass of MFArray)MFTransientScalar (subclass of MFScalar)MFTransientData.Snapshot testing verifies computations against previously captured "snapshots" using the syrupy library and fixtures from modflow-devtools.
By default, tests run in comparison mode, meaning a new test will fail until a snapshot is created. To create or update snapshots, run pytest with the --snapshot-update flag.
Performance testing is handled via pytest-benchmark.
Benchmarking:
Wrap a function call using the benchmark fixture. You can pass the function directly, pass arguments, or use a lambda for complex calls.
def test_benchmark(benchmark):
def sleep_s(s):
import time
time.sleep(s)
return True
assert benchmark(lambda: sleep_s(1))Profiling:
To evaluate the call stack in detail, run tests with the --benchmark-cprofile flag. You can specify the sorting column (e.g., --benchmark-cprofile="tottime").
Notes:
pytest-xdist).--benchmark-disable to turn it off manually.--benchmark-autosave to save results to a .benchmarks folder in the current working directory.Tests must be executed from the autotest directory.
Basic Commands:
pytest -v <filename>.pypytest -v -k "<pattern>"pytest -v -n auto (or specify a number like -n 2 or -n=2)Selecting tests with markers:
Use the -m flag to filter tests by the following markers defined in pytest.ini:
slow: Tests that take longer than a few seconds.example: Scripts, tutorials, and notebooks.regression: Tests that compare multiple results.Smoke Testing:
To run a fast subset of tests (excluding slow, example, and regression tests) that completes in under a minute, use the --smoke (or -S) alias:
pytest -v -n auto -SThe update_version.py script automates the process of updating the FloPy version number across the repository. It updates version.txt and propagates the change to flopy/version.py, CITATION.cff, README.md, and docs/PyPI_release.md.
Behavior:
Options:
--version or -v: Sets a new version number.--get or -g: Retrieves the current version from version.txt without making changes.# Set the version to 3.3.6
python scripts/update_version.py -v 3.3.6
# Get the current version
python scripts/update_version.py -gIf the automatic bot does not update the Conda distribution, follow these steps using a fork of conda-forge/flopy-feedstock:
*.tar.gz release from the GitHub releases page.openssl sha256 flopy-version.tar.gzflopy-feedstock:cd /path/to/your/flopy-feedstock_fork
git fetch upstream
git checkout master
git reset --hard upstream/master
git push origin master --forceconda-smithy:conda smithy rerenderrecipe/meta.yaml file.conda-forge/flopy-feedstock repository.openssl sha256 flopy-version.tar.gz
conda smithy rerenderWhen contributing new examples, the filename determines how they are categorized in the documentation:
tutorial are assigned to the Tutorials page. They should demonstrate a single basic feature.example are full-fledged examples, often demonstrating multiple features or complex workflows.All examples must include a jupytext header. You can generate a template by performing a round-trip conversion (script $\to$ notebook $\to$ script) using jupytext. The header must include at minimum:
section: The documentation section (use create_rstfiles.py to see available sections; defaults to "Miscellaneous").authors: A list of the example's authors.Example header format:
# ---
# jupyter
# jupytext:
# ...
# kernelspec:
# ...
# metadata:
# section: ...
# authors:
# - name: ......
# ---jupytext --from py --to ipynb .docs/Notebooks/your_example.py
jupytext --from ipynb --to py .docs/Notebooks/your_example.ipynbTo ensure VSCode correctly uses your FloPy environment and activates it in integrated terminals, add the following to your settings.json. Replace /path/to/environment with the actual path to your environment's Python executable (which you can find by running where python in an activated terminal).
{
"python.defaultInterpreterPath": "/path/to/environment",
"python.terminal.activateEnvironment": true
}