Feature: Create Package-Level Imports For Basic Objects

[RHammond2]

Create Package-Level Imports for Basic H2I Objects

This PR adds H2IntegrateModel, load_yaml, write_yaml, and write_readable_yaml to the h2integrate/__init__.py file to allow each object to be imported as a package-level import instead of from nested subpackages. Examples and documentation now highlight the usage of from h2integrate import H2IntegrateModel for simplified imports for the majority of use cases. The basic I/O functions were also added to allow users to access basic reading and writing functionality similar to many existing packages (e.g., Pandas or Polars). An example workflow could also look like the following sample.

from h2integrate import load_yaml, write_readable_yaml, H2IntegrateModel

config = load_yaml("/path/to/configuration.yaml")

...  # modification steps

write_readable_yaml(config, "path/to/new_configuration.yaml")

model = H2IntegrateModel(config)
model.run()
results = model.print_results()
write_readable_yaml(results, "/path/to/results_for_later.yaml")

The most common usage in all the examples is now simplified to the following example.

from h2integrate import H2IntegrateModel

h2i = H2IntegrateModel("/path/to/config")
h2i.run()

Section 1: Type of Contribution

• Feature Enhancement
  • Framework
  • New Model
  • Updated Model
  • Tools/Utilities
  • Other (please describe): import structure
• Bug Fix
• Documentation Update
• CI Changes
• Other (please describe):

Section 2: Draft PR Checklist

• Open draft PR
• Describe the feature that will be added
• Fill out TODO list steps
• Describe requested feedback from reviewers on draft PR
• Complete Section 7: New Model Checklist (if applicable)

TODO:

• Step 1
• Step 2

Type of Reviewer Feedback Requested (on Draft PR)

Structural feedback:

Implementation feedback:

Other feedback:

Section 3: General PR Checklist

• PR description thoroughly describes the new feature, bug fix, etc.
• Added tests for new functionality or bug fixes
• Tests pass (If not, and this is expected, please elaborate in the Section 6: Test Results)
• Documentation
  • Docstrings are up-to-date
  • Related docs/ files are up-to-date, or added when necessary
  • Documentation has been rebuilt successfully
  • Examples have been updated (if applicable)
• CHANGELOG.md
  • At least one complete sentence has been provided to describe the changes made in this PR
  • After the above, a hyperlink has been provided to the PR using the following format:
    "A complete thought. [PR XYZ]((https://github.com/NatLabRockies/H2Integrate/pull/XYZ)", where
    XYZ should be replaced with the actual number.

Section 4: Related Issues

N/A

Section 5: Impacted Areas of the Software

Section 5.1: New Files

N/A

Section 5.2: Modified Files

• h2integrate/__init__.py: adds H2IntegrateModel, load_yaml, write_yaml, write_readable_yaml as package-level imports
• All relevant documentation, code, and example files have been updated to use the updated import where it makes sense. The package-level imports are not used when other, more niche objects are imported from the same module.

Section 6: Additional Supporting Information

It dawned on me that it's quite tedious to import relatively simple and common functionality from deep within the model's folder structure, and that we don't have to make basic tooling difficult to access. There is likely room to add more functionality to this list, but I chose these few items based on some workflows I was using in addition to seeing what other common workflows existed throughout the examples and documentation.

UPDATE: original PR descriptions have been modified to represent PR feedback.

Section 7: Test Results, if applicable

Passing

[elenya-grant]

Hi Rob! I like the changes with importing H2IntegrateModel! I have a few notes just based off my usage but - not asking for changes! Mostly sharing my thoughts.

I think that I personally use the load_plant_yaml(), load_tech_yaml() and load_driver_yaml() more than load_yaml() (especially load_plant_yaml() and load_driver_yaml() because those functions use the schema files to populate default values that I always forget to add in).

I also commonly initialize H2I like this:

from h2integrate.core.h2integrate_model import H2IntegrateModel
h2i = H2IntegrateModel(config)
h2i.setup()
h2i.run()

Which makes me a bit hesitant on this kind of usage:

# I'd prefer we don't highlight this usage
import h2integrate as h2i
h2i.load_yaml()

compared to this:

# I'd prefer we show-case this usage
from h2integrate import load_yaml
load_yaml()

Again - these are just thoughts! I would be totally OK if your PR came in as-is (once tests pass).

[johnjasa]

Thanks for your comment, @elenya-grant! I agree that we use h2i as the instantiated object name in a lot of the examples and if we had h2i as the package then it'd probably be confusing for users. I also understand that model has a specific meaning in the OpenMDAO setup, so in the PR body where we have model = H2IntegrateModel() then maybe it's slightly confusing.

So, I think we should be consistent in the naming and don't necessarily have a strong intuition for what's best. Happy to iterate.

[RHammond2]

Hi Rob! I like the changes with importing H2IntegrateModel! I have a few notes just based off my usage but - not asking for changes! Mostly sharing my thoughts.

I think that I personally use the load_plant_yaml(), load_tech_yaml() and load_driver_yaml() more than load_yaml() (especially load_plant_yaml() and load_driver_yaml() because those functions use the schema files to populate default values that I always forget to add in).

I also commonly initialize H2I like this:

from h2integrate.core.h2integrate_model import H2IntegrateModel
h2i = H2IntegrateModel(config)
h2i.setup()
h2i.run()

Which makes me a bit hesitant on this kind of usage:

# I'd prefer we don't highlight this usage
import h2integrate as h2i
h2i.load_yaml()

Thanks for the feedback, @elenya-grant! Fortunately, the only place where I happened to forget about the usage of h2i as the model object or called it model, @johnjasa, was in this PR's write-up, and otherwise only used the from h2integrate import H2IntegrateModel and h2i = H2IntegrateModel() version throughout the updated documentation pages and examples. I'll remove that example workflow from the description, so it's not confusing for anyone else.

For the load_xx_yaml, I will plan to add those to the PR. The reason I did only load_yaml was because I wasn't sure how often the other I/O functions were used since it's not well represented in the examples or documentation.

[johnjasa]

Thanks for this, Rob! I appreciate the quality-of-life improvements you've made and are making to H2I. This is good from my end!

[elenya-grant]

Thanks for those quick changes! Looks great to me! Thanks Rob!

[elenya-grant]

thanks for making these changes! looks great!