# aceiot-cim-rdf

`aceiot-cim-rdf` converts power-system network models from PSS/E-style IEEE RAW files into CIM RDF serialized as Turtle. It also includes schema-derived Pydantic models for CGMES/CIM classes and helpers for RDF serialization, deserialization, and model regeneration from external RDFS profile files.

The project is currently focused on practical RAW-to-CIM conversion for common steady-state network elements and ships with an IEEE 14-bus sample model for validation.

## Features

- Parse PSS/E v33-style RAW files.
- Convert buses, loads, generators, AC branches, two-winding transformers, fixed shunts, terminals, voltage levels, substations, topology nodes, and base voltages into CIM objects.
- Serialize generated CIM objects to RDF/Turtle with `rdflib`.
- Include Dublin Core Terms provenance in Turtle output for the bundled IEEE 14-bus sample data.
- Deserialize Turtle back into registered Pydantic CIM model objects.
- Generate Pydantic CIM model classes from ENTSO-E CGMES 2.4.15 RDFS profile definitions supplied locally.
- Validate conversion behavior with pytest, including IEEE 14-bus regression tests and RDF round-trip isomorphism checks.

## Project Status

This is an early-stage converter. It is suitable for experimentation, testing workflows, and extending RAW-to-CIM mapping logic, but it should be reviewed before use in production interchange pipelines.

Current limitations include:

- RAW parsing targets the sections and field positions covered by the current tests.
- Conversion mappings are intentionally small and do not yet cover every PSS/E record type or every CGMES profile requirement.
- RDF output is useful for graph workflows, but full CGMES conformance validation is not yet implemented.

## Installation

This project uses Python 3.13 or newer.

Install the published package from PyPI:

```bash
python -m pip install aceiot-cim-rdf
```

Or with `uv`:

```bash
uv add aceiot-cim-rdf
```

After installation, the `ieee-to-cim` command is available on your PATH.

For local development, clone the repository and install dependencies with `uv`:

With `uv`:

```bash
uv sync
```

Or with `pip`:

```bash
python -m pip install .
```

For development dependencies:

```bash
uv sync --group dev
```

## Usage

### CLI

Convert a RAW file to Turtle:

```bash
uv run ieee-to-cim "IEEE 14-Bus System/IEEE 14 bus.raw" ieee14_cim.ttl
```

Run the same conversion with a deserialize/serialize round-trip object-count check:

```bash
uv run ieee-to-cim "IEEE 14-Bus System/IEEE 14 bus.raw" ieee14_cim.ttl --validate
```

After installing the package, the console script is available directly:

```bash
ieee-to-cim model.raw model.ttl --validate
```

### Python API

```python
from aceiot_cim_rdf import parse_raw, convert_to_cim, serialize_to_turtle

raw_data = parse_raw("model.raw")
cim_objects = convert_to_cim(raw_data)
turtle = serialize_to_turtle(cim_objects)

with open("model.ttl", "w") as f:
    f.write(turtle)
```

Deserialize Turtle back into registered CIM model objects:

```python
from aceiot_cim_rdf import deserialize_from_turtle

objects = deserialize_from_turtle(turtle)
```

## Development

Run the test suite:

```bash
uv run pytest
```

Run linting:

```bash
uv run ruff check .
```

Build the package:

```bash
uv build
```

The wheel excludes large reference and sample-data directories configured in `pyproject.toml`.

## Repository Layout

```text
src/aceiot_cim_rdf/
  cli.py                    Command-line interface.
  conversion.py             RAW parser and RAW-to-CIM conversion logic.
  parser.py                 RDFS parser and Pydantic model generator.
  cim_pydantic/
    base.py                 CIM base model, registry, and RDF helpers.
    models/                 Generated CIM/CGMES Pydantic models.

tests/                      Parser, converter, and RDF round-trip tests.
IEEE 14-Bus System/         Sample IEEE 14-bus RAW/EPC/PWB/PWD files.
```

## Regenerating CIM Models

The generated model set lives under `src/aceiot_cim_rdf/cim_pydantic/models/`. The schema parser can regenerate profile modules from a local directory containing ENTSO-E CGMES RDFS files:

```python
from aceiot_cim_rdf.parser import SchemaParser

parser = SchemaParser("/path/to/ENTSOE_CGMES_v2.4.15_16Feb2016_RDFS")
parser.parse()
parser.generate("src/aceiot_cim_rdf/cim_pydantic")
```

The generator writes concrete classes into profile-specific modules and keeps `models/all.py` as a compatibility aggregate for older imports.

## Dataset Credits

When converting the bundled IEEE 14-bus RAW file, the CLI adds RDF provenance metadata referencing the Texas A&M Electric Grid Test Case Repository and the University of Washington Power Systems Test Case Archive. Texas A&M describes the IEEE 14-bus system as a simple approximation of the American Electric Power system as of February 1962 and encourages users to cite the appropriate sources when using the dataset.

## License

MIT. See the project metadata in `pyproject.toml`.
