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: CatalogSystem versions ┏━━━━━━━━━━━━━┓ ┃ Version ┃ ┡━━━━━━━━━━━━━┩ │ 1_3_1 │ │ 1_3_2 │ │ 1_3_3 │ │ 1_4_0 │ │ 2_0_0 │ │ 2_0_1 │ │ 2_1_0 │ │ 2_1_2 │ │ 2_1_3 │ │ 2_1_4 │ │ 2_1_5 │ │ 2_1_5_post1 │ │ 2_2_0 │ └─────────────┘
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: DistributionSys tem 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 │ │ 2_1_0 │ │ 2_1_2 │ │ 2_1_3 │ │ 2_1_4 │ │ 2_1_5 │ │ 2_1_5_post1 │ │ 2_2_0 │ └─────────────┘
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: DistributionSys tem 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 │ │ 2_1_0 │ │ 2_1_2 │ │ 2_1_3 │ │ 2_1_4 │ │ 2_1_5 │ │ 2_1_5_post1 │ │ 2_2_0 │ └─────────────┘
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",
)
---------------------------------------------------------------------------
FileNotFoundError Traceback (most recent call last)
File /opt/hostedtoolcache/Python/3.12.12/x64/lib/python3.12/site-packages/gdmloader/source.py:124, in SystemLoader.load_dataset(self, system_type, source_name, dataset_name, version)
123 try:
--> 124 source.fs.get(
125 remote_folder,
126 str(local_folder),
127 recursive=True,
128 )
129 except FileNotFoundError:
File /opt/hostedtoolcache/Python/3.12.12/x64/lib/python3.12/site-packages/fsspec/asyn.py:118, in sync_wrapper.<locals>.wrapper(*args, **kwargs)
117 self = obj or args[0]
--> 118 return sync(self.loop, func, *args, **kwargs)
File /opt/hostedtoolcache/Python/3.12.12/x64/lib/python3.12/site-packages/fsspec/asyn.py:103, in sync(loop, func, timeout, *args, **kwargs)
102 elif isinstance(return_result, BaseException):
--> 103 raise return_result
104 else:
File /opt/hostedtoolcache/Python/3.12.12/x64/lib/python3.12/site-packages/fsspec/asyn.py:56, in _runner(event, coro, result, timeout)
55 try:
---> 56 result[0] = await coro
57 except Exception as ex:
File /opt/hostedtoolcache/Python/3.12.12/x64/lib/python3.12/site-packages/fsspec/asyn.py:645, in AsyncFileSystem._get(self, rpath, lpath, recursive, callback, maxdepth, **kwargs)
644 rpath = self._strip_protocol(rpath)
--> 645 rpaths = await self._expand_path(
646 rpath, recursive=recursive, maxdepth=maxdepth
647 )
648 if source_is_str and (not recursive or maxdepth is not None):
649 # Non-recursive glob does not copy directories
File /opt/hostedtoolcache/Python/3.12.12/x64/lib/python3.12/site-packages/fsspec/asyn.py:883, in AsyncFileSystem._expand_path(self, path, recursive, maxdepth)
882 if isinstance(path, str):
--> 883 out = await self._expand_path([path], recursive, maxdepth)
884 else:
File /opt/hostedtoolcache/Python/3.12.12/x64/lib/python3.12/site-packages/fsspec/asyn.py:912, in AsyncFileSystem._expand_path(self, path, recursive, maxdepth)
911 if not out:
--> 912 raise FileNotFoundError(path)
913 return sorted(out)
FileNotFoundError: ['gdm_data/data/DistributionSystem/2_2_1/p5r']
During handling of the above exception, another exception occurred:
ValueError Traceback (most recent call last)
Cell In[4], line 3
1 from gdm.distribution import DistributionSystem
----> 3 distribution_system: DistributionSystem = gdm_loader.load_dataset(
4 system_type=DistributionSystem,
5 source_name="gdm_data",
6 dataset_name="p5r",
7 )
File /opt/hostedtoolcache/Python/3.12.12/x64/lib/python3.12/site-packages/gdmloader/source.py:131, in SystemLoader.load_dataset(self, system_type, source_name, dataset_name, version)
129 except FileNotFoundError:
130 msg = f"{remote_folder=} not found! Check the URL: {source.url}/{remote_folder}"
--> 131 raise ValueError(msg)
133 system_file = list(dataset_folder.rglob("*.json"))[0]
134 return system_type.from_json(system_file)
ValueError: remote_folder='gdm_data/data/DistributionSystem/2_2_1/p5r' not found! Check the URL: https://storage.googleapis.com/gdm_data/gdm_data/data/DistributionSystem/2_2_1/p5r
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()