Summary
Add a tags: list[str] field to the main element dataclasses so users can attach arbitrary labels for custom grouping, filtering, and post-processing — without overloading id or short_id.
Motivation
Users often need to group or filter elements by criteria orthogonal to the energy model (e.g. "renewable", "site_north", "curtailable"). Currently there's no standard place for this metadata. Tags provide a lightweight, flexible mechanism that the library preserves but doesn't interpret.
Design
Tagged elements
Add tags: list[str] = field(default_factory=list) to:
FlowEffectStorageCarrierPortConverter
No deduplication — the library doesn't interpret tags, so duplicates are harmless.
No propagation
Tags do not propagate from components to child flows. Each element is tagged independently.
Preservation
Tags must survive through the full pipeline (elements → ModelData → Result) and round-trip through serialization.
Example usage
solar = Flow("elec", tags=["renewable", "curtailable"])
gas = Flow("gas", tags=["fossil"])
grid = Port("grid", exports=[solar, gas], tags=["external"])
# Post-processing:
renewable_flows = [f for f in all_flows if "renewable" in f.tags]Tasks
Future enhancements
Intentionally deferred to keep the initial implementation simple:
- Tag propagation from components to flows — e.g.
Port(tags=["x"]) automatically adds "x" to all child flows. Deferred because it adds complexity around lifecycle (what if tags are added after __post_init__?), requires parent references or explicit add_tag/remove_tag methods, and interacts with Storage's charge/discharge renaming.
- Deduplication — could validate uniqueness on construction. Not needed yet since the library doesn't interpret tags.
- Key-value tags —
dict[str, str] or structured tags. list[str] covers most use cases; users can encode structure as "key:value" strings if needed.
Thoughts
- How to store tags in xarray Datasets is an open question — non-dimension coordinates are robust but awkward for list data; attrs are simpler but can be silently dropped by xarray operations. Decide during implementation.
- Tags on
Carrier might be less useful than on the other elements — worth including for consistency, but could be dropped if it adds friction.
Summary
Add a
tags: list[str]field to the main element dataclasses so users can attach arbitrary labels for custom grouping, filtering, and post-processing — without overloadingidorshort_id.Motivation
Users often need to group or filter elements by criteria orthogonal to the energy model (e.g.
"renewable","site_north","curtailable"). Currently there's no standard place for this metadata. Tags provide a lightweight, flexible mechanism that the library preserves but doesn't interpret.Design
Tagged elements
Add
tags: list[str] = field(default_factory=list)to:FlowEffectStorageCarrierPortConverterNo deduplication — the library doesn't interpret tags, so duplicates are harmless.
No propagation
Tags do not propagate from components to child flows. Each element is tagged independently.
Preservation
Tags must survive through the full pipeline (elements → ModelData → Result) and round-trip through serialization.
Example usage
Tasks
tagsfield toFlow,Effect,Storage,Carrier,Port,ConverterFuture enhancements
Intentionally deferred to keep the initial implementation simple:
Port(tags=["x"])automatically adds"x"to all child flows. Deferred because it adds complexity around lifecycle (what if tags are added after__post_init__?), requires parent references or explicitadd_tag/remove_tagmethods, and interacts with Storage's charge/discharge renaming.dict[str, str]or structured tags.list[str]covers most use cases; users can encode structure as"key:value"strings if needed.Thoughts
Carriermight be less useful than on the other elements — worth including for consistency, but could be dropped if it adds friction.