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.
- cimhub_gdm-2.1.0a1/LICENSE +28 -0
- cimhub_gdm-2.1.0a1/PKG-INFO +134 -0
- cimhub_gdm-2.1.0a1/README.md +109 -0
- cimhub_gdm-2.1.0a1/pyproject.toml +44 -0
- cimhub_gdm-2.1.0a1/setup.cfg +4 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/__init__.py +15 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/__init__.py +5 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/bus.py +68 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/capacitor.py +174 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/cim_to_gdm.py +98 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/der.py +233 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/fills.py +104 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/geometry.py +181 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/line.py +167 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/load.py +99 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/naming.py +43 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/reactor.py +69 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/regulator.py +203 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/shared.py +116 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/shell.py +32 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/slots.py +42 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/source.py +95 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/switch.py +189 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/time_series.py +91 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/exporter/transformer.py +271 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/gdm_reader.py +14 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/gdm_writer.py +14 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/__init__.py +5 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/bus.py +51 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/capacitor.py +211 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/der.py +223 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/gdm_to_cim.py +242 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/line.py +297 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/load.py +176 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/network.py +90 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/reactor.py +62 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/regulator.py +258 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/shared.py +197 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/source.py +99 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/switch.py +187 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/time_series.py +157 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm/importer/transformer.py +388 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm.egg-info/PKG-INFO +134 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm.egg-info/SOURCES.txt +65 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm.egg-info/dependency_links.txt +1 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm.egg-info/requires.txt +5 -0
- cimhub_gdm-2.1.0a1/src/cimhub_gdm.egg-info/top_level.txt +1 -0
- cimhub_gdm-2.1.0a1/tests/test_capacitor_import.py +103 -0
- cimhub_gdm-2.1.0a1/tests/test_coverage_import.py +99 -0
- cimhub_gdm-2.1.0a1/tests/test_der_import.py +89 -0
- cimhub_gdm-2.1.0a1/tests/test_ditto_sweep.py +63 -0
- cimhub_gdm-2.1.0a1/tests/test_export_ditto.py +145 -0
- cimhub_gdm-2.1.0a1/tests/test_export_framework.py +302 -0
- cimhub_gdm-2.1.0a1/tests/test_export_gdm_level.py +256 -0
- cimhub_gdm-2.1.0a1/tests/test_export_round_trip.py +67 -0
- cimhub_gdm-2.1.0a1/tests/test_line_import.py +88 -0
- cimhub_gdm-2.1.0a1/tests/test_load_import.py +77 -0
- cimhub_gdm-2.1.0a1/tests/test_network_import.py +69 -0
- cimhub_gdm-2.1.0a1/tests/test_reactor_import.py +26 -0
- cimhub_gdm-2.1.0a1/tests/test_reference_import.py +7 -0
- cimhub_gdm-2.1.0a1/tests/test_regulator_import.py +71 -0
- cimhub_gdm-2.1.0a1/tests/test_shared_import.py +152 -0
- cimhub_gdm-2.1.0a1/tests/test_source_import.py +50 -0
- cimhub_gdm-2.1.0a1/tests/test_switch_import.py +85 -0
- cimhub_gdm-2.1.0a1/tests/test_time_series.py +230 -0
- cimhub_gdm-2.1.0a1/tests/test_transformer_import.py +186 -0
- 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,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,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)]
|