Tracking Changes in GDM - Grid-Data-Models

The grid-data-models (GDM) package includes comprehensive support for modeling tracked changes within a distribution system. This functionality allows users to effectively manage changes to a base grid model, enabling dynamic analysis and scenario planning. All tracked changes are built upon a single base GDM model, ensuring a consistent foundation for analysis. The system allows for edits, additions, and deletions to a base GDM model at specific timestamps. Each modification is tracked and stored, providing a clear history of changes over time.

We will use the gdmloader package to first download a sample GDM model.

from gdm.systems.distribution import DistributionSystem
from gdmloader.constants import GCS_CASE_SOURCE
from gdmloader.source import SystemLoader

loader = SystemLoader()
loader.add_source(GCS_CASE_SOURCE)
base_model: DistributionSystem = loader.load_dataset(
    DistributionSystem, GCS_CASE_SOURCE.name, "three_feeder_switch"
)
base_model.auto_add_composed_components = True
base_model.info()

Next, we will build a catalog of components that will serve as an equipment library for additions to the base model and map to temporal changes in the base model. In this catalog, we add two example models with fixed UUIDs that will later be used for temporal mapping.

from gdm.systems.distribution.equipment import LoadEquipment
from uuid import UUID

catalog = DistributionSystem(auto_add_composed_components=True)
load_equipment = LoadEquipment.example().model_copy(
    update={
        "uuid": UUID("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"),
        "name": "added_phase_load_model",
    }
)
catalog.add_component(load_equipment)

From the model, we get a line model and two load models. These components will be modified to reflect changes in the base model.

from gdm.systems.distribution.components import DistributionLoad, MatrixImpedanceBranch

line = next(base_model.get_components(MatrixImpedanceBranch))
load1, load2 = list(base_model.get_components(DistributionLoad))[:2]

Each TrackedChange object has a scenario name. Additionally, this object may have a date field that can be used to filter changes based on specific dates. Each TrackedChange includes a list of system additions, edits, and deletions to be applied on the specified date.

Additions: This is a list attribute that holds the UUIDs of the components added in this modification. These UUIDs should exist in the catalog.
Deletions: This is a list attribute that holds the UUIDs of the components deleted in this modification. These UUIDs should exist in the base system model.
Edits: This is a list attribute that holds the PropertyEdit objects representing the edits made in this modification. PropertyEdit requires the name of the property to be edited, the new value of the property, and the component_uuid that maps to the modified component.

from gdm.tracked_changes import PropertyEdit, TrackedChange
from gdm.quantities import Distance

system_changes = [
    TrackedChange(
        scenario_name="scenario_1",
        timestamp="2022-01-01 00:00:00",
        edits=[
            PropertyEdit(
                component_uuid=line.uuid,
                name="length",
                value=Distance(100, "meter"),
            )
        ],
    ),
    TrackedChange(
        scenario_name="scenario_1",
        timestamp="2023-01-01 00:00:00",
        additions=["aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"],
    ),
    TrackedChange(
        scenario_name="scenario_1",
        timestamp="2024-01-01 00:00:00",
        deletions=[load1.uuid],
    ),
    TrackedChange(
        scenario_name="scenario_2",
        timestamp="2025-01-01 00:00:00",
        deletions=[load2.uuid],
    ),
]

Next, we use filter_tracked_changes_by_name_and_date to filter a list of tracked changes based on a specific scenario name and / or update date.

from gdm.tracked_changes import filter_tracked_changes_by_name_and_date
from datetime import datetime

tracked_changes = filter_tracked_changes_by_name_and_date(
    system_changes,
    scenario_name="scenario_1",
    timestamp=datetime.strptime("2022-1-1", "%Y-%m-%d"),
)

Finally, we use functions provided by the GDM library to apply changes to the base distribution system model.

from gdm.tracked_changes import apply_updates_to_system

new_system = apply_updates_to_system(
    tracked_changes=tracked_changes, system=base_model, catalog=catalog
)

new_system.info()

tracked_changes = filter_tracked_changes_by_name_and_date(
    system_changes,
    scenario_name="scenario_1",
)
print(tracked_changes)
new_system = apply_updates_to_system(
    tracked_changes=tracked_changes, system=base_model, catalog=catalog
)
new_system.info()

[TrackedChange(scenario_name='scenario_1', update_date=datetime.date(2022, 1, 1), additions=[], edits=[PropertyEdit(name='length', value=<Quantity(100, 'meter')>, component_uuid=UUID('8f98b0f7-e4ff-4ac4-a4c7-d76b9d7a15fa'))], deletions=[]), TrackedChange(scenario_name='scenario_1', update_date=datetime.date(2023, 1, 1), additions=[UUID('aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa')], edits=[], deletions=[]), TrackedChange(scenario_name='scenario_1', update_date=datetime.date(2024, 1, 1), additions=[], edits=[], deletions=[UUID('2aac110f-d0b7-4db0-b356-6bd7d6f3487b')])]