Generating FloPy classes

Generating FloPy classes
- Testing class generation

MODFLOW 6 input continues to evolve as new models, packages, and options are developed, updated, and supported. All MODFLOW 6 input is described by DFN (definition) files, which are simple text files that describe the blocks and keywords in each input file. These definition files are used to build the input and output guide for MODFLOW 6. These definition files are also used to automatically generate FloPy classes for creating, reading and writing MODFLOW 6 models, packages, and options. FloPy and MODFLOW 6 are kept in sync by these DFN (definition) files, and therefore, it may be necessary for a user to update FloPy using a custom set of definition files, or a set of definition files from a previous release.

The FloPy classes for MODFLOW 6 are largely generated by a utility which converts DFN files in a modflow6 repository on GitHub or on the local machine into Python source files in your local FloPy install. For instance (output much abbreviated):

$ python -m flopy.mf6.utils.generate_classes



************************************************************************
Updating the flopy MODFLOW 6 classes
  Updating the MODFLOW 6 classes using MODFLOW-USGS/modflow6/master
  Downloading MODFLOW 6 repository from https://github.com/MODFLOW-USGS/modflow6/archive/master.zip
Downloading https://github.com/MODFLOW-USGS/modflow6/archive/master.zip
   file size: 15,821,180 bytes

total download time: 0.88 seconds
Uncompressing: C:\Users\***\AppData\Local\Temp\***\master.zip
Deleting zipfile C:\Users\***\AppData\Local\Temp\***\master.zip
Done downloading and extracting master.zip to C:\Users\***\AppData\Local\Temp\***
  Backup existing definition files in: C:\Users\***\flopy\flopy\mf6\data\dfn
  Replacing existing definition files with new ones.
  removing...common.dfn    
  removing...exg-gwfgwf.dfn
  ...
  copying..common.dfn
  copying..exg-gwfgwf.dfn
  ...
  Deleting existing mf6 classes.
  removing...mfgnc.py
  removing...mfgwf.py
  ...
  Create mf6 classes using the downloaded definition files.
LIST OF FILES IN C:\Users\***\flopy\flopy\mf6\modflow
        1 - mfgnc.py
        2 - mfgwf.py
        ...

Similar functionality is available within Python, e.g.:

>>> from flopy.mf6.utils import generate_classes
>>> generate_classes()

The generate_classes() function has several optional parameters.

$ python -m flopy.mf6.utils.generate_classes -h
usage: generate_classes.py [-h] [--owner OWNER] [--repo REPO] [--ref REF]
                           [--dfnpath DFNPATH] [--no-backup]

Generate the MODFLOW 6 flopy classes using definition files from the MODFLOW 6
GitHub repository or a set of definition files in a folder provided by the
user.

options:
  -h, --help         show this help message and exit
  --owner OWNER      GitHub repository owner; default is 'MODFLOW-USGS'.
  --repo REPO        Name of GitHub repository; default is 'modflow6'.
  --ref REF          Branch name, tag, or commit hash to use to update the
                     definition; default is 'master'.
  --dfnpath DFNPATH  Path to a definition file folder that will be used to
                     generate the MODFLOW 6 classes.
  --no-backup        Set to disable backup. Default behavior is to keep a
                     backup of the definition files in dfn_backup with a date
                     and timestamp from when the definition files were
                     replaced.

For example, use the develop branch instead:

$ python -m flopy.mf6.utils.generate_classes --ref develop

use a fork of modflow6:

$ python -m flopy.mf6.utils.generate_classes --owner your-username --ref your-branch

maybe your fork has a different name:

$ python -m flopy.mf6.utils.generate_classes --owner your-username --repo your-modflow6 --ref your-branch

local copy of the repo:

$ python -m flopy.mf6.utils.generate_classes --dfnpath ../your/dfn/path

Branch names, commit hashes, or tags may be provided to ref.

By default, a backup is made of FloPy’s package classes before rewriting them. To disable backups, use --no-backup from command-line, or backup=False with the Python function.

Testing class generation

Tests for the generate_classes() utility are located in test_generate_classes.py. The tests depend on virtualenv and will be skipped if run in parallel without the --dist loadfile option for pytest-xdist.