Supplemental Attributes

While the ext field is a mechanism for adding arbitrary metadata. PowerSystems.jl, has moved towards a more structured and formalized way of handling supplemental data using SupplementalAttribute structs. This is designed to store metadata in a more organized fashion than a generic dictionary. These attributes are intended to be attached to a Component types.

Supplemmental attributes can be shared between components or have 1-1 relationships. This is particularly useful to represent components in the same geographic location or outages for multiple components. Conversely, components can contain many attributes.

flowchart LR A["Attribute A"] --> B["Component 1"] A --> C["Component2"] D["Attribute B"] --> C["Component 2"] E["Attribute C"] --> F["Component 3"]

Supplemental attributes can also contain timeseries in the same fashion that a component can allowing the user to model time varying attributes like outage time series or weather dependent probabilities. See the section Working with Time Series Data for details on time series handling.

Getting the attributes in a system

You can retrieve the attributes in a system using the function get_supplemental_attributes. You must pass a supplemental attribute type, which can be concrete or abstract. If you pass an abstract type, all concrete types that are subtypes of the abstract type will be returned.

for outage in get_supplemental_attributes(FixedForcedOutage, system)
    @show summary(outage)
end

You can optionally pass a filter function to reduce the returned attributes. This example will return only FixedForcedOutage instances that have a mean time to recovery greater than or equal to 0.5.

for outage in get_supplemental_attributes(
    x -> get_mean_time_to_recovery(x) >= 0.5,
    FixedForcedOutage,
    system,
)
    @show summary(outage)
end

Getting the attributes associated with a component

You can retrieve the attributes associated with a component using the function get_supplemental_attributes. This method signatures are identical to the versions above that operate on a system; just swap the system for a component.

You must pass a supplemental attribute type, which can be concrete or abstract. If you pass an abstract type, all concrete types that are subtypes of the abstract type will be returned.

gen1 = get_component(ThermalStandard, system, "gen1")
for outage in get_supplemental_attributes(FixedForcedOutage, gen)
    @show summary(outage)
end

You can optionally pass a filter function to reduce the returned attributes. This example will return only FixedForcedOutage instances that have a mean time to recovery greater than or equal to 0.5.

for outage in get_supplemental_attributes(
    x -> get_mean_time_to_recovery(x) >= 0.5,
    gen,
    FixedForcedOutage,
)
    @show summary(outage)
end

Getting the attributes associated with a component type

You can retrieve the attributes associated with any component of a given type using the function get_associated_supplemental_attributes. If one attribute is attached to multiple components of the given type, it will still only appear once in the result.

Get all the attributes associated with all components of a given type.

for outage in get_associated_supplemental_attributes(system, ThermalStandard)
    @show summary(outage)
end

Same as #1, but filter the results by attribute type, which can be concrete or abstract.

for outage in
    get_associated_supplemental_attributes(
    system,
    ThermalStandard;
    attribute_type = FixedForcedOutage,
)
    @show summary(outage)
end

Getting the components associated with an attribute

You can retrieve the components associated with a single supplemental attribute using the function get_associated_components.

Get all components associated with a single supplemental attribute.

outage = first(get_supplemental_attributes(FixedForcedOutage, system))
for component in get_associated_components(system, outage)
    @show summary(component)
end

Same as #1, but filter the results by component type, which can be concrete or abstract.

outage = first(get_supplemental_attributes(FixedForcedOutage, system))
for component in get_associated_components(system, outage; component_type = ThermalStandard)
    @show summary(component)
end

Getting the components associated with an attribute type

You can retrieve the components associated with any supplemental attribute of a given type using the function get_associated_components.

Get all components associated with any supplemental attribute of a given type.

for component in get_associated_components(system, FixedForcedOutage)
    @show summary(component)
end

Same as #1, but filter the results by component type, which can be concrete or abstract.

for component in
    get_associated_components(system, FixedForcedOutage; component_type = ThermalStandard)
    @show summary(component)
end

Getting component / supplemental attribute pairs

The function get_component_supplemental_attribute_pairs returns a vector of component / supplemental attribute pairs based on types and optional filters. This can be more efficient than double for loops that iterate over components and their associated attributes independently.

for (gen, outage) in get_component_supplemental_attribute_pairs(
    ThermalStandard,
    FixedForcedOutage,
    system,
)
    @show summary(gen) summary(outage)
end