WIP: Helper Methods in SLC BaseClass

[elenya-grant]

Helper Methods in SLC BaseClass

Added some hopefully useful helper methods in the SLC baseclass and intended to resolve Issue #741. I also view this as a pre-requisite to tackling Issue #747. These methods are intended to help future control development be more easily expanded to varying system architectures and make them more friendly to multi-commodity systems (systems that contain converters such as an electrolyzer or Haber Bosch system).

These methods probably have their limitations - but those will be best found and addressed as we test them with more complex system architectures.

This PR also includes some updates to the DemandFollowingControl to show-case how to use some of the methods in the SLC baseclass. I am still working on adding all the necessary doc-strings and cleaning up the code.

Please do not yet push any changes to this branch.

Section 1: Type of Contribution

• Feature Enhancement
  • Framework
  • New Model
  • Updated Model
  • Tools/Utilities
  • Other (please describe):
• 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:

• Split out the new example into two separate folders
• Finish adding doc strings to the methods in the SLC baseclass
• Add another example or test with using non-averaged conversion factors
• Finish cleaning-up SLC baseclass

Type of Reviewer Feedback Requested (on Draft PR)

Structural feedback:

Implementation feedback:

• Should methods that are only called in _post_setup_multi_commodity() be updated to have the format __method_name__? Or no?
• Should methods that are called from the DemandFollowingControl class be formatted as _method_name or just method_name?

Other feedback:

• Any tips on formatting some pretty detailed variables in docstrings? Some of the doc strings are not fun to format and I'm struggling to explain some of the format of the input and output variables well. A lot of variables are dictionaries with lists as a tuple of strings and values that are equally as complex. For example, one variable, converter_upstreams, is a dictionary like:

converter_upstreams[("electricity", "electrolyzer")] = {"solar", "battery", "wind"}

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

Intended to resolve Issue #741

Section 5: Impacted Areas of the Software

Section 5.1: New Files

• h2integrate/control/control_strategies/system_level/test/test_slc_baseclass.py: new test file for some methods introduced in the SLC baseclass

Section 5.2: Modified Files

• h2integrate/core/h2integrate_model.py._classify_slc_technologies(): updated so that other inputs (such as tech_control_classifiers and storage_techs_to_control) only include technologies that are upstream of the demand component.
• h2integrate/control/control_strategies/system_level/demand_following_control.py
  • DemandFollowingControlConfig: new configuration class for the demand following controller
  • DemandFollowingControl
    • Basically wrapped a lot of what was in compute() in a method named get_setpoints_for_commodity_subset()
    • get_conversion_factors(): new method
    • compute(): changed a bunch

Many new methods were added to h2integrate/control/control_strategies/system_level/system_level_control_base.py. Below is a summary of the major new methods and the other methods that they use

• _post_setup_multi_commodity(): called in setup() and uses the below methods
  • _find_converter_techs: only called during _post_setup_multi_commodity() and uses the below methods
    • _get_commodity_for_tech: called elsewhere - not specific to this method
    • get_upstream_techs_for_commodity: called elsewhere - not specific to this method
  • _find_demand_tech_group: only called during _post_setup_multi_commodity()
    • _check_demand_tech_group_connections:
    • dict_values_to_flat_list: called elsewhere - not specific to the parent method
  • _find_group_for_non_input_techs: only called during _post_setup_multi_commodity()
  • _make_conversion_factor_recipes: only called during _post_setup_multi_commodity()
  • sets attributes:
    • simple_graph
    • non_converter_conversion_factor_keys:
    • grouped_techs:
    • converters:
    • converter_upstreams:
    • converter_tech_names: could perhaps remove
    • conversion_recipes:

New methods in the SLC baseclass that are used by the DemandFollowingControl.compute() method are:

• _get_techs_to_demand_from_recipe
• _get_conversion_from_recipe
• get_converter_capacity_conversion_ratio
• get_converter_conversion_ratio

Section 6: Additional Supporting Information

Section 7: Test Results, if applicable

Section 8 (Optional): New Model Checklist

• Model Structure:
  • Follows established naming conventions outlined in docs/developer_guide/coding_guidelines.md
  • Used attrs class to define the Config to load in attributes for the model
    • If applicable: inherit from BaseConfig or CostModelBaseConfig
  • Added: initialize() method, setup() method, compute() method
    • If applicable: inherit from CostModelBaseClass
• Integration: Model has been properly integrated into H2Integrate
  • Added to supported_models.py
  • If a new commodity_type is added, update create_financial_model in h2integrate_model.py
• Tests: Unit tests have been added for the new model
  • Pytest-style unit tests
  • Unit tests are in a "test" folder within the folder a new model was added to
  • If applicable add integration tests
• Example: If applicable, a working example demonstrating the new model has been created
  • Input file comments
  • Run file comments
  • Example has been tested and runs successfully in test_all_examples.py
• Documentation:
  • Write docstrings using the Google style
  • Model added to the main models list in docs/user_guide/model_overview.md
    • Model documentation page added to the appropriate docs/ section
    • <model_name>.md is added to the _toc.yml
  • Run generate_class_hierarchy.py to update the class hierarchy diagram in docs/developer_guide/class_structure.md