`flopy.discretization.ModelTime` object lacks API for reading references from files

[zroy-wc]

flopy 3.3.5
python 3.10.5

Model grid geographic reference information can be loaded from files. No such option exists for model temporal reference information.

Current Behavior

Default behavior for flopy.discretization.Grid classes is to read from the following references in order:

1. usgs.model.reference
2. NAM file (header comment)
3. defaults

The .modflow.Modflow class creates .discretization.ModelTime and (sub-classes of) .discretization.Grid objects for it's modeltime and modelgrid attributes (respectively).

The ModelTime object does not support reading from the above references like it's Grid counterpart does. Additionally, the .utils.reference.TemporalReference does not support reading from file either.

Existing behavior for reading temporal information exists in the Grid class in it's read_usgs_model_reference_file and attribs_from_namfile_header methods. Currently, temporal information is not used. Moving these methods to .utils.reference, and adjusting them to be functions that return dict could allow their use in the ModelTime class as well.

Proposed Change

1. Create 2 functions, read_usgs_model_reference_file and read_attribs_from_namfile_header in .utils.reference. Use the following signatures.
   • def read_usgs_model_reference_file(reffile: str="usgs.model.reference") -> dict:
   • def read_attribs_from_namfile_header(namefile: str)-> dict:
2. Alter 2 existing methods in .discretization.Grid. Adjust these methods to use the .utils.referece functions created above. Changes would be made o read_usgs_model_reference_file and attribs_from_namfile_header methods.
3. Add 2 methods in .discretization.ModelTime class to mirror the API for the Grid class.

Files changed would be:

• flopy/discretization/grid.py
• flopy/discretization/modeltime.py
• flopy/utils/reference.py

Let me know if you see any complications here that I am ignorant to. If there are none seen, I can submit a pull request.

Cheers

Minimum Reproducible Example Files

example.nam
# Name file for MODFLOW-NWT, generated by Flopy version 3.3.5.
LIST               2  example.list
DIS               11  example.dis

example.dis
# DIS package for MODFLOW-NWT generated by Flopy 3.3.5
         1         1         1         5         4         2
  0
CONSTANT    1.000000E+00                           #delr                          
CONSTANT    1.000000E+00                           #delc                          
CONSTANT    1.000000E+00                           #model_top                     
CONSTANT    0.000000E+00                           #botm layer 1                  
      1.000000             1  1.000000  SS 
      1.000000             1  1.000000  SS 
      1.000000             1  1.000000  SS 
      1.000000             1  1.000000  SS 
      1.000000             1  1.000000  SS 

usgs.model.reference
# Hypothetical, non-zero for demonstration
xul 2.022
yul 3.14
rotation 42
# Set non-typical
time_units days
start_date 1/1/2000
start_time 00:00:00

read_example.py
import flopy

model = flopy.modflow.Modflow.load('example.nam')
model.modelgrid.load_coord_info('example.nam')  # No api available for temporal data

print(model.modeltime.start_datetime)
# 1-1-1970
print(model.modelgrid)
# xll:2.691130606358858; yll:2.3968551745226057; rotation:42.0; units:meters; lenuni:2

[zroy-wc]

Note: I have a branch in my personal fork that is passing the tests run with the following.
pytest -v -n auto -m "not slow and not example and not regression"

I plan on running the full test suite if the proposition seems fine, and create a pull request at that point.

[wpbonelli]

Thanks for this @zroy-wc and apologies for the long delay. Your suggestion seems good to me, with the caveat that in #1915 it is proposed to deprecate and eventually remove flopy.utils.reference, so I think ModelTime would be the place for this. Maybe others have thoughts or are aware of complications I am not.