cimhub-raw 2.0.0a2__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 (133) hide show
  1. cimhub_raw-2.0.0a2/PKG-INFO +319 -0
  2. cimhub_raw-2.0.0a2/README.md +304 -0
  3. cimhub_raw-2.0.0a2/pyproject.toml +47 -0
  4. cimhub_raw-2.0.0a2/setup.cfg +4 -0
  5. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/__init__.py +28 -0
  6. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/annotation_writer.py +292 -0
  7. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/areas/__init__.py +1 -0
  8. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/areas/area_interchange.py +137 -0
  9. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/cim_to_raw.py +965 -0
  10. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/dc/__init__.py +1 -0
  11. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/dc/two_terminal_dc.py +218 -0
  12. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/dc/vsc_dc.py +205 -0
  13. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/facts/__init__.py +1 -0
  14. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/facts/facts_device.py +370 -0
  15. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/generators/__init__.py +12 -0
  16. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/generators/synchronous_machine.py +206 -0
  17. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/lines/__init__.py +12 -0
  18. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/lines/ac_line_segment.py +215 -0
  19. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/lines/multi_section_line.py +159 -0
  20. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/lines/retained_breaker.py +196 -0
  21. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/loads/__init__.py +9 -0
  22. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/loads/energy_consumer.py +156 -0
  23. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/machines/__init__.py +1 -0
  24. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/machines/induction_machine.py +238 -0
  25. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/raw34_writer.py +256 -0
  26. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/registry.py +8 -0
  27. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/series/__init__.py +1 -0
  28. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/series/series_compensator.py +171 -0
  29. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/shunts/__init__.py +1 -0
  30. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/shunts/shunt_compensator.py +143 -0
  31. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/shunts/switched_shunt_compensator.py +216 -0
  32. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/topology/__init__.py +2 -0
  33. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/topology/bus_name_utils.py +294 -0
  34. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/topology/connectivity_node.py +197 -0
  35. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/transformers/__init__.py +9 -0
  36. cimhub_raw-2.0.0a2/src/cimhub_raw/exporter/transformers/power_transformer.py +236 -0
  37. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/__init__.py +0 -0
  38. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/areas/__init__.py +0 -0
  39. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/areas/area_interchange.py +101 -0
  40. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/bus_lookup.py +43 -0
  41. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/dc/__init__.py +0 -0
  42. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/dc/two_terminal_dc.py +235 -0
  43. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/dc/vsc_dc.py +211 -0
  44. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/facts/__init__.py +1 -0
  45. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/facts/facts_device.py +152 -0
  46. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/generators/__init__.py +0 -0
  47. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/generators/generator.py +301 -0
  48. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/lines/__init__.py +0 -0
  49. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/lines/branch.py +404 -0
  50. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/lines/multi_section_line.py +144 -0
  51. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/loads/__init__.py +0 -0
  52. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/loads/load.py +283 -0
  53. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/machines/__init__.py +0 -0
  54. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/machines/induction_machine.py +125 -0
  55. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/owners/__init__.py +0 -0
  56. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/owners/owner.py +67 -0
  57. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/raw34_reader.py +1974 -0
  58. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/raw34_to_cim.py +337 -0
  59. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/registry.py +8 -0
  60. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/shunts/__init__.py +0 -0
  61. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/shunts/fixed_shunt.py +217 -0
  62. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/shunts/switched_shunt.py +187 -0
  63. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/switches/__init__.py +0 -0
  64. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/switches/switch.py +173 -0
  65. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/topology/__init__.py +3 -0
  66. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/topology/bus.py +286 -0
  67. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/transformers/__init__.py +5 -0
  68. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/transformers/transformer.py +351 -0
  69. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/zones/__init__.py +0 -0
  70. cimhub_raw-2.0.0a2/src/cimhub_raw/importer/zones/zone.py +86 -0
  71. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/data_profile/__init__.py +113 -0
  72. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/data_profile/raw_extension.py +5162 -0
  73. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/models/__init__.py +0 -0
  74. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/models/rawModel.py +1455 -0
  75. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/area_interchange.yaml +77 -0
  76. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/branch.yaml +269 -0
  77. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/bus.yaml +162 -0
  78. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/case_identification.yaml +143 -0
  79. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/facts_device.yaml +265 -0
  80. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/fixed_shunt.yaml +76 -0
  81. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/generator.yaml +341 -0
  82. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/gne_device.yaml +87 -0
  83. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/impedance_correction.yaml +189 -0
  84. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/induction_machine.yaml +387 -0
  85. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/interarea_transfer.yaml +61 -0
  86. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/load.yaml +214 -0
  87. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/multi_section_line.yaml +173 -0
  88. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/multi_terminal_dc.yaml +58 -0
  89. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/owner.yaml +41 -0
  90. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/switch.yaml +128 -0
  91. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/switched_shunt.yaml +319 -0
  92. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/transformer.yaml +1503 -0
  93. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/two_terminal_dc.yaml +632 -0
  94. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/vsc_dc.yaml +360 -0
  95. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/classes/zone.yaml +41 -0
  96. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/composite_id.py +103 -0
  97. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/main.yaml +191 -0
  98. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/raw34_schema.py +4059 -0
  99. cimhub_raw-2.0.0a2/src/cimhub_raw/schema/raw_v34/types/common_types.yaml +33 -0
  100. cimhub_raw-2.0.0a2/src/cimhub_raw.egg-info/PKG-INFO +319 -0
  101. cimhub_raw-2.0.0a2/src/cimhub_raw.egg-info/SOURCES.txt +131 -0
  102. cimhub_raw-2.0.0a2/src/cimhub_raw.egg-info/dependency_links.txt +1 -0
  103. cimhub_raw-2.0.0a2/src/cimhub_raw.egg-info/requires.txt +2 -0
  104. cimhub_raw-2.0.0a2/src/cimhub_raw.egg-info/top_level.txt +1 -0
  105. cimhub_raw-2.0.0a2/tests/test_api_conformance.py +16 -0
  106. cimhub_raw-2.0.0a2/tests/test_area_interchange.py +86 -0
  107. cimhub_raw-2.0.0a2/tests/test_area_interchange_importer.py +127 -0
  108. cimhub_raw-2.0.0a2/tests/test_branch.py +416 -0
  109. cimhub_raw-2.0.0a2/tests/test_bus.py +292 -0
  110. cimhub_raw-2.0.0a2/tests/test_facts_device.py +207 -0
  111. cimhub_raw-2.0.0a2/tests/test_fixed_shunt.py +332 -0
  112. cimhub_raw-2.0.0a2/tests/test_full_roundtrip.py +593 -0
  113. cimhub_raw-2.0.0a2/tests/test_generator.py +409 -0
  114. cimhub_raw-2.0.0a2/tests/test_ieee14_roundtrip.py +272 -0
  115. cimhub_raw-2.0.0a2/tests/test_induction_machine.py +231 -0
  116. cimhub_raw-2.0.0a2/tests/test_load.py +385 -0
  117. cimhub_raw-2.0.0a2/tests/test_multi_section_line_exporter.py +115 -0
  118. cimhub_raw-2.0.0a2/tests/test_multi_section_line_importer.py +106 -0
  119. cimhub_raw-2.0.0a2/tests/test_owner_exporter.py +73 -0
  120. cimhub_raw-2.0.0a2/tests/test_owner_importer.py +80 -0
  121. cimhub_raw-2.0.0a2/tests/test_production_roundtrip.py +171 -0
  122. cimhub_raw-2.0.0a2/tests/test_raw34_reader.py +71 -0
  123. cimhub_raw-2.0.0a2/tests/test_raw34_roundtrip.py +49 -0
  124. cimhub_raw-2.0.0a2/tests/test_rawModel.py +1777 -0
  125. cimhub_raw-2.0.0a2/tests/test_rawToCim.py +748 -0
  126. cimhub_raw-2.0.0a2/tests/test_raw_extension.py +2265 -0
  127. cimhub_raw-2.0.0a2/tests/test_switch_importer.py +192 -0
  128. cimhub_raw-2.0.0a2/tests/test_switched_shunt_compensator.py +214 -0
  129. cimhub_raw-2.0.0a2/tests/test_two_terminal_dc.py +184 -0
  130. cimhub_raw-2.0.0a2/tests/test_two_terminal_dc_importer.py +195 -0
  131. cimhub_raw-2.0.0a2/tests/test_vsc_dc_exporter.py +127 -0
  132. cimhub_raw-2.0.0a2/tests/test_vsc_dc_importer.py +151 -0
  133. cimhub_raw-2.0.0a2/tests/test_zone_importer.py +111 -0
@@ -0,0 +1,319 @@
1
+ Metadata-Version: 2.4
2
+ Name: cimhub_raw
3
+ Version: 2.0.0a2
4
+ Summary: CIMHub PSS/E Library
5
+ Author-email: Andrew R Fisher <andrew.fisher@pnnl.gov>
6
+ Project-URL: Homepage, https://github.com/PNNL-CIM-Tools/CIMHub_2_0
7
+ Project-URL: Bug Tracker, https://github.com/PNNL-CIM-Tools/CIMHub_2_0
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: Operating System :: OS Independent
10
+ Classifier: Environment :: Console
11
+ Requires-Python: >=3.10
12
+ Description-Content-Type: text/markdown
13
+ Requires-Dist: cimhub_core<2.1,>=2.0.0a2
14
+ Requires-Dist: networkx
15
+
16
+ # cimhub_raw
17
+
18
+ # cimhub_raw
19
+
20
+ RAW v34 ↔ CIM converter for the cimhub ecosystem.
21
+
22
+ Supports reading, writing, and bidirectional conversion between RAW v34 files and CIM (IEC 61970) network models using [cimgraph](https://github.com/PNNL-CIM-Tools/cimgraph).
23
+
24
+ ---
25
+
26
+ ## Installation
27
+
28
+ ```bash
29
+ uv sync
30
+ # or
31
+ pip install -e .
32
+ ```
33
+
34
+ Set the CIM profile before importing (required by cimgraph):
35
+
36
+ ```python
37
+ import os
38
+ os.environ.setdefault("CIMG_CIM_PROFILE", "cim17v40")
39
+ ```
40
+
41
+ ---
42
+
43
+ ## Usage
44
+
45
+ ### 1. Read a RAW file (no CIM conversion)
46
+
47
+ The source is bound at construction and `read_all()` returns a
48
+ `cimhub_core.GraphModel` — the same `graph[RecordClass][identifier]` container
49
+ used across the cimhub ecosystem. Records are the LinkML-generated dataclasses
50
+ in `raw34_schema`.
51
+
52
+ ```python
53
+ from cimhub_raw.importer.raw34_reader import Raw34Reader
54
+ import cimhub_raw.schema.raw_v34.raw34_schema as raw
55
+
56
+ raw_network = Raw34Reader("network.raw").read_all()
57
+
58
+ # Counts and iteration go through the GraphModel API:
59
+ print(f"Buses: {raw_network.count(raw.BusRecord)}")
60
+ print(f"Loads: {raw_network.count(raw.LoadRecord)}")
61
+ print(f"Generators: {raw_network.count(raw.GeneratorRecord)}")
62
+
63
+ for bus in raw_network.list_by_class(raw.BusRecord):
64
+ print(f" Bus {bus.bus_number}: {bus.name}, {bus.base_voltage} kV")
65
+ ```
66
+
67
+ > **Note:** the reader used to return a `RawModel` container with
68
+ > `.bus_records` / `.load_records` list attributes. That container is gone —
69
+ > use `count()` / `list_by_class()` / `find_by_attribute()` instead.
70
+
71
+ ### 1a. Basic editing style
72
+
73
+ Records live at `raw_network.graph[RecordClass][identifier]`. The identifier is
74
+ the composite key the reader assigns per record type (see the table below), so
75
+ you can look a record up directly and mutate its fields in place:
76
+
77
+ ```python
78
+ import cimhub_raw.schema.raw_v34.raw34_schema as raw
79
+
80
+ # Direct access by composite identifier — generator id "3" on bus 10111:
81
+ gen = raw_network.graph[raw.GeneratorRecord]['10111_3']
82
+ gen.p_output = 250.0 # set active power (MW)
83
+ gen.q_output = 40.0 # set reactive power (MVAr)
84
+
85
+ # Or find a record without knowing its exact key:
86
+ (bus,) = raw_network.find_by_attribute(raw.BusRecord, 'bus_number', 10111)
87
+ bus.base_voltage = 138.0
88
+
89
+ # find_by_attribute returns a LIST (exact string match), so index or unpack it:
90
+ loads = raw_network.find_by_attribute(raw.LoadRecord, 'bus_number', 10111)
91
+ for load in loads:
92
+ load.status = 0 # take every load on the bus out of service
93
+ ```
94
+
95
+ **Composite identifier keys** (what to put in `graph[Cls][...]`):
96
+
97
+ | Record | Identifier key |
98
+ |---|---|
99
+ | `BusRecord` | `bus_number` |
100
+ | `LoadRecord` | `bus_number_loadid` |
101
+ | `FixedShuntRecord` | `bus_number_shuntid` |
102
+ | `GeneratorRecord` | `bus_number_genid` |
103
+ | `BranchRecord` / `SwitchRecord` | `from_to_ckt` |
104
+ | `TransformerRecord` | `i_j_k_ckt` |
105
+ | `SwitchedShuntRecord` | `bus_number` |
106
+ | `VscDcRecord` | `name_ibus` |
107
+
108
+ If you don't know the exact key, `find_by_attribute(cls, attr, value)` is the
109
+ safe path — it matches on the string form of any field.
110
+
111
+ ### 2. Write a RAW file
112
+
113
+ The writer's standard input is a `GraphModel` — pass the one you read/edited
114
+ straight to `write()`:
115
+
116
+ ```python
117
+ from cimhub_raw.exporter.raw34_writer import Raw34Writer
118
+
119
+ writer = Raw34Writer()
120
+ writer.write(raw_network, "output.raw")
121
+ ```
122
+
123
+ To render a single record without writing a file, use `writer.serialize(obj)`.
124
+
125
+ ### 3. RAW → RAW round-trip (read + write, no CIM)
126
+
127
+ ```python
128
+ from cimhub_raw.importer.raw34_reader import Raw34Reader
129
+ from cimhub_raw.exporter.raw34_writer import Raw34Writer
130
+
131
+ raw_network = Raw34Reader("network.raw").read_all()
132
+ Raw34Writer().write(raw_network, "output.raw")
133
+ ```
134
+
135
+ ### 4. RAW → CIM
136
+
137
+ Convert a RAW file to a CIM `NodeBreakerModel` (cimgraph):
138
+
139
+ ```python
140
+ import os
141
+ os.environ.setdefault("CIMG_CIM_PROFILE", "cim17v40")
142
+
143
+ from cimhub_raw.importer.raw34_to_cim import raw34_to_cim
144
+ import cimhub_raw.schema.data_profile as cim
145
+
146
+ network = raw34_to_cim("network.raw")
147
+
148
+ buses = network.list_by_class(cim.TopologicalNode)
149
+ loads = network.list_by_class(cim.EnergyConsumer)
150
+ gens = network.list_by_class(cim.SynchronousMachine)
151
+
152
+ print(f"Buses: {len(buses)}, Loads: {len(loads)}, Generators: {len(gens)}")
153
+ ```
154
+
155
+ Pass `include_extensions=True` to attach raw_extension objects (e.g. `RawBusRecord`)
156
+ alongside each CIM object — useful for lossless round-trips:
157
+
158
+ ```python
159
+ network = raw34_to_cim("network.raw", include_extensions=True)
160
+ ```
161
+
162
+ ### 5. CIM → RAW
163
+
164
+ Export a CIM `BusBranchModel` back to a RAW file:
165
+
166
+ ```python
167
+ from cimhub_raw.exporter.cim_to_raw import cim_to_raw
168
+
169
+ cim_to_raw(network, "output.raw")
170
+ ```
171
+
172
+ Or build the intermediate `GraphModel` first (e.g. to inspect before writing):
173
+
174
+ ```python
175
+ from cimhub_raw.exporter.cim_to_raw import Raw34Exporter
176
+ from cimhub_raw.exporter.raw34_writer import Raw34Writer
177
+
178
+ raw_model = Raw34Exporter().to_model(network, system_base_mva=100.0)
179
+ writer = Raw34Writer()
180
+ writer.write(raw_model, "output.raw")
181
+ ```
182
+
183
+ ### 6. Full RAW → CIM → RAW round-trip
184
+
185
+ ```python
186
+ import os
187
+ os.environ.setdefault("CIMG_CIM_PROFILE", "cim17v40")
188
+
189
+ from cimhub_raw.importer.raw34_to_cim import raw34_to_cim
190
+ from cimhub_raw.exporter.cim_to_raw import cim_to_raw
191
+
192
+ network = raw34_to_cim("network.raw", include_extensions=True)
193
+ cim_to_raw(network, "output.raw")
194
+ ```
195
+
196
+ ### 7. Serialize CIM to XML / JSON-LD
197
+
198
+ Once you have a CIM network model, serialize it to CIM XML or JSON-LD:
199
+
200
+ ```python
201
+ from cimgraph.utils import write_xml, write_json_ld
202
+
203
+ write_xml(network, "network.xml")
204
+ write_json_ld(network, "network.jsonld")
205
+ ```
206
+
207
+ ---
208
+
209
+ ## Equipment Coverage
210
+
211
+ ### Fully converted (RAW ↔ CIM)
212
+
213
+ | RAW Record | CIM Class(es) |
214
+ |---|---|
215
+ | BusRecord | `TopologicalNode`, `ConnectivityNode` |
216
+ | LoadRecord | `EnergyConsumer` |
217
+ | GeneratorRecord | `SynchronousMachine` |
218
+ | FixedShuntRecord | `LinearShuntCompensator` (single-section) |
219
+ | SwitchedShuntRecord | `LinearShuntCompensator` (multi-section) |
220
+ | BranchRecord | `ACLineSegment`, `SeriesCompensator`, `Breaker` |
221
+ | TransformerRecord | `PowerTransformer` (2-winding) |
222
+ | TwoTerminalDCRecord | `DCLineSegment` + `CsConverter` x2 |
223
+ | VscDcRecord | `DCLineSegment` + `VsConverter` x2 |
224
+ | FactsDeviceRecord | `StaticVarCompensator`, `VsConverter` |
225
+ | InductionMachineRecord | `AsynchronousMachine` |
226
+ | AreaInterchangeRecord | `ControlArea` / `SubControlArea` |
227
+ | ZoneRecord | `SubGeographicalRegion` |
228
+ | OwnerRecord | `AssetOwner` |
229
+ | MultiSectionLineRecord | `Line` (container grouping) |
230
+ | SwitchRecord | `Switch` / `Breaker` |
231
+
232
+ ### Passthrough only (read + write, no CIM conversion)
233
+
234
+ These record types are parsed and written verbatim but have no CIM mapping:
235
+
236
+ | RAW Record | Reason |
237
+ |---|---|
238
+ | InterareaTransferRecord | No standard CIM equivalent |
239
+ | ImpedanceCorrectionRecord | No CIM class in the CIM 17 profile |
240
+ | MultiTerminalDCRecord | Sub-records (converters, bus links) not fully parsed |
241
+ | GneDeviceRecord | Generic extensible model; depends on `model` field |
242
+
243
+ ---
244
+
245
+ ## Running Tests
246
+
247
+ ```bash
248
+ # From the repo root
249
+ uv run pytest cimhub_raw/tests/
250
+
251
+ # Key test files
252
+ uv run pytest cimhub_raw/tests/test_raw34_roundtrip.py # RAW → RAW (no CIM)
253
+ uv run pytest cimhub_raw/tests/test_ieee14_roundtrip.py # Full RAW → CIM → RAW
254
+ uv run pytest cimhub_raw/tests/test_production_roundtrip.py # 169-bus production model
255
+ ```
256
+
257
+ ---
258
+
259
+ ## TODO
260
+
261
+ ### CIM mappings needed for passthrough record types
262
+
263
+ These record types are currently read and written verbatim (no CIM conversion).
264
+ Implementing them requires either finding an appropriate CIM class or extending the data profile.
265
+
266
+ #### 1. `InterareaTransferRecord`
267
+ - Represents scheduled power transfers between control areas.
268
+ - No direct CIM equivalent in CIM 17. Closest candidates: `TieFlow` or a custom extension.
269
+ - Work needed: define CIM mapping, implement importer + exporter, add tests.
270
+
271
+ #### 2. `ImpedanceCorrectionRecord`
272
+ - Tap-dependent impedance correction tables for transformers.
273
+ - No CIM class in the CIM 17 profile. Closest: `TransformerMeshImpedance` or a raw_extension.
274
+ - Work needed: define CIM mapping or raw_extension class, implement importer + exporter, add tests.
275
+
276
+ #### 3. `MultiTerminalDCRecord`
277
+ - Represents multi-terminal HVDC lines (3+ converter stations).
278
+ - CIM has `DCNode`, `DCTopologicalNode`, `DCConverterUnit` — mapping is feasible but complex.
279
+ - Current reader only parses the header line; converter/bus/link sub-records are skipped.
280
+ - Work needed: extend reader to parse all sub-record types, define CIM mapping, implement importer + exporter.
281
+
282
+ #### 4. `GneDeviceRecord`
283
+ - Generic network element: a catch-all for vendor-specific dynamic models.
284
+ - No universal CIM mapping — depends on the `model` field value.
285
+ - Work needed: case-by-case assessment per model type; may require raw_extension approach.
286
+
287
+ ### Other known gaps
288
+
289
+ - **3-winding transformers**: `TransformerRecord` currently handles 2-winding only. 3-winding transformers are represented as a star (3 × 2-winding) in raw; CIM uses `PowerTransformerEnd` with 3 ends. Needs dedicated handling.
290
+ - **Multi-terminal DC importer registration**: `MultiTerminalDCRecord` is not in `IMPORT_ORDER` in `raw34_to_cim.py`.
291
+
292
+
293
+
294
+ ## Legacy PSS/E RAW extension layer (`cimgraph_raw_extension`). Provides raw-extension dataclasses that can be attached alongside CIM objects during a PSS/E import to preserve fields that have no direct CIM mapping.
295
+
296
+
297
+ ### Usage
298
+
299
+ ```python
300
+ from cimgraph_raw_extension.converters.rawToCim import raw_to_cim
301
+ from cimgraph_raw_extension.converters.cimToRaw import cim_to_raw
302
+
303
+ # Import RAW → CIM with extensions attached
304
+ network = raw_to_cim("network.raw")
305
+
306
+ # Export CIM → RAW
307
+ cim_to_raw(network, "output.raw")
308
+ ```
309
+
310
+ ## Structure
311
+
312
+ ```
313
+ src/cimgraph_raw_extension/
314
+ data_profile/raw_extension.py # Extension dataclasses (RawBusRecord, etc.)
315
+ models/rawModel.py # RawModel container (legacy)
316
+ converters/rawToCim.py # RAW → CIM conversion
317
+ converters/cimToRaw.py # CIM → RAW conversion
318
+ ```
319
+
@@ -0,0 +1,304 @@
1
+ # cimhub_raw
2
+
3
+ # cimhub_raw
4
+
5
+ RAW v34 ↔ CIM converter for the cimhub ecosystem.
6
+
7
+ Supports reading, writing, and bidirectional conversion between RAW v34 files and CIM (IEC 61970) network models using [cimgraph](https://github.com/PNNL-CIM-Tools/cimgraph).
8
+
9
+ ---
10
+
11
+ ## Installation
12
+
13
+ ```bash
14
+ uv sync
15
+ # or
16
+ pip install -e .
17
+ ```
18
+
19
+ Set the CIM profile before importing (required by cimgraph):
20
+
21
+ ```python
22
+ import os
23
+ os.environ.setdefault("CIMG_CIM_PROFILE", "cim17v40")
24
+ ```
25
+
26
+ ---
27
+
28
+ ## Usage
29
+
30
+ ### 1. Read a RAW file (no CIM conversion)
31
+
32
+ The source is bound at construction and `read_all()` returns a
33
+ `cimhub_core.GraphModel` — the same `graph[RecordClass][identifier]` container
34
+ used across the cimhub ecosystem. Records are the LinkML-generated dataclasses
35
+ in `raw34_schema`.
36
+
37
+ ```python
38
+ from cimhub_raw.importer.raw34_reader import Raw34Reader
39
+ import cimhub_raw.schema.raw_v34.raw34_schema as raw
40
+
41
+ raw_network = Raw34Reader("network.raw").read_all()
42
+
43
+ # Counts and iteration go through the GraphModel API:
44
+ print(f"Buses: {raw_network.count(raw.BusRecord)}")
45
+ print(f"Loads: {raw_network.count(raw.LoadRecord)}")
46
+ print(f"Generators: {raw_network.count(raw.GeneratorRecord)}")
47
+
48
+ for bus in raw_network.list_by_class(raw.BusRecord):
49
+ print(f" Bus {bus.bus_number}: {bus.name}, {bus.base_voltage} kV")
50
+ ```
51
+
52
+ > **Note:** the reader used to return a `RawModel` container with
53
+ > `.bus_records` / `.load_records` list attributes. That container is gone —
54
+ > use `count()` / `list_by_class()` / `find_by_attribute()` instead.
55
+
56
+ ### 1a. Basic editing style
57
+
58
+ Records live at `raw_network.graph[RecordClass][identifier]`. The identifier is
59
+ the composite key the reader assigns per record type (see the table below), so
60
+ you can look a record up directly and mutate its fields in place:
61
+
62
+ ```python
63
+ import cimhub_raw.schema.raw_v34.raw34_schema as raw
64
+
65
+ # Direct access by composite identifier — generator id "3" on bus 10111:
66
+ gen = raw_network.graph[raw.GeneratorRecord]['10111_3']
67
+ gen.p_output = 250.0 # set active power (MW)
68
+ gen.q_output = 40.0 # set reactive power (MVAr)
69
+
70
+ # Or find a record without knowing its exact key:
71
+ (bus,) = raw_network.find_by_attribute(raw.BusRecord, 'bus_number', 10111)
72
+ bus.base_voltage = 138.0
73
+
74
+ # find_by_attribute returns a LIST (exact string match), so index or unpack it:
75
+ loads = raw_network.find_by_attribute(raw.LoadRecord, 'bus_number', 10111)
76
+ for load in loads:
77
+ load.status = 0 # take every load on the bus out of service
78
+ ```
79
+
80
+ **Composite identifier keys** (what to put in `graph[Cls][...]`):
81
+
82
+ | Record | Identifier key |
83
+ |---|---|
84
+ | `BusRecord` | `bus_number` |
85
+ | `LoadRecord` | `bus_number_loadid` |
86
+ | `FixedShuntRecord` | `bus_number_shuntid` |
87
+ | `GeneratorRecord` | `bus_number_genid` |
88
+ | `BranchRecord` / `SwitchRecord` | `from_to_ckt` |
89
+ | `TransformerRecord` | `i_j_k_ckt` |
90
+ | `SwitchedShuntRecord` | `bus_number` |
91
+ | `VscDcRecord` | `name_ibus` |
92
+
93
+ If you don't know the exact key, `find_by_attribute(cls, attr, value)` is the
94
+ safe path — it matches on the string form of any field.
95
+
96
+ ### 2. Write a RAW file
97
+
98
+ The writer's standard input is a `GraphModel` — pass the one you read/edited
99
+ straight to `write()`:
100
+
101
+ ```python
102
+ from cimhub_raw.exporter.raw34_writer import Raw34Writer
103
+
104
+ writer = Raw34Writer()
105
+ writer.write(raw_network, "output.raw")
106
+ ```
107
+
108
+ To render a single record without writing a file, use `writer.serialize(obj)`.
109
+
110
+ ### 3. RAW → RAW round-trip (read + write, no CIM)
111
+
112
+ ```python
113
+ from cimhub_raw.importer.raw34_reader import Raw34Reader
114
+ from cimhub_raw.exporter.raw34_writer import Raw34Writer
115
+
116
+ raw_network = Raw34Reader("network.raw").read_all()
117
+ Raw34Writer().write(raw_network, "output.raw")
118
+ ```
119
+
120
+ ### 4. RAW → CIM
121
+
122
+ Convert a RAW file to a CIM `NodeBreakerModel` (cimgraph):
123
+
124
+ ```python
125
+ import os
126
+ os.environ.setdefault("CIMG_CIM_PROFILE", "cim17v40")
127
+
128
+ from cimhub_raw.importer.raw34_to_cim import raw34_to_cim
129
+ import cimhub_raw.schema.data_profile as cim
130
+
131
+ network = raw34_to_cim("network.raw")
132
+
133
+ buses = network.list_by_class(cim.TopologicalNode)
134
+ loads = network.list_by_class(cim.EnergyConsumer)
135
+ gens = network.list_by_class(cim.SynchronousMachine)
136
+
137
+ print(f"Buses: {len(buses)}, Loads: {len(loads)}, Generators: {len(gens)}")
138
+ ```
139
+
140
+ Pass `include_extensions=True` to attach raw_extension objects (e.g. `RawBusRecord`)
141
+ alongside each CIM object — useful for lossless round-trips:
142
+
143
+ ```python
144
+ network = raw34_to_cim("network.raw", include_extensions=True)
145
+ ```
146
+
147
+ ### 5. CIM → RAW
148
+
149
+ Export a CIM `BusBranchModel` back to a RAW file:
150
+
151
+ ```python
152
+ from cimhub_raw.exporter.cim_to_raw import cim_to_raw
153
+
154
+ cim_to_raw(network, "output.raw")
155
+ ```
156
+
157
+ Or build the intermediate `GraphModel` first (e.g. to inspect before writing):
158
+
159
+ ```python
160
+ from cimhub_raw.exporter.cim_to_raw import Raw34Exporter
161
+ from cimhub_raw.exporter.raw34_writer import Raw34Writer
162
+
163
+ raw_model = Raw34Exporter().to_model(network, system_base_mva=100.0)
164
+ writer = Raw34Writer()
165
+ writer.write(raw_model, "output.raw")
166
+ ```
167
+
168
+ ### 6. Full RAW → CIM → RAW round-trip
169
+
170
+ ```python
171
+ import os
172
+ os.environ.setdefault("CIMG_CIM_PROFILE", "cim17v40")
173
+
174
+ from cimhub_raw.importer.raw34_to_cim import raw34_to_cim
175
+ from cimhub_raw.exporter.cim_to_raw import cim_to_raw
176
+
177
+ network = raw34_to_cim("network.raw", include_extensions=True)
178
+ cim_to_raw(network, "output.raw")
179
+ ```
180
+
181
+ ### 7. Serialize CIM to XML / JSON-LD
182
+
183
+ Once you have a CIM network model, serialize it to CIM XML or JSON-LD:
184
+
185
+ ```python
186
+ from cimgraph.utils import write_xml, write_json_ld
187
+
188
+ write_xml(network, "network.xml")
189
+ write_json_ld(network, "network.jsonld")
190
+ ```
191
+
192
+ ---
193
+
194
+ ## Equipment Coverage
195
+
196
+ ### Fully converted (RAW ↔ CIM)
197
+
198
+ | RAW Record | CIM Class(es) |
199
+ |---|---|
200
+ | BusRecord | `TopologicalNode`, `ConnectivityNode` |
201
+ | LoadRecord | `EnergyConsumer` |
202
+ | GeneratorRecord | `SynchronousMachine` |
203
+ | FixedShuntRecord | `LinearShuntCompensator` (single-section) |
204
+ | SwitchedShuntRecord | `LinearShuntCompensator` (multi-section) |
205
+ | BranchRecord | `ACLineSegment`, `SeriesCompensator`, `Breaker` |
206
+ | TransformerRecord | `PowerTransformer` (2-winding) |
207
+ | TwoTerminalDCRecord | `DCLineSegment` + `CsConverter` x2 |
208
+ | VscDcRecord | `DCLineSegment` + `VsConverter` x2 |
209
+ | FactsDeviceRecord | `StaticVarCompensator`, `VsConverter` |
210
+ | InductionMachineRecord | `AsynchronousMachine` |
211
+ | AreaInterchangeRecord | `ControlArea` / `SubControlArea` |
212
+ | ZoneRecord | `SubGeographicalRegion` |
213
+ | OwnerRecord | `AssetOwner` |
214
+ | MultiSectionLineRecord | `Line` (container grouping) |
215
+ | SwitchRecord | `Switch` / `Breaker` |
216
+
217
+ ### Passthrough only (read + write, no CIM conversion)
218
+
219
+ These record types are parsed and written verbatim but have no CIM mapping:
220
+
221
+ | RAW Record | Reason |
222
+ |---|---|
223
+ | InterareaTransferRecord | No standard CIM equivalent |
224
+ | ImpedanceCorrectionRecord | No CIM class in the CIM 17 profile |
225
+ | MultiTerminalDCRecord | Sub-records (converters, bus links) not fully parsed |
226
+ | GneDeviceRecord | Generic extensible model; depends on `model` field |
227
+
228
+ ---
229
+
230
+ ## Running Tests
231
+
232
+ ```bash
233
+ # From the repo root
234
+ uv run pytest cimhub_raw/tests/
235
+
236
+ # Key test files
237
+ uv run pytest cimhub_raw/tests/test_raw34_roundtrip.py # RAW → RAW (no CIM)
238
+ uv run pytest cimhub_raw/tests/test_ieee14_roundtrip.py # Full RAW → CIM → RAW
239
+ uv run pytest cimhub_raw/tests/test_production_roundtrip.py # 169-bus production model
240
+ ```
241
+
242
+ ---
243
+
244
+ ## TODO
245
+
246
+ ### CIM mappings needed for passthrough record types
247
+
248
+ These record types are currently read and written verbatim (no CIM conversion).
249
+ Implementing them requires either finding an appropriate CIM class or extending the data profile.
250
+
251
+ #### 1. `InterareaTransferRecord`
252
+ - Represents scheduled power transfers between control areas.
253
+ - No direct CIM equivalent in CIM 17. Closest candidates: `TieFlow` or a custom extension.
254
+ - Work needed: define CIM mapping, implement importer + exporter, add tests.
255
+
256
+ #### 2. `ImpedanceCorrectionRecord`
257
+ - Tap-dependent impedance correction tables for transformers.
258
+ - No CIM class in the CIM 17 profile. Closest: `TransformerMeshImpedance` or a raw_extension.
259
+ - Work needed: define CIM mapping or raw_extension class, implement importer + exporter, add tests.
260
+
261
+ #### 3. `MultiTerminalDCRecord`
262
+ - Represents multi-terminal HVDC lines (3+ converter stations).
263
+ - CIM has `DCNode`, `DCTopologicalNode`, `DCConverterUnit` — mapping is feasible but complex.
264
+ - Current reader only parses the header line; converter/bus/link sub-records are skipped.
265
+ - Work needed: extend reader to parse all sub-record types, define CIM mapping, implement importer + exporter.
266
+
267
+ #### 4. `GneDeviceRecord`
268
+ - Generic network element: a catch-all for vendor-specific dynamic models.
269
+ - No universal CIM mapping — depends on the `model` field value.
270
+ - Work needed: case-by-case assessment per model type; may require raw_extension approach.
271
+
272
+ ### Other known gaps
273
+
274
+ - **3-winding transformers**: `TransformerRecord` currently handles 2-winding only. 3-winding transformers are represented as a star (3 × 2-winding) in raw; CIM uses `PowerTransformerEnd` with 3 ends. Needs dedicated handling.
275
+ - **Multi-terminal DC importer registration**: `MultiTerminalDCRecord` is not in `IMPORT_ORDER` in `raw34_to_cim.py`.
276
+
277
+
278
+
279
+ ## Legacy PSS/E RAW extension layer (`cimgraph_raw_extension`). Provides raw-extension dataclasses that can be attached alongside CIM objects during a PSS/E import to preserve fields that have no direct CIM mapping.
280
+
281
+
282
+ ### Usage
283
+
284
+ ```python
285
+ from cimgraph_raw_extension.converters.rawToCim import raw_to_cim
286
+ from cimgraph_raw_extension.converters.cimToRaw import cim_to_raw
287
+
288
+ # Import RAW → CIM with extensions attached
289
+ network = raw_to_cim("network.raw")
290
+
291
+ # Export CIM → RAW
292
+ cim_to_raw(network, "output.raw")
293
+ ```
294
+
295
+ ## Structure
296
+
297
+ ```
298
+ src/cimgraph_raw_extension/
299
+ data_profile/raw_extension.py # Extension dataclasses (RawBusRecord, etc.)
300
+ models/rawModel.py # RawModel container (legacy)
301
+ converters/rawToCim.py # RAW → CIM conversion
302
+ converters/cimToRaw.py # CIM → RAW conversion
303
+ ```
304
+
@@ -0,0 +1,47 @@
1
+ [build-system]
2
+ requires = ["setuptools~=80.9"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "cimhub_raw"
7
+ description = "CIMHub PSS/E Library"
8
+ authors = [
9
+ { name = "Andrew R Fisher", email = "andrew.fisher@pnnl.gov" }
10
+ ]
11
+ readme = "README.md"
12
+ version = "2.0.0a2"
13
+ requires-python = ">=3.10"
14
+ classifiers = [
15
+ "Programming Language :: Python :: 3",
16
+ "Operating System :: OS Independent",
17
+ "Environment :: Console"
18
+ ]
19
+
20
+ dependencies = [
21
+ "cimhub_core >=2.0.0a2,<2.1",
22
+ "networkx"
23
+ ]
24
+
25
+ [project.urls]
26
+ "Homepage" = "https://github.com/PNNL-CIM-Tools/CIMHub_2_0"
27
+ "Bug Tracker" = "https://github.com/PNNL-CIM-Tools/CIMHub_2_0"
28
+
29
+ [tool.coverage.report]
30
+ skip_empty = true
31
+
32
+ [tool.mypy]
33
+ strict = false
34
+ ignore_missing_imports = false
35
+ disallow_untyped_defs = false
36
+ warn_unused_ignores = true
37
+ warn_unreachable = true
38
+
39
+ [tool.setuptools]
40
+ # Scope to cimhub_raw only. src/ also holds the superseded
41
+ # cimgraph_raw_extension package, which must not be published: it would ship
42
+ # dead code and claim a second top-level import name on PyPI. It stays in the
43
+ # repo for the legacy tests that still exercise it.
44
+ packages = { find = { where = ["src"], include = ["cimhub_raw*"] } }
45
+
46
+ [tool.setuptools.package-data]
47
+ "*" = ["*.json", "*.yaml"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,28 @@
1
+ # cimhub_raw/exporter/__init__.py
2
+ """CIM to raw RAW format exporters."""
3
+
4
+ from .registry import raw_exporter_registry
5
+
6
+ # Import converters to register them
7
+ from .topology.connectivity_node import convert_all_buses, convert_topological_node
8
+ from .loads.energy_consumer import convert_all_loads, convert_energy_consumer
9
+ from .lines.ac_line_segment import convert_all_lines, convert_ac_line_segment
10
+ from .generators.synchronous_machine import convert_all_generators, convert_synchronous_machine
11
+ from .transformers.power_transformer import convert_all_transformers, convert_power_transformer
12
+ from .lines.retained_breaker import convert_all_breakers, convert_breaker
13
+ from .series.series_compensator import convert_all_series_compensators, convert_series_compensator
14
+ from .shunts.shunt_compensator import convert_shunt_compensator, convert_all_shunt_compensators
15
+
16
+ __all__ = [
17
+ "raw_exporter_registry",
18
+ "convert_all_buses",
19
+ "convert_topological_node",
20
+ "convert_all_loads",
21
+ "convert_energy_consumer",
22
+ "convert_all_lines",
23
+ "convert_ac_line_segment",
24
+ "convert_all_generators",
25
+ "convert_synchronous_machine",
26
+ "convert_all_transformers",
27
+ "convert_power_transformer"
28
+ ]