Metadata-Version: 2.4
Name: cimhub_gridlabd
Version: 2.0.0a1
Summary: CIMHub GridLAB-D Library
Author-email: Pacific Northwest National Laboratory <gridappsd@pnnl.gov>
License: BSD-2-Clause
Project-URL: Homepage, https://github.com/PNNL-CIM-Tools/CIMHub_2_0
Project-URL: Bug Tracker, https://github.com/PNNL-CIM-Tools/CIMHub_2_0/issues
Project-URL: Documentation, https://cimhub-gridlabd.readthedocs.io/
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: cimhub_core~=2.0.0a2
Requires-Dist: pandas>=2.3.3

# cimhub_gridlabd

Bidirectional converter between GridLAB-D (GLM) and CIM (IEC 61968/61970) using the `cimhub_2026` profile.

## Usage

### GLM to CIM (Import)

```python
import os
os.environ['CIMG_USE_UNITS'] = 'TRUE'
os.environ['CIMG_CIM_PROFILE'] = 'cimhub_2026'

from cimhub_gridlabd.importer.glm_to_cim import glm_to_cim

feeder = glm_to_cim("/path/to/IEEE13.glm")
```

### CIM to GLM (Export)

Export is two steps: build the GLM model, then write it.

```python
from cimhub_gridlabd.exporter.cim_to_glm import GlmExporter
from cimhub_gridlabd.exporter.glm_text_writer import GlmTextWriter

glm_model = GlmExporter().to_model(feeder)
GlmTextWriter().write(glm_model, "/path/to/IEEE13.glm")
```

`to_model` returns an in-memory `GraphModel` of GLM dataclasses, so you can
inspect or edit the model before it is serialized.

### JSON variant

Swap in the GLM-JSON writer (one object per JSON entry, grouped by class):

```python
from cimhub_gridlabd.exporter.cim_to_glm import GlmExporter
from cimhub_gridlabd.exporter.glm_writer import GlmJsonWriter

glm_model = GlmExporter().to_model(feeder)
GlmJsonWriter().write(glm_model, "/path/to/IEEE13.json")
```

Or use the one-line convenience wrapper:

```python
from cimhub_gridlabd.exporter.cim_to_glm import cim_to_glm_json

cim_to_glm_json(feeder, "/path/to/IEEE13.json")
```

## Architecture

The package follows the standard CIMHub four-layer pipeline:

```
LinkML YAML  →  glm_schema.py  →  GraphModel  →  GlmReader / GlmWriter
                                        ↕
                              GlmImporter / GlmExporter
```

The writer is annotation-driven: LinkML slot annotations (`native_name`, `glm_unit`, etc.) control how each CIM field maps to a GLM attribute without hard-coded per-class logic. See `GLM_LINKML_ARCHITECTURE.md` for the full design.

## Equipment Coverage

| Element | Import | Export |
|---|---|---|
| Overhead lines (geometry) | ✓ | ✓ |
| Underground cables | ✓ | ✓ |
| Transformers | ✓ | ✓ |
| Regulators | ✓ | ✓ |
| Capacitor banks | ✓ | ✓ |
| Loads | ✓ | ✓ |
| Switches / reclosers / fuses | ✓ | ✓ |
| DER (PV, battery) | partial | partial |

## Running Tests

```bash
uv run pytest cimhub_gridlabd/tests/ -v
```

## Notes

- **Never substitute a computed impedance matrix for conductor geometry.** When `WireSpacingInfo` is present, export it as native GridLAB-D `line_spacing` + `overhead_line_conductor` objects. See `cimhub_core/development/CONDUCTOR_GEOMETRY_ANTI_PATTERNS.md`.
- Python complex literals (`+0.79+0.43j`) are not valid GLM syntax — the writer uses explicit `r` / `x` fields.
- Phase lookups must traverse from `ACLineSegment.ACLineSegmentPhases`, not from `WireSpacingInfo.ACLineSegment[0]` (that list can be empty).
