Forcings Engine Data Provider Interface and Lumped Forcings Implementation

[program--]

This PR adds a ForcingsEngineDataProvider base class and ForcingsEngineLumpedDataProvider implementation.

Implementation Details

ForcingsEngineDataProvider is a templated base class taking two types, DataType and SelectionType, and inherits from DataProvider<DataType, SelectionType>. The base class handles Python module instantiation and timing functions, and leaves value acquisition to derived classes.

ForcingsEngineLumpedDataProvider is a derived class of ForcingsEngineDataProvider<double, CatchmentAggrDataSelector> representing the forcings engine in lumped catchment mode (i.e. GRID_TYPE in the config file is set to "hydrofabric").

Since the forcings engine provides values over an entire domain, the classes are designed in a flyweight-like manner, where construction and instance referencing are through static maps for each templated base class of ForcingsEngineDataProvider, i.e. each derived class instance is stored in a map of its base type.

Derived classes should implement a static construction function that uses the protected function ForcingsEngineDataProvider::set_instance, which moves a unique_ptr of the base class into the static map. Then, to get an instance, callers should either use the return from the derived function (i.e. ForcingsEngineLumpedDataProvider::lumped_instance), or get an existing instance using ForcingsEngineDataProvider<DataType, SelectionType>::instance. Ownership and lifetime management are held by the static maps, so these functions return raw pointers (that do not imply any ownership).

Note: it may make sense to return references instead.

Additions

• ForcingsEngineDataProvider
• ForcingsEngineLumpedDataProvider, and a corresponding test fixture ForcingsEngineLumpedDataProviderTest.
• assert_forcings_engine_requirements, which checks that the forcings engine python module is installed, and checks for the $WGRIB2 environment variable.

Changes

• Separate NullForcingsEngine implementation into source file so that the NGen::forcings CMake target always has a source.

Notes

• To use the forcings engine, the user's environment requires NetCDF/PNetCDF, ParallelIO, ESMF (+ python bindings), and the wgrib2 executable.
• When running the forcings engine, the WGRIB2 environment variable must be set to the path of the wgrib2 executable. If/when pywgrib2 is integrated, this will not be a requirement.

To-Do

• Allow forcings engine to be installable as a package (Make Forcings Engine Installable via pip jduckerOWP/ngen-forcing#3)

Checklist

• PR has an informative and human-readable title
• Changes are limited to a single goal (no scope creep)
• Code can be automatically merged (no conflicts)
• Code follows project standards (link if applicable)
• Passes all existing automated tests
• Any change in functionality is tested
• New functions are documented (with a description, list of inputs, and expected output)
• Placeholder code is flagged / future todos are captured in comments
• Project documentation has been updated (including the "Unreleased" section of the CHANGELOG)
• Reviewers requested with the Reviewers tool ➡️

Target Environment support

• Linux
• macOS

[PhilMiller]

I'm happy with this. It would probably be good to get a fresh review from someone else, since I've poked at so many bits of this along the way.

[PhilMiller]

@donaldwj @hellkite500 Could one of you review this? I'm happy with it, but I've also had a lot of say in its progression, so I don't want to be the one to sign off on it.