feat(lgr): add from_parent_grid classmethod to Lgr class

[wpbonelli]

Factored out of #2667

It's a bit verbose to manually pass all the parent grid props into the Lgr grid initializer, this makes it easier. I named the refinement region parameter refine_mask as this seemed clearer than idomainp as in the initializer. If others agree maybe worth a deprecation/name change in the initializer too?

The original version in #2667 used the parent grid's idomain as the refinement mask, I was thinking because of the naming this might be justifiable, but decided it was better to keep them separate. Someone might want an inactive region to remain in the parent grid when the refinement is applied.

[codecov]

Codecov Report

❌ Patch coverage is 94.28571% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.7%. Comparing base (556c088) to head (31a0d63).
⚠️ Report is 97 commits behind head on develop.

Files with missing lines	Patch %	Lines
flopy/utils/lgrutil.py	94.2%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #2668      +/-   ##
===========================================
+ Coverage     55.5%    72.7%   +17.1%     
===========================================
  Files          644      667      +23     
  Lines       124135   129538    +5403     
===========================================
+ Hits         68947    94187   +25240     
+ Misses       55188    35351   -19837     

Files with missing lines	Coverage Δ
flopy/utils/lgrutil.py	97.3% <94.2%> (+<0.1%)	⬆️

... and 559 files with indirect coverage changes

🚀 New features to boost your workflow:

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

[wpbonelli]

@christianlangevin the main question I had for you is whether there is history to the idomainp naming / if you like refine_mask. this is pretty small and benign otherwise, just a convenience, but it will allow cleanly updating the nested grid MF6 example and then removing the deprecated gridlist_to_disv_gridprops

[christianlangevin]

refine_mask makes sense to me because of the reason you mentioned. idomain may be needed to remove parts of the model grid, whereas refine_mask needs to remove/deactivate cells and mark where to refine. Nice change.

[wpbonelli]

@christianlangevin do you mind giving this one last look? I tried to clarify the relationship between the refinement region and the resulting child grid idomain in the docstrings.

[christianlangevin]

I added a little more description. Not sure if it helps. Feel free to add or jettison. I like the refinet_mask terminology. Keep in mind that this utility may be used repeatedly to create either a parent model with multiple child models or a parent model with a child model, and a grandchild model, etc. I don't recall if we have any tests or examples with this, but we have used it that way in the past.

[christianlangevin]

This is good, @wpbonelli. Perhaps we can clarify even further.

Array indicating which parent cells to refine (shape: nlay, nrow, ncol). Cells with value 0 will be refined, with value 1 remain as parent cells. When a parent cell is marked to be refined, it will be deactivated in the parent model using the idomain functionality. The region of these refined parent cells will be represented by active cells in the child model. The child grid domain will span the rectangular region covering the zeros. This approach is designed so that a region is only represented by active cells in either the parent or child model grid.