Working with GDMLOADER#
GDMLOADER is a helper package designed to simplify downloading and loading example distribution system models into your workspace. It provides convenience functions for retrieving prebuilt test cases, allowing you to focus on using the models rather than building them from scratch.
First, we will add sources to SystemLoader and explore the available test cases.
Note
Public cases are currently hosted on Google Cloud. However, GDMLOADER allows users to manage private sources (not covered in this tutorial). Contact the GDM team if you are interested in learning more.
Setting Up Data Source#
from gdmloader.constants import GCS_CASE_SOURCE
from gdmloader.source import SystemLoader
gdm_loader = SystemLoader()
gdm_loader.add_source(GCS_CASE_SOURCE)
gdm_loader.show_sources()
┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Name ┃ URL ┃ ┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ gdm_data │ https://storage.googleapis.com/gdm_data │ └──────────┴─────────────────────────────────────────┘
Viewing Available Models#
Sources are designed to support all systems in GDM, including DistributionSystem, CatalogSystem, and StructuralSystem. You can view all available models hosted by the source using the show_dataset_by_source method.
gdm_loader.show_dataset_by_source("gdm_data")
System: CatalogSystem ┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓ ┃ name ┃ description ┃ contributor ┃ contributed_date ┃ ┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩ │ gdm_catalog │ Equipment catalog for DistributionSystem models contains over │ Aadil Latif │ 2024-12-04 │ │ │ 25000 models for BareConductorEquipment, CapacitorEquipment, │ │ │ │ │ ConcentricCableEquipment, DistributionTransformerEquipment, │ │ │ │ │ InverterEquipment and SolarEquipment │ │ │ └─────────────┴──────────────────────────────────────────────────────────────────┴─────────────┴──────────────────┘
System: CatalogSyst em versions ┏━━━━━━━━━┓ ┃ Version ┃ ┡━━━━━━━━━┩ │ 1_3_1 │ │ 1_3_2 │ │ 1_3_3 │ │ 1_4_0 │ │ 2_0_0 │ │ 2_0_1 │ └─────────┘
System: DistributionSystem ┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓ ┃ name ┃ description ┃ contributor ┃ contributed_… ┃ has_geo_coord… ┃ has_time_ser… ┃ has_split_pha… ┃ ┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩ │ three_feeder… │ Three feeder │ Abodh Poudyal │ 2024-12-03 │ False │ False │ False │ │ │ test case │ │ │ │ │ │ │ │ with │ │ │ │ │ │ │ │ switches. │ │ │ │ │ │ │ three_feeder… │ Three feeder │ Abodh Poudyal │ 2024-12-13 │ False │ False │ False │ │ │ test case │ │ │ │ │ │ │ │ with │ │ │ │ │ │ │ │ non-identical │ │ │ │ │ │ │ │ feeder load │ │ │ │ │ │ │ │ and switches. │ │ │ │ │ │ │ three_feeder… │ Three feeder │ Abodh Poudyal │ 2024-12-13 │ False │ False │ False │ │ │ test case │ │ │ │ │ │ │ │ with │ │ │ │ │ │ │ │ non-identical │ │ │ │ │ │ │ │ feeder load │ │ │ │ │ │ │ │ without tie │ │ │ │ │ │ │ │ switches. │ │ │ │ │ │ │ p5r │ Slightly │ Kapil Duwadi │ 2024-12-03 │ True │ True │ True │ │ │ modified │ │ │ │ │ │ │ │ version of │ │ │ │ │ │ │ │ sub feeder │ │ │ │ │ │ │ │ within `P5R` │ │ │ │ │ │ │ │ region │ │ │ │ │ │ │ │ SMARTDS data │ │ │ │ │ │ │ │ from `SFO` │ │ │ │ │ │ │ │ area. Added │ │ │ │ │ │ │ │ PVsystem. │ │ │ │ │ │ │ three_feeder… │ Three feeder │ Abodh Poudyal │ 2024-02-19 │ False │ False │ False │ │ │ test case │ │ │ │ │ │ │ │ with │ │ │ │ │ │ │ │ non-identical │ │ │ │ │ │ │ │ feeder load │ │ │ │ │ │ │ │ without tie │ │ │ │ │ │ │ │ switches. │ │ │ │ │ │ │ three_feeder… │ Three feeder │ Abodh Poudyal │ 2024-02-19 │ False │ False │ False │ │ │ test case │ │ │ │ │ │ │ │ with │ │ │ │ │ │ │ │ non-identical │ │ │ │ │ │ │ │ feeder load │ │ │ │ │ │ │ │ without tie │ │ │ │ │ │ │ │ switches. │ │ │ │ │ │ │ testcasev1 │ Simple test │ Kapil Duwadi │ 2024-12-03 │ False │ False │ False │ │ │ case for │ │ │ │ │ │ │ │ CADET │ │ │ │ │ │ │ │ testing. │ │ │ │ │ │ │ p1rhs7_1247 │ Medium sized │ Aadil Latif │ 2025-05-07 │ True │ False │ True │ │ │ Smart-DS │ │ │ │ │ │ │ │ model for │ │ │ │ │ │ │ │ testing │ │ │ │ │ │ └───────────────┴───────────────┴───────────────┴───────────────┴────────────────┴───────────────┴────────────────┘
System: Distributio nSystem versions ┏━━━━━━━━━┓ ┃ Version ┃ ┡━━━━━━━━━┩ │ 1_2_0 │ │ 1_3_0 │ │ 1_3_1 │ │ 1_3_2 │ │ 1_3_3 │ │ 1_4_0 │ │ 2_0_0 │ │ 2_0_1 │ └─────────┘
Alternatively, models for a specific system can be viewed using the show_dataset_by_system method.
gdm_loader.show_dataset_by_system("DistributionSystem", "gdm_data")
System: DistributionSystem ┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓ ┃ name ┃ description ┃ contributor ┃ contributed_… ┃ has_geo_coord… ┃ has_time_ser… ┃ has_split_pha… ┃ ┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩ │ three_feeder… │ Three feeder │ Abodh Poudyal │ 2024-12-03 │ False │ False │ False │ │ │ test case │ │ │ │ │ │ │ │ with │ │ │ │ │ │ │ │ switches. │ │ │ │ │ │ │ three_feeder… │ Three feeder │ Abodh Poudyal │ 2024-12-13 │ False │ False │ False │ │ │ test case │ │ │ │ │ │ │ │ with │ │ │ │ │ │ │ │ non-identical │ │ │ │ │ │ │ │ feeder load │ │ │ │ │ │ │ │ and switches. │ │ │ │ │ │ │ three_feeder… │ Three feeder │ Abodh Poudyal │ 2024-12-13 │ False │ False │ False │ │ │ test case │ │ │ │ │ │ │ │ with │ │ │ │ │ │ │ │ non-identical │ │ │ │ │ │ │ │ feeder load │ │ │ │ │ │ │ │ without tie │ │ │ │ │ │ │ │ switches. │ │ │ │ │ │ │ p5r │ Slightly │ Kapil Duwadi │ 2024-12-03 │ True │ True │ True │ │ │ modified │ │ │ │ │ │ │ │ version of │ │ │ │ │ │ │ │ sub feeder │ │ │ │ │ │ │ │ within `P5R` │ │ │ │ │ │ │ │ region │ │ │ │ │ │ │ │ SMARTDS data │ │ │ │ │ │ │ │ from `SFO` │ │ │ │ │ │ │ │ area. Added │ │ │ │ │ │ │ │ PVsystem. │ │ │ │ │ │ │ three_feeder… │ Three feeder │ Abodh Poudyal │ 2024-02-19 │ False │ False │ False │ │ │ test case │ │ │ │ │ │ │ │ with │ │ │ │ │ │ │ │ non-identical │ │ │ │ │ │ │ │ feeder load │ │ │ │ │ │ │ │ without tie │ │ │ │ │ │ │ │ switches. │ │ │ │ │ │ │ three_feeder… │ Three feeder │ Abodh Poudyal │ 2024-02-19 │ False │ False │ False │ │ │ test case │ │ │ │ │ │ │ │ with │ │ │ │ │ │ │ │ non-identical │ │ │ │ │ │ │ │ feeder load │ │ │ │ │ │ │ │ without tie │ │ │ │ │ │ │ │ switches. │ │ │ │ │ │ │ testcasev1 │ Simple test │ Kapil Duwadi │ 2024-12-03 │ False │ False │ False │ │ │ case for │ │ │ │ │ │ │ │ CADET │ │ │ │ │ │ │ │ testing. │ │ │ │ │ │ │ p1rhs7_1247 │ Medium sized │ Aadil Latif │ 2025-05-07 │ True │ False │ True │ │ │ Smart-DS │ │ │ │ │ │ │ │ model for │ │ │ │ │ │ │ │ testing │ │ │ │ │ │ └───────────────┴───────────────┴───────────────┴───────────────┴────────────────┴───────────────┴────────────────┘
System: Distributio nSystem versions ┏━━━━━━━━━┓ ┃ Version ┃ ┡━━━━━━━━━┩ │ 1_2_0 │ │ 1_3_0 │ │ 1_3_1 │ │ 1_3_2 │ │ 1_3_3 │ │ 1_4_0 │ │ 2_0_0 │ │ 2_0_1 │ └─────────┘
Downloading case files#
Users can download specific models using the load_dataset method.
Note
By default, gdmloader downloads the model version that corresponds to the installed GDM version. However, users can specify a different version they wish to download.
from gdm.distribution import DistributionSystem
distribution_system: DistributionSystem = gdm_loader.load_dataset(
system_type=DistributionSystem,
source_name="gdm_data",
dataset_name="p5r",
#version="1_4_0" # Optional. By default model matching your GDM installation is returned
)
/opt/hostedtoolcache/Python/3.12.10/x64/lib/python3.12/site-packages/pydantic/_internal/_generate_schema.py:502: UserWarning: Ellipsis is not a Python type (it may be an instance of an object), Pydantic will allow any object with no validation since we cannot even enforce that the input is an instance of the given type. To get rid of this error wrap the type with `pydantic.SkipValidation`.
warn(
Downloaded models are cached on the local machine for improved performance. Users can view system information using the info method on the system instance.
distribution_system.name = "P5R"
distribution_system.info()
System ┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓ ┃ Property ┃ Value ┃ ┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩ │ System name │ P5R │ │ Data format version │ 2.0.1 │ │ Components attached │ 60 │ │ Time Series attached │ 5 │ │ Description │ │ └──────────────────────┴───────┘
Component Information ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓ ┃ Type ┃ Count ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩ │ DistributionBus │ 10 │ │ DistributionLoad │ 2 │ │ DistributionSolar │ 2 │ │ DistributionTransformer │ 2 │ │ DistributionTransformerEquipment │ 1 │ │ DistributionVoltageSource │ 1 │ │ InverterEquipment │ 2 │ │ LoadEquipment │ 2 │ │ Location │ 10 │ │ MatrixImpedanceBranch │ 6 │ │ MatrixImpedanceBranchEquipment │ 2 │ │ MatrixImpedanceSwitch │ 1 │ │ MatrixImpedanceSwitchEquipment │ 1 │ │ PhaseLoadEquipment │ 6 │ │ PhaseVoltageSourceEquipment │ 3 │ │ SolarEquipment │ 2 │ │ VoltageLimitSet │ 4 │ │ VoltageSourceEquipment │ 1 │ │ WindingEquipment │ 2 │ └──────────────────────────────────┴───────┘
Time Series Summary ┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━ ┃ ┃ ┃ ┃ ┃ ┃ No. Components ┃ Component Type ┃ Time Series Type ┃ Initial time ┃ Resolution ┃ No. Components ┃ with Time Series ┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━ │ DistributionLoad │ SingleTimeSeries │ 2020-01-01 00:00:00 │ 0:15:00 │ 2 │ 4 │ DistributionSolar │ SingleTimeSeries │ 2020-01-01 00:00:00 │ 0:15:00 │ 2 │ 2 └──────────────────────┴──────────────────┴─────────────────────┴────────────┴────────────────┴────────────────────