Metadata-Version: 2.4
Name: cimhub_matpower
Version: 2.0.0a1
Summary: CIMHub Matpower 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
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.1,>=2.0.0a2

# cimhub_matpower

Bidirectional converter between MATPOWER (`.m` case files) and CIM (IEC 61970) using the `cim17v40` profile.

## Usage

### MATPOWER to CIM (Import)

```python
import os
os.environ['CIMG_CIM_PROFILE'] = 'cim17v40'

from cimhub_matpower.importer.matpower_to_cim import matpower_to_cim

network = matpower_to_cim("case9.m")
```

### CIM to MATPOWER (Export)

```python
from cimhub_matpower.exporter.cim_to_matpower import cim_to_matpower

cim_to_matpower(network, "output.m")
```

## Equipment Coverage

| MATPOWER Field | CIM Class(es) |
|---|---|
| `bus` | `TopologicalNode`, `ConnectivityNode`, `BaseVoltage` |
| `gen` | `SynchronousMachine`, `GeneratingUnit` |
| `branch` | `ACLineSegment`, `PowerTransformer` |
| `gencost` | `GrossToNetActivePowerCurve` |
| `areas` | `ControlArea` |

## Unit Conventions

MATPOWER uses per-unit impedances on the system MVA base. The converter handles the `z_base = base_kv² / base_mva` conversion automatically — do not manually multiply by `baseMVA`.

Generator sign convention: MATPOWER `Pg` is positive for generation (power out). CIM `Terminal.p` is positive for power flowing **into** equipment — the converter negates when crossing the boundary.

## Running Tests

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

## Status

- **Importer**: functional for buses, generators, branches, gencost, areas.
- **Exporter**: implemented; full roundtrip tests in progress.
- **Known gap**: reactive power limits (`Qmin`/`Qmax`) and transformer tap ratios need validation.
