This document describes how to set up an environment to use or develop the MODFLOW 6 example models.
The examples are Python scripts managed with jupytext. The Python files in scripts/ are the ultimate source of truth. Data and notebooks are generated from the scripts. There are more examples than scripts: some of the scripts produce multiple examples.
This section lists steps to set up a development environment, build the examples from scripts, and finally build the examples documentation.
- install MODFLOW 6 and related programs
- Install Python dependencies
- make sure FloPy is up to date
Install modeling programs using the get-modflow utility that is available from FloPy. From any directory, issue the following commands:
get-modflow :
get-modflow --repo modflow6-nightly-build :
The command will show a prompt to select the install location. Any location can be selected, as get-modflow will put the executables on your path (the notebooks expect binaries to be available on the path).
Several Python packages are required to create the MODFLOW 6 examples. These are listed in etc/requirements.pip.txt and etc/requirements.usgs.txt.
It's important that FloPy is up-to-date with the latest changes to MODFLOW 6. The latest release of FloPy is always up to date with the latest release of MODFLOW 6.
To manually update FloPy from some branch of the official MODFLOW 6 repository:
import flopy
flopy.mf6.utils.generate_classes(owner="MODFLOW-USGS", branch="master", backup=True)
The above is equivalent to calling the function with no arguments. Arguments may be substituted to select an alternative repository (e.g. your fork) or branch.
The examples can be run with Jupyter or with Pytest.
To start a Jupyter browser interface, run jupyter notebook from the notebooks/ directory.
Pytest can be used to run all of the example scripts and models. The pytest-xdist plugin is a convenient way to run the scripts in parallel. Note that pytest must be invoked from the etc/ directory, not from scripts/.
To run example scripts in parallel with verbose output, and generate input files without running models:
pytest -v -n auto ci_build_files.pyTo run models, use --run True.
To run in serial instead of parallel, omit -n auto.
Adding a new example requires adding a new example script in the scripts/ folder and adding a new LaTeX problem description in the doc/sections/ folder. Then open a pull request from your fork of the repository.
A new release is automatically created whenever code is merged into the trunk branch of this repository. Steps to manually prepare for a release are listed below.
- Generate notebooks and tables
- Build examples documentation
The example scripts must be converted into jupyter notebooks using jupytext, then latex tables generated from specially formatted code/comments. Run process-scripts.py in the scripts/ directory to do this.
If the figures and tables were generated correctly, then it should be possible to build the examples PDF document. The PDF can be created by processing doc/mf6examples.tex with pdftex or a similar tool.