Standardize naming conventions

[elenya-grant]

Standardized naming conventions

Have a standardized and documented naming convention for model inputs and outputs given that a lot of logic relies on strings. This would include naming outputs in a specific way that indicate whether the output is a timeseries profile, an aggregated value, or a lifetime estimated value. Also would include naming conventions for not just the primary flow variables, but also the secondary inputs/outputs that may not be 'primary'. For example, the electrolyzer model has a primary timeseries input of an electricity profile and primary timeseries output of hydrogen. The electrolyzer consumes electricity (although may not consume all the electricity input) and consumes water. The consumption of water is not output from the model and not included in any financial calculations. The electrolyzer model could output results for the plant lifetime but does not at the moment.

Also - have a more standardized/automated method of understanding what technologies are connected to what commodities.

Proposed solution

General nomenclature:

• commodity: commodities are produced or stored. A converter produces some commodity, a storage component stores some commodity
• feedstock: feedstock(s) is/are consumed by a technology. A converter may be input one of many feedstock(s) to produce its commodity. This could also refer to ancillary equipment needs. A storage component may have a feedstock if it requires some input other than the storage commodity to operate.
• resource: resource(s) is/are used by a technology. Such as a natural resource, refers to things that would be in plant_config['site'].

Standardized naming convention

Standardized model inputs/outputs could look like introducing a base class for different technology types (converters, storage, transporters, etc). At the very least, this should include documentation. Below is a draft of some possible naming conventions:

Converter Performance Models (commodity to commodity)

• inputs:

  • possible design variables:

    • {technology}_capacity OR n_{technology_modules}
    • size_for_demand ?

  • timeseries:

    • {feedstock_a}_in OR {feedstock_a}_in_profile
    • {feedstock_b}_in OR {feedstock_b}_in_profile
    • {commodity}_demand perhaps? OR {commodity}_demand_profile

  • annual:

  • lifetime: ?

• outputs:
  • timeseries (arrays of length n_timesteps):
    • {commodity}_out: timeseries of commodity production
    • {feedstock_a}_consumption_profile: timeseries of primary feedstock consumed
    • {feedstock_b}_consumption_profile: if used, timeseries of secondary feedstock consumed (only required for hourly prices for secondary feedstock)
  • totals (scalars):
    • max_{commodity}_production_possible: maximum amount of commodity that could be produced over the simulation if the converter was running at its rated capacity for the entire simulation. Should be representative of the converter's rated capacity.
    • total_{commodity}_produced: sum of {commodity}_out
    • capacity_factor: equal to total_{commodity}_produced/max_{commodity}_production_possible. Should be a value between 0 and 1.
    • total_{primary_feedstock}_consumed: sum of {primary_feedstock}_consumption_profile
    • total_{secondary_feedstock}_consumed: sum of {secondary_feedstock}_consumption_profile
  • lifetime (array of length plant_life):
    • annual_{commodity_out}_produced_per_year: can default to [total_{commodity}_produced*(8760*3600)/(n_timesteps*dt)]*plant_life if simulation is not completed for a whole year or [total_{commodity}_produced]*plant_life if simulation is equal to one year.
    • annual_{primary_feedstock}_consumed_per_year (if relevant)
    • annual_{secondary_feedstock}_consumed_per_year (if relevant)
    • time_until_replacement: can default to plant_life. Wouldn't be included in financials unless replacement_cost_percent is included in tech-specific finance parameters under capex.

storage

• inputs:
  • possible design variables:
    • {technology}_charge_rate AND {technology}_{capacity}
  • timeseries:
    • {commodity}_in: available input to use for charging
    • {commodity}_demand: reference signal
  • annual:
  • lifetime:
• outputs:
  • timeseries:
    • {commodity}_out
    • {commodity}_excess
    • {commodity}_missed_load
    • {technology}_SOC
    • {technology}_discharged
    • {technology}_charged
  • annual:
  • lifetime:

Standardized method of connecting technologies and commodities or dealing with models with tech-specific finance models

Add the following dictionaries to supported_models.py:

commodity_to_model_kwargs = {
    "hydrogen": ["electrolyzer", "geoh2", "h2_storage", "wombat", "hydrogen_tank"],
    "steel": ["steel"],
    "methanol": ["methanol", "smr"],
    "ammonia": ["ammonia"],
    "nitrogen": ["air_separator", "asu"],
    "co2": ["doc", "direct_ocean_capture"],
    "electricity": ["wind", "solar", "pv", "river", "hydro", "hopp"],
    "water": ["desal", "desalination"],
}

commodity_to_common_units = {
    "hydrogen": "kg",
    "steel": "t",  # metric ton
    "ammonia": "",
    "nitrogen": "kg",
    "co2": "kg",
    "electricity": "kW*h",
    "water": "kg",
}

independent_financial_models = [
    "steel_cost",
    "stimulated_geoh2_financial",
    "natural_geoh2_financial",
    "methanol_plant_financial",
]

Including some new utility/tool functions like this:

from h2integrate.core.supported_models import commodity_to_model_kwargs


def make_model_kwarg_to_commodity():
    model_kwargs_to_commodity = {}
    for commodity, tech_kwargs in commodity_to_model_kwargs.items():
        model_kwargs_to_commodity.update({tech_kw: commodity for tech_kw in tech_kwargs})
    return model_kwargs_to_commodity


def get_commodities_for_tech_keywords(finance_group_tech_config: dict):
    model_kwargs_to_commodity = make_model_kwarg_to_commodity()
    commodity_types = []
    for tech_name in finance_group_tech_config.keys():
        commodity = [v for k, v in model_kwargs_to_commodity.items() if tech_name.lower() in k]
           
        if len(commodity) > 0:
            commodity_types.append(commodity[0])
        else:
            msg = (
                f"Technology {tech_name} name has unrecognized commodity type."
                "Please check `commodity_to_model_kwargs` in "
                "h2integrate/core/supported_models.py to find valid technology keywords."
            )
            raise ValueError(msg)
    unique_commodity_types = list(set(commodity_types))
    return unique_commodity_types

Then adjusting the logic within h2integrate/core/h2integrate_model.py to not rely on technology names in tech_config (ex: tech_config.keys()) but to instead look at the strings used for the models (ex: tech_config['electrolyzer']['cost_model']['model']). For example, in create_financial_model():

for group_id, tech_configs in financial_groups.items():
     commodity_types = get_commodities_for_tech_keywords(tech_configs)

could replace

for group_id, tech_configs in financial_groups.items():
     if "steel" in tech_configs:
          commodity_types.append("steel")
     if "electrolyzer" in tech_configs:
          commodity_types.append("hydrogen")
     ...

We could also replace some hard-coded logic about either individual finance models or coupled cost/finance models like this:

    if any(c in commodity_types for c in ("steel", "methanol")):
        continue

    # GeoH2 provides own financials
    if "geoh2" in tech_configs:
        continue

to be this:

# Check for individual financial model
coupled_cost_finance = any(
    tech_info.get("cost_model", {}).get("model", False) in independent_financial_models
    for tech, tech_info in tech_configs.items()
)
individual_finance = any(
    tech_info.get("financial_model", {}).get("model", False)
    in independent_financial_models
    for tech, tech_info in tech_configs.items()
)
if coupled_cost_finance or individual_finance:
    continue

Alternatives considered

Additional context

This was partially discussed/addressed in PR #198.
Related to Issue #231

[elenya-grant]

for converter inputs/outputs - I wonder if there should be a difference between variable energy producing technologies (wind, solar-PV, etc) vs "firm power" sources (natural gas, coal, oil). Could we see there ever being a case where (for example) we want to either a) size the wind farm based on some electricity demand or b) operate the wind farm to achieve some electricity demand?

[kbrunik]

I think something top of mind for me is resource vs feedstock vs commodity vs co-product and if these are the best terms to use. Sometimes the distinction between the categories are rather gray.

It does seem important to track if an input is variable or you can get X amount you desire - hence a distinction between resource and feedstock. Sometimes you can have the input be a commodity from one model or a feedstock that's external to the system - are we able to flexibly handle these cases or a mix of feedstock and commodity (i.e., a hybrid grid case).

I also think we should standardize how we refer to a converter. Is it based on primary commodity produced (e.g., methanol)? Input (feedstock or resource) to the converter (e.g., wind)?

[elenya-grant]

I think something top of mind for me is resource vs feedstock vs commodity vs co-product and if these are the best terms to use. Sometimes the distinction between the categories are rather gray.

It does seem important to track if an input is variable or you can get X amount you desire - hence a distinction between resource and feedstock. Sometimes you can have the input be a commodity from one model or a feedstock that's external to the system - are we able to flexibly handle these cases or a mix of feedstock and commodity (i.e., a hybrid grid case).

I also think we should standardize how we refer to a converter. Is it based on primary commodity produced (e.g., methanol)? Input (feedstock or resource) to the converter (e.g., wind)?

I agree - I do think that feedstocks (like resource) could have limited availability (for example - like what if an 'electricity feedstock' from the electric grid has no availability for some hours because of an outage? Or - what if there's limited 'availability' of the feedstock throughout the year (limited water supply in summer maybe?)). I think that PR #221 partially addresses being able to handle a mix of feedstock and a commodity and being able to handle a mix of the same feedstocks that come from different sources (for example, water coming from Denver water supply vs water coming from boulder water supply).

Regarding the distinction between resource and feedstock - I also think there's a difference in converters related to this. Some converters are resource-to-commodity converters (wind, solar-pv) while others are commodity-to-commodity converters (electrolyzer). I originally had two sections for converters to highlight this because I think there's inherently some differences in what functionality, inputs, and outputs a converter model could/should have depending on whether its resource-based or feedstock-based.

I also think that a distinction between resource and feedstock could be that a feedstock is consumed whereas a resource is used (I can't think of a better word). An electrolyzer consumes water and electricity but a wind turbine does not consume wind speed (it uses wind).

On your last point - I think that we should refer to converters based on the technology rather than the primary commodity or input feedstock or input resource, at least in supported_models. I.e., the steel model should be electric_arc_furnance. We have two technologies that can produce hydrogen (electrolyzer and geo-H2). These could both live in h2integrate/converters/hydrogen/ but the models should be named with respect to the technology. I think this could get a bit weird if we want to introduce something like a fuel cell because it's an electricity producing technology but also seems closer to an electrolyzer than the other electricity producing technologies. This would also likely require making sure that it's very clear what technology produces what commodity. I think I started going down a bit of a rabbit hole here so - I'll leave it here at converters should be referred to based on their technology

[kbrunik]

I think it makes sense to refer to the converter as the technology but some things might have the same shared base class (i.e., a hydrogen electrolyzer base class for alkaline and pem). Should they then live in a shared directory? and if so how should that directory be named - based on commodity produced? Would we have another nested directory for electrolyzers that's at the same level as the geo-h2?

[johnjasa]

I also think that a distinction between resource and feedstock could be that a feedstock is consumed whereas a resource is used (I can't think of a better word). An electrolyzer consumes water and electricity but a wind turbine does not consume wind speed (it uses wind).

I like this distinction a lot! Really succinctly said.

Relatedly, I think a feedstock could exist for any commodity, i.e. you have a feedstock of hydrogen, or water, or anything you want. I think we should view feedstocks as a source term for commodities.

[johnjasa]

Now I'll comment more generally on this issue, acknowledging that Elenya and have been chatting back-and-forth a good amount already, but I want to capture my thoughts here for others' benefit. I mostly support the suggestions in this issue and could see a multi-step approach to implementation.

I see the steps as:

• agreeing on a naming scheme for converters, storage, commodities, etc
• documenting that naming scheme explicitly in the docs
• updating all existing code to adopt those schemes
• updating h2integrate_model.py and supported_models.py to use logic from the new naming scheme in an intelligent way (like the lower body of the issue)

I'd suggest doing the first step as part of this issue and together as a group, then do the next two steps as one PR, and the last one as another PR.

Now for a potpourri of thoughts:

• I like _consumption_profile
• I dislike the notion of primary vs secondary feedstocks. I think all feedstocks should be treated the same. And in reality, a feedstock is just a <commodity>_in.
• For the logic in h2integrate_model that involves the new names, I'd want to make sure it's abundantly clear what's going on. Even if it takes more lines or code or verbosity, I think it's worth making that extremely clear so folks can easily see what filters are being applied. This is because when we add the additional layer of abstraction of having mapping dictionaries defined in supported_models, we'd want to minimize the amount of back-and-forth between files or translations between mappings that users would have to do to understand the logic
• Nitpicky: I'd want to make the names of the supported_models dictionaries more clear; maybe models_that_output_commodity_mapping and commodity_units or something else? Open to discussion here