feat(gridgen): build GNC package input from gridgen output

[jdhughes-dev]

• Added Gridgen.get_gnc to read the ghost node data gridgen writes to qtg.gnc.dat

• Added Gridgen.get_gridprops_gnc6, Gridgen.get_gridprops_gnc5, and get_gridprops_gnc5 to convert it to MODFLOW 6 and MODFLOW-USG GNC Package input

• Fixed MfUsgGnc.write_file, which truncated the contributing factors to three significant digits and wrote the options list with its Python repr

• Fixed fmt_string, which joined the field formats with no separator regardless of the format of the list, so a value that filled its width ran into the next value

• Closes bug: CLN package list output has no separator between fields #2788

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 70.0%. Comparing base (556c088) to head (f8df65a).
⚠️ Report is 183 commits behind head on develop.

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #2789      +/-   ##
==========================================
+ Coverage     55.5%   70.0%   +14.5%     
==========================================
  Files          644     315     -329     
  Lines       124135   65915   -58220     
==========================================
- Hits         68947   46205   -22742     
+ Misses       55188   19710   -35478     

Files with missing lines	Coverage Δ
flopy/mfusg/mfusg.py	78.3% <100.0%> (+0.8%)	⬆️
flopy/mfusg/mfusggnc.py	83.0% <100.0%> (+1.9%)	⬆️
flopy/utils/__init__.py	100.0% <100.0%> (ø)
flopy/utils/gnc.py	100.0% <100.0%> (ø)
flopy/utils/gridgen.py	76.6% <100.0%> (-10.5%)	⬇️

... and 588 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR adds support for building Ghost Node Correction (GNC) package inputs directly from GRIDGEN output (qtg.gnc.dat) and improves MODFLOW-USG GNC/CLN-style list writing so free-format records remain tokenizable (URWORD-safe).

Changes:

• Added Gridgen.get_gnc and helpers to read qtg.gnc.dat and convert it to MODFLOW 6 / MODFLOW-USG GNC package constructor inputs.
• Added get_gridprops_gnc5 conversion utilities and exposed them via flopy.utils.
• Fixed MODFLOW-USG GNC writer output (options formatting + avoid truncating contributing factors) and fixed fmt_string to separate free-format fields with spaces.

Reviewed changes

Copilot reviewed 9 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
flopy/utils/gridgen.py	Adds GRIDGEN qtg.gnc.dat reader and Gridgen helpers to build MODFLOW 6/USG GNC gridprops.
flopy/utils/gnc.py	Extends utilities with MODFLOW-USG (get_gridprops_gnc5) conversion support.
flopy/utils/init.py	Re-exports get_gridprops_gnc5 from flopy.utils.
flopy/mfusg/mfusggnc.py	Fixes GNC package file writing (options keywords + higher-precision/free-format list output).
flopy/mfusg/mfusg.py	Fixes fmt_string so free-format lists are space-separated to keep fields readable by URWORD.
autotest/test_gridgen.py	Adds end-to-end and unit tests for reading GRIDGEN GNC output and building gridprops.
autotest/test_gnc.py	Adds tests to validate agreement between computed vs GRIDGEN GNC and validates output formatting behavior.
.docs/Notebooks/mfusg_gnc_example.py	New notebook example demonstrating MODFLOW-USG GNC workflow with GRIDGEN output.
.docs/Notebooks/gnc_example.py	New/updated notebook example demonstrating MODFLOW 6 GNC workflows including GRIDGEN route.
examples/data/mfusg_transport/Ex3_CLN_Conduit/Dispersion/Conduit_Dispersion_CLN.CBB	Adds/updates example dataset artifact used by documentation/examples.

Suppressed comments (1)

autotest/test_gnc.py:485

• This assertion is duplicated (the exact same np.allclose(run(2), run(4), ...) check is performed twice). Remove the duplicate to avoid redundant solver runs and keep the test intent clear.

    assert np.allclose(run(2), run(4), atol=1e-8)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jdhughes-dev]

Both removed. They are leftovers from splitting these tests across branches.

The second one is not a decorator. Line 485 repeated the assertion at the end of test_mfusg_gnc_padding:

    assert np.allclose(run(2), run(4), atol=1e-8)

    assert np.allclose(run(2), run(4), atol=1e-8)

Each run() builds and runs a MODFLOW-USG model, so the test was doing four model runs where two are needed.

Swept the rest of the split files for the same kind of damage and found nothing else.