cimhub_gdm 2.1.0a1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. cimhub_gdm-2.1.0a1/LICENSE +28 -0
  2. cimhub_gdm-2.1.0a1/PKG-INFO +134 -0
  3. cimhub_gdm-2.1.0a1/README.md +109 -0
  4. cimhub_gdm-2.1.0a1/pyproject.toml +44 -0
  5. cimhub_gdm-2.1.0a1/setup.cfg +4 -0
  6. cimhub_gdm-2.1.0a1/src/cimhub_gdm/__init__.py +15 -0
  7. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/__init__.py +5 -0
  8. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/bus.py +68 -0
  9. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/capacitor.py +174 -0
  10. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/cim_to_gdm.py +98 -0
  11. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/der.py +233 -0
  12. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/fills.py +104 -0
  13. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/geometry.py +181 -0
  14. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/line.py +167 -0
  15. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/load.py +99 -0
  16. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/naming.py +43 -0
  17. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/reactor.py +69 -0
  18. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/regulator.py +203 -0
  19. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/shared.py +116 -0
  20. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/shell.py +32 -0
  21. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/slots.py +42 -0
  22. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/source.py +95 -0
  23. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/switch.py +189 -0
  24. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/time_series.py +91 -0
  25. cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/transformer.py +271 -0
  26. cimhub_gdm-2.1.0a1/src/cimhub_gdm/gdm_reader.py +14 -0
  27. cimhub_gdm-2.1.0a1/src/cimhub_gdm/gdm_writer.py +14 -0
  28. cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/__init__.py +5 -0
  29. cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/bus.py +51 -0
  30. cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/capacitor.py +211 -0
  31. cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/der.py +223 -0
  32. cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/gdm_to_cim.py +242 -0
  33. cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/line.py +297 -0
  34. cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/load.py +176 -0
  35. cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/network.py +90 -0
  36. cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/reactor.py +62 -0
  37. cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/regulator.py +258 -0
  38. cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/shared.py +197 -0
  39. cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/source.py +99 -0
  40. cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/switch.py +187 -0
  41. cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/time_series.py +157 -0
  42. cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/transformer.py +388 -0
  43. cimhub_gdm-2.1.0a1/src/cimhub_gdm.egg-info/PKG-INFO +134 -0
  44. cimhub_gdm-2.1.0a1/src/cimhub_gdm.egg-info/SOURCES.txt +65 -0
  45. cimhub_gdm-2.1.0a1/src/cimhub_gdm.egg-info/dependency_links.txt +1 -0
  46. cimhub_gdm-2.1.0a1/src/cimhub_gdm.egg-info/requires.txt +5 -0
  47. cimhub_gdm-2.1.0a1/src/cimhub_gdm.egg-info/top_level.txt +1 -0
  48. cimhub_gdm-2.1.0a1/tests/test_capacitor_import.py +103 -0
  49. cimhub_gdm-2.1.0a1/tests/test_coverage_import.py +99 -0
  50. cimhub_gdm-2.1.0a1/tests/test_der_import.py +89 -0
  51. cimhub_gdm-2.1.0a1/tests/test_ditto_sweep.py +63 -0
  52. cimhub_gdm-2.1.0a1/tests/test_export_ditto.py +145 -0
  53. cimhub_gdm-2.1.0a1/tests/test_export_framework.py +302 -0
  54. cimhub_gdm-2.1.0a1/tests/test_export_gdm_level.py +256 -0
  55. cimhub_gdm-2.1.0a1/tests/test_export_round_trip.py +67 -0
  56. cimhub_gdm-2.1.0a1/tests/test_line_import.py +88 -0
  57. cimhub_gdm-2.1.0a1/tests/test_load_import.py +77 -0
  58. cimhub_gdm-2.1.0a1/tests/test_network_import.py +69 -0
  59. cimhub_gdm-2.1.0a1/tests/test_reactor_import.py +26 -0
  60. cimhub_gdm-2.1.0a1/tests/test_reference_import.py +7 -0
  61. cimhub_gdm-2.1.0a1/tests/test_regulator_import.py +71 -0
  62. cimhub_gdm-2.1.0a1/tests/test_shared_import.py +152 -0
  63. cimhub_gdm-2.1.0a1/tests/test_source_import.py +50 -0
  64. cimhub_gdm-2.1.0a1/tests/test_switch_import.py +85 -0
  65. cimhub_gdm-2.1.0a1/tests/test_time_series.py +230 -0
  66. cimhub_gdm-2.1.0a1/tests/test_transformer_import.py +186 -0
  67. cimhub_gdm-2.1.0a1/tests/test_xml_round_trip.py +29 -0
@@ -0,0 +1,28 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright (c) 2026, Battelle Memorial Institute
4
+
5
+ Redistribution and use in source and binary forms, with or without
6
+ modification, are permitted provided that the following conditions are met:
7
+
8
+ 1. Redistributions of source code must retain the above copyright notice, this
9
+ list of conditions and the following disclaimer.
10
+
11
+ 2. Redistributions in binary form must reproduce the above copyright notice,
12
+ this list of conditions and the following disclaimer in the documentation
13
+ and/or other materials provided with the distribution.
14
+
15
+ 3. Neither the name of the copyright holder nor the names of its
16
+ contributors may be used to endorse or promote products derived from
17
+ this software without specific prior written permission.
18
+
19
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,134 @@
1
+ Metadata-Version: 2.4
2
+ Name: cimhub_gdm
3
+ Version: 2.1.0a1
4
+ Summary: CIMHub GDM converter: grid-data-models DistributionSystem -> cim18v17 through CIM-Builder
5
+ Author: Tylor Slay, Kapil Duwadi, Nathan Gray, Andy Fisher
6
+ Author-email: Alex Anderson <19935503+AAndersn@users.noreply.github.com>, Craig Allwardt <3979063+craig8@users.noreply.github.com>
7
+ Maintainer-email: Pacific Northwest National Laboratory <gridappsd@pnnl.gov>
8
+ License-Expression: BSD-3-Clause
9
+ Project-URL: Homepage, https://github.com/PNNL-CIM-Tools/CIMHub
10
+ Project-URL: Bug Tracker, https://github.com/PNNL-CIM-Tools/CIMHub/issues
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Intended Audience :: Science/Research
15
+ Classifier: Topic :: Scientific/Engineering
16
+ Requires-Python: >=3.11
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Requires-Dist: cimhub-core[time-points]<2.2,>=2.1.0a1
20
+ Requires-Dist: cim-builder<0.2,>=0.1.1a1
21
+ Requires-Dist: cim-tables<0.2,>=0.1.1a1
22
+ Requires-Dist: grid-data-models~=2.4
23
+ Requires-Dist: pyarrow>=18
24
+ Dynamic: license-file
25
+
26
+ # cimhub-gdm
27
+
28
+ grid-data-models (GDM) converter for CIMHub: a GDM `DistributionSystem` to and from CIM (cim18v17).
29
+
30
+ GDM has no file format of its own. Its native model is typed pydantic objects with pint quantities. So this package
31
+ is **builder-native**: `GdmImporter().to_cim(system)` calls CIM-Builder's keyword methods directly and writes no
32
+ `.cimtbl` file. The tests compare the result with reviewed `.cimtbl` goldens. The exporter reads every value
33
+ through the `cimhub-core` getters.
34
+
35
+ ```bash
36
+ pip install --pre cimhub-gdm # also installs cimhub-core
37
+ ```
38
+
39
+ Python 3.11 or later.
40
+
41
+ ## Quickstart
42
+
43
+ ```python
44
+ from cimhub_gdm import gdm_to_cim, read_gdm
45
+
46
+ system = read_gdm("system.json") # a GDM DistributionSystem saved as JSON
47
+ system.name = system.name or "my_feeder" # the CIM Model name; a system saved without one has none
48
+ network = gdm_to_cim(system)
49
+ ```
50
+
51
+ ## Time series
52
+
53
+ Load time series map onto nc_schedule `EnergyConnectionSchedule`s when you pass a `time_points` dict. The schedules go
54
+ in the CIM XML; their points go in Parquet beside it, one row per point keyed by the schedule's uri, never as graph
55
+ objects. See [`docs/TIMESERIES_NEEDS.md`](docs/TIMESERIES_NEEDS.md).
56
+
57
+ ```python
58
+ from cimgraph.utils import write_xml
59
+ from cimhub_gdm import GdmExporter, gdm_to_cim, read_time_points, write_time_points
60
+
61
+ time_points = {} # filled: {"EnergyConnectionTimePoint": pyarrow.Table}
62
+ feeder_model = gdm_to_cim(system, time_points=time_points)
63
+ write_xml(feeder_model, "feeder.xml")
64
+ write_time_points(time_points, "feeder.xml")
65
+
66
+ time_points = read_time_points("feeder.xml", reloaded_model)
67
+ system = GdmExporter(time_points).to_model(reloaded_model)
68
+ ```
69
+
70
+ Export goes the other way:
71
+
72
+ | Function | Purpose |
73
+ |---|---|
74
+ | `GdmExporter().to_model(network, *, name_source=None, system_name=None)` | returns a GDM `DistributionSystem` |
75
+ | `cim_to_gdm(network, destination, **opts)` | the same, written as GDM JSON |
76
+ | `read_gdm(path)`, `write_gdm(system, path)` | GDM JSON in and out |
77
+
78
+ `name_source` is `'name'`, `'mrid'` or `'uri'` (default `$CIMHUB_NAME_SOURCE`, else `'mrid'`). `system_name` names the
79
+ system; without it the model's one Feeder names it, and a model with several Feeders raises.
80
+
81
+ ## What is supported
82
+
83
+ | Family | Import | Export |
84
+ |---|---|---|
85
+ | Network shell (feeders, substations) and buses | yes | yes |
86
+ | Voltage sources | yes | yes |
87
+ | Switches, fuses, reclosers | yes | yes |
88
+ | Lines: matrix, sequence and geometry impedance, with wire and cable catalogs | yes | yes (bare and concentric-neutral wire) |
89
+ | Loads | yes | yes |
90
+ | Capacitors and their controllers | yes | yes |
91
+ | Transformers (tank-configuration templates, center taps, off-nominal taps) | yes | yes |
92
+ | Regulators, tap changers and controls | yes | yes |
93
+ | Solar and battery DER with inverter and battery data | yes | yes (one GDM DER per unit of a hybrid inverter) |
94
+ | Series reactors | yes | yes |
95
+
96
+ What raises or is dropped:
97
+
98
+ - Import: inverter controllers, the daily-timed capacitor controller and earthing switches raise as pending, naming
99
+ what they wait for. Other time series, and load time series imported without a `time_points` dict, are dropped with
100
+ one warning. GDM fields with no cim18v17 home are untranscribed (logged at `DEBUG`); the list is in
101
+ [GDM_MAPPING.md](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_gdm/docs/GDM_MAPPING.md) section 10.
102
+ - Export: a tape-shield cable raises, because GDM has no class for one. Exporting a model that `gdm_to_cim` built can
103
+ raise on its current limits, because CIM-Builder's `add_limit_type` has no `durationKind` yet (see
104
+ [GDM_MAPPING.md](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_gdm/docs/GDM_MAPPING.md) section 14, item B22 b).
105
+ - The exported system writes and solves through ditto's OpenDSS writer, which has no battery writer.
106
+
107
+ The import needs CIM-Builder's `add_transformer_tank_end` method, `SeriesCompensatorBuilder` and
108
+ `EnergyConnectionScheduleBuilder`. The output survives a cim18v17 XML round trip unchanged.
109
+
110
+ ## Documentation
111
+
112
+ - [GDM to CIM mapping spec](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_gdm/docs/GDM_MAPPING.md)
113
+ - [CIM to GDM export spec](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_gdm/docs/EXPORT_MAPPING.md)
114
+ - [Tap assumptions both directions make](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_gdm/docs/TAP_ASSUMPTIONS.md)
115
+ - [Rewrite plan](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_gdm/docs/GDM_REWRITE_PLAN.md) and [export plan](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_gdm/docs/EXPORT_PLAN.md)
116
+ - [CIMHub architecture](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_core/docs/ARCHITECTURE.md) and [converter API](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_core/docs/CONVERTER_API.md)
117
+
118
+ BSD 3-Clause. Source and issues: <https://github.com/PNNL-CIM-Tools/CIMHub>.
119
+
120
+ ## License and attribution
121
+
122
+ BSD 3-Clause. See [LICENSE](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_gdm/LICENSE). Contributors are listed in [AUTHORS](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/AUTHORS).
123
+
124
+ This software was created under a project sponsored by the U.S. Department of Energy's Office of Electricity, an
125
+ agency of the United States Government. Neither the United States Government nor the United States Department of
126
+ Energy, nor Battelle, nor any of their employees, nor any jurisdiction or organization that has cooperated in the
127
+ development of these materials, makes any warranty, express or implied, or assumes any legal liability or
128
+ responsibility for the accuracy, completeness, or usefulness or any information, apparatus, product, software, or
129
+ process disclosed, or represents that its use would not infringe privately owned rights.
130
+
131
+ PACIFIC NORTHWEST NATIONAL LABORATORY\
132
+ operated by BATTELLE\
133
+ for the UNITED STATES DEPARTMENT OF ENERGY\
134
+ under Contract DE-AC05-76RL01830
@@ -0,0 +1,109 @@
1
+ # cimhub-gdm
2
+
3
+ grid-data-models (GDM) converter for CIMHub: a GDM `DistributionSystem` to and from CIM (cim18v17).
4
+
5
+ GDM has no file format of its own. Its native model is typed pydantic objects with pint quantities. So this package
6
+ is **builder-native**: `GdmImporter().to_cim(system)` calls CIM-Builder's keyword methods directly and writes no
7
+ `.cimtbl` file. The tests compare the result with reviewed `.cimtbl` goldens. The exporter reads every value
8
+ through the `cimhub-core` getters.
9
+
10
+ ```bash
11
+ pip install --pre cimhub-gdm # also installs cimhub-core
12
+ ```
13
+
14
+ Python 3.11 or later.
15
+
16
+ ## Quickstart
17
+
18
+ ```python
19
+ from cimhub_gdm import gdm_to_cim, read_gdm
20
+
21
+ system = read_gdm("system.json") # a GDM DistributionSystem saved as JSON
22
+ system.name = system.name or "my_feeder" # the CIM Model name; a system saved without one has none
23
+ network = gdm_to_cim(system)
24
+ ```
25
+
26
+ ## Time series
27
+
28
+ Load time series map onto nc_schedule `EnergyConnectionSchedule`s when you pass a `time_points` dict. The schedules go
29
+ in the CIM XML; their points go in Parquet beside it, one row per point keyed by the schedule's uri, never as graph
30
+ objects. See [`docs/TIMESERIES_NEEDS.md`](docs/TIMESERIES_NEEDS.md).
31
+
32
+ ```python
33
+ from cimgraph.utils import write_xml
34
+ from cimhub_gdm import GdmExporter, gdm_to_cim, read_time_points, write_time_points
35
+
36
+ time_points = {} # filled: {"EnergyConnectionTimePoint": pyarrow.Table}
37
+ feeder_model = gdm_to_cim(system, time_points=time_points)
38
+ write_xml(feeder_model, "feeder.xml")
39
+ write_time_points(time_points, "feeder.xml")
40
+
41
+ time_points = read_time_points("feeder.xml", reloaded_model)
42
+ system = GdmExporter(time_points).to_model(reloaded_model)
43
+ ```
44
+
45
+ Export goes the other way:
46
+
47
+ | Function | Purpose |
48
+ |---|---|
49
+ | `GdmExporter().to_model(network, *, name_source=None, system_name=None)` | returns a GDM `DistributionSystem` |
50
+ | `cim_to_gdm(network, destination, **opts)` | the same, written as GDM JSON |
51
+ | `read_gdm(path)`, `write_gdm(system, path)` | GDM JSON in and out |
52
+
53
+ `name_source` is `'name'`, `'mrid'` or `'uri'` (default `$CIMHUB_NAME_SOURCE`, else `'mrid'`). `system_name` names the
54
+ system; without it the model's one Feeder names it, and a model with several Feeders raises.
55
+
56
+ ## What is supported
57
+
58
+ | Family | Import | Export |
59
+ |---|---|---|
60
+ | Network shell (feeders, substations) and buses | yes | yes |
61
+ | Voltage sources | yes | yes |
62
+ | Switches, fuses, reclosers | yes | yes |
63
+ | Lines: matrix, sequence and geometry impedance, with wire and cable catalogs | yes | yes (bare and concentric-neutral wire) |
64
+ | Loads | yes | yes |
65
+ | Capacitors and their controllers | yes | yes |
66
+ | Transformers (tank-configuration templates, center taps, off-nominal taps) | yes | yes |
67
+ | Regulators, tap changers and controls | yes | yes |
68
+ | Solar and battery DER with inverter and battery data | yes | yes (one GDM DER per unit of a hybrid inverter) |
69
+ | Series reactors | yes | yes |
70
+
71
+ What raises or is dropped:
72
+
73
+ - Import: inverter controllers, the daily-timed capacitor controller and earthing switches raise as pending, naming
74
+ what they wait for. Other time series, and load time series imported without a `time_points` dict, are dropped with
75
+ one warning. GDM fields with no cim18v17 home are untranscribed (logged at `DEBUG`); the list is in
76
+ [GDM_MAPPING.md](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_gdm/docs/GDM_MAPPING.md) section 10.
77
+ - Export: a tape-shield cable raises, because GDM has no class for one. Exporting a model that `gdm_to_cim` built can
78
+ raise on its current limits, because CIM-Builder's `add_limit_type` has no `durationKind` yet (see
79
+ [GDM_MAPPING.md](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_gdm/docs/GDM_MAPPING.md) section 14, item B22 b).
80
+ - The exported system writes and solves through ditto's OpenDSS writer, which has no battery writer.
81
+
82
+ The import needs CIM-Builder's `add_transformer_tank_end` method, `SeriesCompensatorBuilder` and
83
+ `EnergyConnectionScheduleBuilder`. The output survives a cim18v17 XML round trip unchanged.
84
+
85
+ ## Documentation
86
+
87
+ - [GDM to CIM mapping spec](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_gdm/docs/GDM_MAPPING.md)
88
+ - [CIM to GDM export spec](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_gdm/docs/EXPORT_MAPPING.md)
89
+ - [Tap assumptions both directions make](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_gdm/docs/TAP_ASSUMPTIONS.md)
90
+ - [Rewrite plan](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_gdm/docs/GDM_REWRITE_PLAN.md) and [export plan](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_gdm/docs/EXPORT_PLAN.md)
91
+ - [CIMHub architecture](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_core/docs/ARCHITECTURE.md) and [converter API](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_core/docs/CONVERTER_API.md)
92
+
93
+ BSD 3-Clause. Source and issues: <https://github.com/PNNL-CIM-Tools/CIMHub>.
94
+
95
+ ## License and attribution
96
+
97
+ BSD 3-Clause. See [LICENSE](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/cimhub_gdm/LICENSE). Contributors are listed in [AUTHORS](https://github.com/PNNL-CIM-Tools/CIMHub/blob/main/AUTHORS).
98
+
99
+ This software was created under a project sponsored by the U.S. Department of Energy's Office of Electricity, an
100
+ agency of the United States Government. Neither the United States Government nor the United States Department of
101
+ Energy, nor Battelle, nor any of their employees, nor any jurisdiction or organization that has cooperated in the
102
+ development of these materials, makes any warranty, express or implied, or assumes any legal liability or
103
+ responsibility for the accuracy, completeness, or usefulness or any information, apparatus, product, software, or
104
+ process disclosed, or represents that its use would not infringe privately owned rights.
105
+
106
+ PACIFIC NORTHWEST NATIONAL LABORATORY\
107
+ operated by BATTELLE\
108
+ for the UNITED STATES DEPARTMENT OF ENERGY\
109
+ under Contract DE-AC05-76RL01830
@@ -0,0 +1,44 @@
1
+ [build-system]
2
+ requires = ["setuptools~=80.9"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "cimhub_gdm"
7
+ description = "CIMHub GDM converter: grid-data-models DistributionSystem -> cim18v17 through CIM-Builder"
8
+ readme = "README.md"
9
+ version = "2.1.0a1"
10
+ requires-python = ">=3.11"
11
+ license = "BSD-3-Clause"
12
+ license-files = ["LICENSE"]
13
+ authors = [
14
+ { name = "Alex Anderson", email = "19935503+AAndersn@users.noreply.github.com" },
15
+ { name = "Tylor Slay" },
16
+ { name = "Kapil Duwadi" },
17
+ { name = "Nathan Gray" },
18
+ { name = "Craig Allwardt", email = "3979063+craig8@users.noreply.github.com" },
19
+ { name = "Andy Fisher" },
20
+ ]
21
+ maintainers = [
22
+ { name = "Pacific Northwest National Laboratory", email = "gridappsd@pnnl.gov" },
23
+ ]
24
+ classifiers = [
25
+ "Programming Language :: Python :: 3",
26
+ "Operating System :: OS Independent",
27
+ "Development Status :: 3 - Alpha",
28
+ "Intended Audience :: Science/Research",
29
+ "Topic :: Scientific/Engineering",
30
+ ]
31
+ dependencies = [
32
+ "cimhub-core[time-points]>=2.1.0a1,<2.2",
33
+ "cim-builder>=0.1.1a1,<0.2",
34
+ "cim-tables>=0.1.1a1,<0.2",
35
+ "grid-data-models~=2.4",
36
+ "pyarrow>=18",
37
+ ]
38
+
39
+ [project.urls]
40
+ "Homepage" = "https://github.com/PNNL-CIM-Tools/CIMHub"
41
+ "Bug Tracker" = "https://github.com/PNNL-CIM-Tools/CIMHub/issues"
42
+
43
+ [tool.setuptools]
44
+ packages = { find = { where = ["src"] } }
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,15 @@
1
+ """CIMHub GDM: grid-data-models DistributionSystem <-> cim18v17 (importer builder-native, exporter on the core
2
+ getters)."""
3
+
4
+ import importlib.metadata
5
+
6
+ __version__ = importlib.metadata.version("cimhub_gdm")
7
+
8
+ from cimhub_core.time_points import read_time_points, write_time_points
9
+ from cimhub_gdm.exporter import GdmExporter, cim_to_gdm
10
+ from cimhub_gdm.gdm_reader import read_gdm
11
+ from cimhub_gdm.gdm_writer import write_gdm
12
+ from cimhub_gdm.importer import GdmImporter, gdm_to_cim
13
+
14
+ __all__ = ["GdmExporter", "GdmImporter", "cim_to_gdm", "gdm_to_cim", "read_gdm", "read_time_points", "write_gdm",
15
+ "write_time_points"]
@@ -0,0 +1,5 @@
1
+ """cim18v17 → GDM DistributionSystem, through the core getters (``docs/EXPORT_PLAN.md``)."""
2
+
3
+ from cimhub_gdm.exporter.cim_to_gdm import EXPORT_ORDER, GdmExporter, cim_to_gdm
4
+
5
+ __all__ = ["EXPORT_ORDER", "GdmExporter", "cim_to_gdm"]
@@ -0,0 +1,68 @@
1
+ """ConnectivityNode → DistributionBus (``EXPORT_MAPPING.md#buses``, decision X6).
2
+
3
+ Buses are rated line to ground, as ditto's DSS reader writes them: ditto's capacitor and solar writers read a bus
4
+ rating as line to ground whatever its ``voltage_type``, so a line-to-line bus would put a 3-phase capacitor at √3 times
5
+ its voltage.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import cimprofiles.cim18.cim18v17 as cim
11
+ from cimhub_core.getters.base_voltage import get_base_voltage
12
+ from cimhub_core.getters.terminals import get_terminal_phases
13
+ from gdm.quantities import Voltage
14
+ from gdm.systems.distribution.components import DistributionBus
15
+ from gdm.systems.distribution.enums import Phase, VoltageTypes
16
+
17
+ from cimhub_gdm.exporter.shared import BUS_PHASE_ORDER, ExportContext, containers, gdm_phases
18
+ from cimhub_gdm.exporter.slots import UUID, Slot
19
+
20
+ CIM_CLASSES = (cim.ConnectivityNode,)
21
+
22
+ SPLIT_PHASES = {Phase.S1, Phase.S2}
23
+
24
+ SLOTS = {
25
+ DistributionBus: {
26
+ "uuid": UUID,
27
+ "name": Slot("written", "Names (X2)"),
28
+ "substation": Slot("written", "the ConnectivityNodeContainer when it is a Substation or VoltageLevel "
29
+ "(containers)"),
30
+ "feeder": Slot("written", "the ConnectivityNodeContainer when it is a Feeder (containers)"),
31
+ "in_service": Slot("unset", "a ConnectivityNode has no service state; GDM's default, True"),
32
+ "voltage_type": Slot("rule", "always line-to-ground, as ditto writes buses: its capacitor and solar writers "
33
+ "read every bus rating as line to ground (X6)"),
34
+ "phases": Slot("rule", "the union of the conductors on the node's terminals, in A B C S1 S2 N order; [] when "
35
+ "no terminal is on it (X6)"),
36
+ "voltagelimits": Slot("unset", "untranscribed on import: no OperationalLimitSet on a ConnectivityNode"),
37
+ "rated_voltage": Slot("rule", "get_base_voltage(form='LN') (kV); on a split-phase bus (S1 or S2) the 120 V "
38
+ "leg, get_base_voltage(form='LL') / 2 (the importer's system_voltage inverse)"),
39
+ "coordinate": Slot("unset", "untranscribed on import: a ConnectivityNode is not a PowerSystemResource (X10)"),
40
+ },
41
+ }
42
+
43
+
44
+ def export(node: cim.ConnectivityNode, context: ExportContext) -> DistributionBus:
45
+ phases = bus_phases(node)
46
+ return DistributionBus(
47
+ **context.names.own(node),
48
+ rated_voltage=Voltage(line_to_ground(node, phases), "kilovolt"),
49
+ voltage_type=VoltageTypes.LINE_TO_GROUND,
50
+ phases=phases,
51
+ **containers(node.ConnectivityNodeContainer, context),
52
+ )
53
+
54
+
55
+ def line_to_ground(node: cim.ConnectivityNode, phases: list) -> float:
56
+ """The bus's line-to-ground rating in kV: half the line-to-line voltage on a split-phase bus (240 V → 120 V),
57
+ else line to line / sqrt(3) (4.16 kV → 2.4018 kV)."""
58
+ if SPLIT_PHASES & set(phases):
59
+ return get_base_voltage(node, "kV", form="LL") / 2
60
+ return get_base_voltage(node, "kV", form="LN")
61
+
62
+
63
+ def bus_phases(node: cim.ConnectivityNode) -> list:
64
+ """Every conductor on the node's terminals, once, in ``BUS_PHASE_ORDER``."""
65
+ found = set()
66
+ for terminal in node.Terminals:
67
+ found.update(gdm_phases(get_terminal_phases(terminal), terminal))
68
+ return [phase for phase in BUS_PHASE_ORDER if phase in found]
@@ -0,0 +1,174 @@
1
+ """LinearShuntCompensator → DistributionCapacitor, its RegulatingControl → a capacitor controller
2
+ (``EXPORT_MAPPING.md#capacitors``, decisions X7, X8).
3
+
4
+ Each phase gets an equal share of the rated Q (all sections in, on ``nomU``: ``get_shunt_reactive_power``). The
5
+ state is one entry, as ditto writes it: on when any section is in. The controller is the importer's inverse: on and
6
+ off = (target ∓ deadband / 2) / ratio. GDM names no monitored element, so a control on another terminal raises.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import cimprofiles.cim18.cim18v17 as cim
12
+ from cimhub_core.cimtbl import lookup
13
+ from cimhub_core.getters import describe
14
+ from cimhub_core.getters.control import get_equipment_control
15
+ from cimhub_core.getters.shunt import get_shunt_reactive_power
16
+ from cimhub_core.getters.terminals import get_terminal_nodes
17
+ from gdm.quantities import ReactivePower
18
+ from gdm.systems.distribution.components import DistributionCapacitor
19
+ from gdm.systems.distribution.controllers import (
20
+ ActivePowerCapacitorController,
21
+ CurrentCapacitorController,
22
+ ReactivePowerCapacitorController,
23
+ VoltageCapacitorController,
24
+ )
25
+ from gdm.systems.distribution.enums import ConnectionType, VoltageTypes
26
+ from gdm.systems.distribution.equipment import CapacitorEquipment, PhaseCapacitorEquipment
27
+ from infrasys.quantities import ActivePower, Current, Time, Voltage
28
+
29
+ from cimhub_gdm.exporter.shared import ExportContext, connection_type, containers, gdm_phases, in_service
30
+ from cimhub_gdm.exporter.slots import UUID, Slot
31
+
32
+ CIM_CLASSES = (cim.LinearShuntCompensator,)
33
+
34
+ MODE = cim.RegulatingControlModeKind
35
+ #: Control mode → (controller class, on slot, off slot, quantity class, GDM unit of the mode's SI unit, ratio slot).
36
+ CONTROLLERS = {
37
+ MODE.voltage: (VoltageCapacitorController, "on_voltage", "off_voltage", Voltage, "volt", "pt_ratio"),
38
+ MODE.currentFlow: (CurrentCapacitorController, "on_current", "off_current", Current, "ampere", "ct_ratio"),
39
+ MODE.activePower: (ActivePowerCapacitorController, "on_power", "off_power", ActivePower, "watt", None),
40
+ MODE.reactivePower: (ReactivePowerCapacitorController, "on_power", "off_power", ReactivePower, "var", None),
41
+ }
42
+
43
+ BALANCED = (cim.SinglePhaseKind.A, cim.SinglePhaseKind.B, cim.SinglePhaseKind.C)
44
+
45
+ _UNTRANSCRIBED = "untranscribed on import: no CIM home"
46
+ _CONTROLLER_SLOTS = {
47
+ "uuid": UUID,
48
+ "name": Slot("written", "the capacitor's name (X2)"),
49
+ "delay_on": Slot("written", "get_equipment_control.delay (aVRDelay, s); unset is None"),
50
+ "delay_off": Slot("unset", "untranscribed on import: CIM has one delay, aVRDelay"),
51
+ "dead_time": Slot("unset", _UNTRANSCRIBED),
52
+ }
53
+ _ON = "(target − deadband / 2)"
54
+ _OFF = "(target + deadband / 2)"
55
+
56
+ SLOTS = {
57
+ DistributionCapacitor: {
58
+ "uuid": UUID,
59
+ "name": Slot("written", "Names (X2)"),
60
+ "substation": Slot("written", "the EquipmentContainer when it is a Substation or VoltageLevel (containers)"),
61
+ "feeder": Slot("written", "the EquipmentContainer when it is a Feeder (containers)"),
62
+ "in_service": Slot("rule", "get_in_service(which='actual'); unset is in service, GDM's default"),
63
+ "bus": Slot("written", "the bus of get_terminal_nodes"),
64
+ "phases": Slot("written", "get_shunt_reactive_power.phases: the phase conductors, no neutral"),
65
+ "controllers": Slot("rule", "one controller from get_equipment_control, by mode (CONTROLLERS); none when "
66
+ "there is no control or it is disabled (enabled or controlEnabled false)"),
67
+ "equipment": Slot("written", "a CapacitorEquipment made for this capacitor"),
68
+ "state": Slot("rule", "one entry, as ditto writes it: sections (actual) > 0"),
69
+ },
70
+ CapacitorEquipment: {
71
+ "uuid": UUID,
72
+ "name": Slot("written", "the capacitor's name (X2)"),
73
+ "phase_capacitors": Slot("written", "one PhaseCapacitorEquipment per phase conductor"),
74
+ "connection_type": Slot("written", "phaseConnection: Y and Yn → STAR, D → DELTA; others raise"),
75
+ "rated_voltage": Slot("written", "get_shunt_reactive_power(voltage='nominal').voltage: nomU (kV)"),
76
+ "voltage_type": Slot("rule", "line-to-line on balanced ABC and for delta (nomU across a branch), else "
77
+ "line-to-ground: the importer's nominal_voltage inverse"),
78
+ },
79
+ PhaseCapacitorEquipment: {
80
+ "uuid": UUID,
81
+ "name": Slot("written", "<capacitor>_<phase> (X2)"),
82
+ "resistance": Slot("unset", "untranscribed on import: no home on LinearShuntCompensator; GDM's default 0"),
83
+ "reactance": Slot("unset", "untranscribed on import: no home on LinearShuntCompensator; GDM's default 0"),
84
+ "rated_reactive_power": Slot("written", "get_shunt_reactive_power(sections='maximum', voltage='nominal')"
85
+ ".per_phase (kVAr)"),
86
+ "num_banks_on": Slot("written", "get_shunt_reactive_power(sections='actual').sections; a fraction raises"),
87
+ "num_banks": Slot("written", "get_shunt_reactive_power(sections='maximum').sections"),
88
+ },
89
+ VoltageCapacitorController: _CONTROLLER_SLOTS | {
90
+ "on_voltage": Slot("rule", f"{_ON} / pt_ratio (V)"),
91
+ "off_voltage": Slot("rule", f"{_OFF} / pt_ratio (V)"),
92
+ "pt_ratio": Slot("rule", "ptRatio; unset is 1, the targets as stored"),
93
+ },
94
+ CurrentCapacitorController: _CONTROLLER_SLOTS | {
95
+ "on_current": Slot("rule", f"{_ON} / ct_ratio (A)"),
96
+ "off_current": Slot("rule", f"{_OFF} / ct_ratio (A)"),
97
+ "ct_ratio": Slot("rule", "ctRatio; unset is 1, the targets as stored"),
98
+ },
99
+ ActivePowerCapacitorController: _CONTROLLER_SLOTS | {
100
+ "on_power": Slot("rule", f"{_ON} (W)"),
101
+ "off_power": Slot("rule", f"{_OFF} (W)"),
102
+ },
103
+ ReactivePowerCapacitorController: _CONTROLLER_SLOTS | {
104
+ "on_power": Slot("rule", f"{_ON} (VAr)"),
105
+ "off_power": Slot("rule", f"{_OFF} (VAr)"),
106
+ },
107
+ }
108
+
109
+
110
+ def export(shunt: cim.LinearShuntCompensator, context: ExportContext) -> DistributionCapacitor:
111
+ rated = get_shunt_reactive_power(shunt, "kVAr", sections="maximum", voltage="nominal", voltage_unit="kV")
112
+ actual = get_shunt_reactive_power(shunt, "kVAr", sections="actual", voltage="nominal", voltage_unit="kV")
113
+ names = context.names
114
+ phases = gdm_phases(rated.phases, shunt)
115
+ banks_on = whole_sections(actual.sections, shunt)
116
+ phase_capacitors = [
117
+ PhaseCapacitorEquipment(**names.part(shunt, PhaseCapacitorEquipment, suffix=f"_{phase.value}"),
118
+ rated_reactive_power=ReactivePower(rated.per_phase[conductor], "kilovar"),
119
+ num_banks_on=banks_on, num_banks=whole_sections(rated.sections, shunt))
120
+ for conductor, phase in zip(rated.phases, phases)
121
+ ]
122
+ connection = connection_type(rated.connection, shunt)
123
+ equipment = CapacitorEquipment(**names.part(shunt, CapacitorEquipment), phase_capacitors=phase_capacitors,
124
+ connection_type=connection, rated_voltage=Voltage(rated.voltage, "kilovolt"),
125
+ voltage_type=voltage_type(rated.phases, connection))
126
+ [node] = get_terminal_nodes(shunt)
127
+ return DistributionCapacitor(
128
+ **names.own(shunt),
129
+ bus=context.gdm(node),
130
+ phases=phases,
131
+ equipment=equipment,
132
+ state=[banks_on > 0],
133
+ controllers=controllers(shunt, context),
134
+ in_service=in_service(shunt),
135
+ **containers(shunt.EquipmentContainer, context),
136
+ )
137
+
138
+
139
+ def whole_sections(sections: float, shunt: cim.LinearShuntCompensator) -> int:
140
+ """A section count as GDM's bank count; a fraction of a section raises."""
141
+ if sections != int(sections):
142
+ raise ValueError(f"{describe(shunt)}: {sections} sections; GDM counts whole banks")
143
+ return int(sections)
144
+
145
+
146
+ def voltage_type(phases, connection: ConnectionType) -> VoltageTypes:
147
+ """nomU's form: line to line on balanced ABC and across a delta branch, line to ground for a wye off ABC."""
148
+ if tuple(phases) == BALANCED or connection is ConnectionType.DELTA:
149
+ return VoltageTypes.LINE_TO_LINE
150
+ return VoltageTypes.LINE_TO_GROUND
151
+
152
+
153
+ def controllers(shunt: cim.LinearShuntCompensator, context: ExportContext) -> list:
154
+ """The capacitor's one controller, or none when it has no control or the control is disabled."""
155
+ control = get_equipment_control(shunt, time_unit="s")
156
+ if control is None or control.control_enabled is False or control.control.enabled is False:
157
+ return []
158
+ settings = control.control
159
+ if settings.terminal not in shunt.Terminals:
160
+ raise ValueError(f"{describe(shunt)}: its RegulatingControl monitors {describe(settings.terminal)}, not "
161
+ "its own terminal; a GDM capacitor controller names no monitored element")
162
+ controller_class, on_slot, off_slot, quantity, unit, ratio_slot = lookup(
163
+ CONTROLLERS, settings.mode, slot="mode", record_id=shunt.mRID)
164
+ values = {}
165
+ scale = 1.0
166
+ if ratio_slot is not None:
167
+ ratio = settings.pt_ratio if ratio_slot == "pt_ratio" else settings.ct_ratio
168
+ scale = 1.0 if ratio is None else ratio # unset: the targets as stored
169
+ values[ratio_slot] = scale
170
+ half_band = (settings.deadband or 0.0) / 2
171
+ values[on_slot] = quantity((settings.target - half_band) / scale, unit)
172
+ values[off_slot] = quantity((settings.target + half_band) / scale, unit)
173
+ delay = None if control.delay is None else Time(control.delay, "second")
174
+ return [controller_class(**context.names.part(shunt, controller_class), delay_on=delay, **values)]