feat(dfns): specify and reimplement v2 dfn schema

[wpbonelli]

Draft a new DFN specification and schema in the dfns module. Simplify the DFNs API. Clean up the older dfn module. Rewrite and reorganize some docs. Drop Python3.10 and add Python3.14.

The schema mapping is messy, but temporary. Once we move to v2 upstream in mf6 it can go away. The tentative v2 spec/schema is what really matters here.

[wpbonelli]

@mwtoews if you have thoughts on the approach here, we'd be glad to hear. I know this is huge, sorry. Key files are dfnspec.md and modflow_devtools.dfns.schema.py. Most of the rest is cleanup. Still rough, but since the dfns module is experimental and nothing but the flopy4 prototype uses it yet I might merge and iterate in smaller steps to keep this more legible going forward.

Basic goals here are to formalize what we've been prototyping for some time now, moving from flat to structured definitions, and making anything implicit in the old DFNs explicit and amenable to validation.

Important to note that we decided to stop normalizing period block data into separate arrays as the "v1.1" schema did. That's what package variants (e.g. WELG, RCHA) are for: each definition is a possible representation, e.g. sparse list-based vs dense array-based period data. So v2 will respect the v1 DFNs' representational choices. I got carried away before.

The tentative schema here adopts most of your suggestions in #229

• deduplication: drop the redundant block and name attributes from fields since they're already implied by the table structure
• shape as a list: e.g. ["nper", "nnodes"] rather than string "(nper, nnodes)"
• YAML over TOML: support both (or JSON) but default to YAML
• JSON Schema: define schema + validations with pydantic, generate and check in schema.json file

Flags are still distinct instead of a single attrs list, though. Seemed cleaner but I don't have strong feelings.

@martclanor your feedback would be super valuable too. Could your VSCode plugin consume the JSON schema?

[mwtoews]

Thanks @wpbonelli appreciate implementing the suggestions and providing a summary for this PR (+6,738,-5,219). I'll probably take a look at develop to see the implementation.

[wpbonelli]

(+6,738,-5,219)

😅

Just figured I'd give you a heads up that we are taking a lot of your advice and say please feel free to weigh in at any point. Sorry if the above reads like a request to review 6000 LOC, it was not.

[martclanor]

@wpbonelli, great stuff here! Glad to see such detailed documentation as well.

I'm trying to catch up with the developments here. In addition to the two files that you referred to, I find the docs/md/dfns.md handy when it comes to integrating with the VS Code extension.

So far, only the fetching of dfns has been added. Next, I plan to parse the dfns with the modflow_devtools.dfns.Dfns object and delegate as much as possible of the logic to the devtools.

I was wondering if it is also planned to move the mf6ivar.py functions from the mf6 repo to modflow-devtools. If so then the VS Code extension can also use these, for example, to create the block structure definitions or keyword descriptions.

With regards to the question about the JSON schema, I still have to look into this further but so far, I'm not sure just yet how the extension can consume that or if it's needed because I will use the Dfns object already with the v2 schema.

[wpbonelli]

With regards to the question about the JSON schema, I still have to look into this further but so far, I'm not sure just yet how the extension can consume that or if it's needed because I will use the Dfns object already with the v2 schema.

Yeah, you're right. The JSON schema here would only be useful for validating DFN files themselves, not input files.

I was wondering if it is also planned to move the mf6ivar.py functions from the mf6 repo to modflow-devtools. If so then the VS Code extension can also use these, for example, to create the block structure definitions or keyword descriptions.

We can move that into devtools, maybe, as a render() method on component, block and field types.. nice idea.

[wpbonelli]

@martclanor is something like #332 what you had in mind?

[martclanor]

Yes, this is awesome! 😀 Thanks! Playing a bit around the API and the drilldown is now much simpler:

Dfns.load("data/dfns/6.7.0").components["gwf-chd"].blocks["options"].fields["ts_filerecord"].fields["ts6"].description
# 'keyword to specify that record corresponds to a time-series file.'