cimoxide

Python bindings for cimoxide, a Rust toolkit for ENTSO-E CGMES (Common Grid Model Exchange Standard) power system data. This package wraps the Rust decoder and SHACL/SPARQL validator (via PyO3) to give you fast RDF/XML parsing and CGMES conformance validation from Python, with no Rust toolchain required at install time.

Install

pip install cimoxide

Prebuilt wheels are published for common platforms; if none match your environment, pip will need a Rust toolchain and maturin to build from source.

Quick start

import cimoxide

# Parse one or more CGMES RDF/XML files into a single merged dataset.
ds = cimoxide.decode_files([
    "RealGrid_EQ.xml",
    "RealGrid_SSH.xml",
    "RealGrid_TP.xml",
    "RealGrid_SV.xml",
])

len(ds)                       # total number of elements
ds.by_type()                  # {"ACLineSegment": [mrid, ...], ...} — no deserialization
ds.get_type("ACLineSegment")  # [{"_type": "ACLineSegment", "r": 0.12, ...}, ...]

for mrid in ds:
    obj = ds[mrid]             # dict, e.g. {"_type": "BusbarSection", "name": "...", ...}

Each element is a plain Python dict with a "_type" key (the CIM class name) plus one key per populated attribute, snake_case, matching the JSON serialization of the underlying Rust structs. Reference fields (MRID associations) are plain MRID strings.

Modify and re-encode

CimDataset supports dict-style assignment and deletion, so you can edit elements in place and write the result back out as CGMES profile XML:

# Edit an existing element (read, mutate the dict, assign it back).
line = ds["ACLineSegment.1"]
line["r"] = 0.15
ds["ACLineSegment.1"] = line

# Add a brand-new element the same way — the "_type" key selects the CIM class.
ds["BaseVoltage.NEW"] = {"_type": "BaseVoltage", "id": "BaseVoltage.NEW", "nominal_voltage": 110.0}

# Remove one.
del ds["ACLineSegment.2"]

# Encode a single profile as an RDF/XML string.
eq_xml = ds.to_xml_for_profile("EQ")

# Or write a full profile set straight to a directory: dir/EQ.xml, dir/SSH.xml, ...
ds.write_xml_files("out/", ["EQ", "SSH", "TP", "SV"])

to_xml_for_profile/write_xml_files only emit elements and fields whose CIM schema origin includes the requested profile. If the dataset still has the decoded FullModel header for that profile (from the original source file), it's reused verbatim (scenarioTime, modelingAuthoritySet, version, DependentOn, ...); otherwise a minimal header is synthesized.

Validation

violations = cimoxide.validate_files(
    ["RealGrid_EQ.xml", "RealGrid_SSH.xml"],
    profiles=["EQ", "SSH"],   # optional; auto-detected if omitted
)

for v in violations:
    print(v.severity, v.rule_id, v.message, v.object_id)

validate_files runs two-phase validation: per-profile SHACL/SPARQL checks against each file individually, then cross-profile checks on the merged dataset. See the validate_files docstring for the full parameter list (solved, common, quality, silence).

API surface

Function / method	Description
`cimoxide.decode_file(path)`	Parse a single RDF/XML file.
`cimoxide.decode_files(paths)`	Parse and merge multiple RDF/XML files.
`cimoxide.decode_str(content)`	Parse RDF/XML from a string.
`cimoxide.validate_files(paths, ...)`	Two-phase SHACL/SPARQL validation, returns `list[Violation]`.
`CimDataset.merge(other)`	Merge another dataset into this one (`other` becomes empty).
`CimDataset.drop_blocks()`	Free internal parse buffers after the final merge.
`CimDataset[mrid]` / `.get(mrid)`	Fetch one element as a dict (`KeyError` / `None` if missing).
`CimDataset[mrid] = {...}`	Insert or replace the element at `mrid`.
`del CimDataset[mrid]`	Remove the element at `mrid` (`KeyError` if missing).
`CimDataset.mrids()` / `iter(ds)` / `len(ds)`	Enumerate or count MRIDs.
`CimDataset.by_type()`	`dict[str, list[mrid]]` type index, no deserialization.
`CimDataset.get_type(name)`	All element dicts for one CIM class.
`CimDataset.entries()`	All entries as `dict[mrid, dict]` (deserializes everything).
`CimDataset.to_xml_for_profile(profile)`	Encode one CGMES profile (e.g. `"EQ"`) as an RDF/XML string.
`CimDataset.write_xml_files(dir, profiles)`	Write one RDF/XML file per profile into `dir`.

Full type stubs with per-method docstrings are in python/cimoxide/__init__.pyi and python/cimoxide/types.pyi (generated TypedDict per CIM class, for editor autocomplete on the returned dicts).

Examples

examples/example_counts.py decodes the RealGrid test configuration and prints an element count per CIM type:

python examples/example_counts.py

examples/example_encode.py decodes RealGrid, encodes it back to EQ/SSH/TP/SV profile files (in a temp directory by default, or the directory given as an argument), then re-decodes the output to confirm the round-trip is lossless:

python examples/example_encode.py [output-dir]

Both require the CGMES-Test-Configurations submodule checked out at the repo root — see "Development" below.

Benchmark

examples/benchmark_realgrid.py times decode_files, write_xml_files, and validate_files against the full RealGrid dataset and reports best/mean wall time plus MB/s throughput for each:

python examples/benchmark_realgrid.py [iterations]   # default: 3

Also requires the CGMES-Test-Configurations submodule.

Tests

The test suite decodes and validates the CGMES fixture files checked into the parent repository's testdata/ directory:

pip install pytest
pytest tests/

tests/test_decode.py — round-trip decode tests (decode_file/decode_str/decode_files, indexing, iteration).
tests/test_api.py — dataset API contract tests (merge, drop_blocks, mutation via __setitem__/__delitem__, error handling).
tests/test_encode.py — to_xml_for_profile/write_xml_files behavior, including FullModel header reuse against a real CGMES fixture.
tests/test_validate.py — validate_files behavior (profile filtering, silence, quality/common flags, Violation fields).

Development

This package is built from the cimoxide monorepo, where cimoxide-py lives alongside the Rust crates it binds (cimdecoder, cimstructs, cimvalidation, cimconvert). To build it from source:

# for ubuntu
git clone --recurse-submodules https://github.com/m-mirz/cimoxide.git
cd cimoxide
python3 -m venv .venv
source .venv/bin/activate
pip3 install maturin
cd cimoxide-py
maturin develop --release   # editable install into the active virtualenv
pip3 install pytest
pytest tests/

See the repository README for the full project layout, the code generator, and the Rust CLI.

License

Apache-2.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cimoxide-0.1.1.tar.gz (856.3 kB view details)

Uploaded Jul 14, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

cimoxide-0.1.1-cp39-abi3-win_amd64.whl (9.0 MB view details)

Uploaded Jul 14, 2026 CPython 3.9+Windows x86-64

cimoxide-0.1.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (7.8 MB view details)

Uploaded Jul 14, 2026 CPython 3.9+manylinux: glibc 2.17+ x86-64

cimoxide-0.1.1-cp39-abi3-macosx_11_0_arm64.whl (7.3 MB view details)

Uploaded Jul 14, 2026 CPython 3.9+macOS 11.0+ ARM64

File details

Details for the file cimoxide-0.1.1.tar.gz.

File metadata

Download URL: cimoxide-0.1.1.tar.gz
Upload date: Jul 14, 2026
Size: 856.3 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for cimoxide-0.1.1.tar.gz
Algorithm	Hash digest
SHA256	`0ac78778135b20c5f6c09bba4eff6c553f4d02bcebda10fae3532870e58b24bc`
MD5	`f5a70fdaad5a9b741b6481ecbc313109`
BLAKE2b-256	`d515009e62bada4bff9170199ebe2f089069c0235c40384d49612494f84881d7`

See more details on using hashes here.

Provenance

The following attestation bundles were made for cimoxide-0.1.1.tar.gz:

Publisher: pypi.yml on m-mirz/cimoxide

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: cimoxide-0.1.1.tar.gz
- Subject digest: 0ac78778135b20c5f6c09bba4eff6c553f4d02bcebda10fae3532870e58b24bc
- Sigstore transparency entry: 2168747675
- Sigstore integration time: Jul 14, 2026
Source repository:
- Permalink: m-mirz/cimoxide@185c40dd34100dc7857d99084995646a86dc8792
- Branch / Tag: refs/tags/v0.1.1
- Owner: https://github.com/m-mirz
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: pypi.yml@185c40dd34100dc7857d99084995646a86dc8792
- Trigger Event: push

File details

Details for the file cimoxide-0.1.1-cp39-abi3-win_amd64.whl.

File metadata

Download URL: cimoxide-0.1.1-cp39-abi3-win_amd64.whl
Upload date: Jul 14, 2026
Size: 9.0 MB
Tags: CPython 3.9+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for cimoxide-0.1.1-cp39-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`328916c8267005ac7dcab11e2de4ae6f62e219302ddfb476b1b495dd09694177`
MD5	`abab3fd6be0f590d7825d73ab61deec4`
BLAKE2b-256	`3eb3fd8a370fc4f2c449d00379b1d4053046c6e23ff61638dded943c3df3b46e`

See more details on using hashes here.

Provenance

The following attestation bundles were made for cimoxide-0.1.1-cp39-abi3-win_amd64.whl:

Publisher: pypi.yml on m-mirz/cimoxide

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: cimoxide-0.1.1-cp39-abi3-win_amd64.whl
- Subject digest: 328916c8267005ac7dcab11e2de4ae6f62e219302ddfb476b1b495dd09694177
- Sigstore transparency entry: 2168747714
- Sigstore integration time: Jul 14, 2026
Source repository:
- Permalink: m-mirz/cimoxide@185c40dd34100dc7857d99084995646a86dc8792
- Branch / Tag: refs/tags/v0.1.1
- Owner: https://github.com/m-mirz
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: pypi.yml@185c40dd34100dc7857d99084995646a86dc8792
- Trigger Event: push

File details

Details for the file cimoxide-0.1.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: cimoxide-0.1.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Jul 14, 2026
Size: 7.8 MB
Tags: CPython 3.9+, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for cimoxide-0.1.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`8cc264806fc0297b1adf3b85ebd9b2eb47fdd5806ab87a91d4fb00c58533add8`
MD5	`9c9678cfbfd1ac8b613bb102b30bb2f7`
BLAKE2b-256	`8d03d0a5ac8bfbab58c9eacf379ff37d689a7583b7fa5b5e81b0127d966f4e24`

See more details on using hashes here.

Provenance

The following attestation bundles were made for cimoxide-0.1.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: pypi.yml on m-mirz/cimoxide

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: cimoxide-0.1.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Subject digest: 8cc264806fc0297b1adf3b85ebd9b2eb47fdd5806ab87a91d4fb00c58533add8
- Sigstore transparency entry: 2168747746
- Sigstore integration time: Jul 14, 2026
Source repository:
- Permalink: m-mirz/cimoxide@185c40dd34100dc7857d99084995646a86dc8792
- Branch / Tag: refs/tags/v0.1.1
- Owner: https://github.com/m-mirz
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: pypi.yml@185c40dd34100dc7857d99084995646a86dc8792
- Trigger Event: push

File details

Details for the file cimoxide-0.1.1-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: cimoxide-0.1.1-cp39-abi3-macosx_11_0_arm64.whl
Upload date: Jul 14, 2026
Size: 7.3 MB
Tags: CPython 3.9+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for cimoxide-0.1.1-cp39-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`5ae0389ae5a7c02b89cc4a2aa4a03f2ecf49d3085d33240f827961c9a3febd10`
MD5	`4411b1acec619cc5e5f411d931529cc5`
BLAKE2b-256	`ddd4f2ac9d4d4d3a6cfe3587517dc9ef9b30f1786748466396de7bf3605d012e`

See more details on using hashes here.

Provenance

The following attestation bundles were made for cimoxide-0.1.1-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: pypi.yml on m-mirz/cimoxide

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: cimoxide-0.1.1-cp39-abi3-macosx_11_0_arm64.whl
- Subject digest: 5ae0389ae5a7c02b89cc4a2aa4a03f2ecf49d3085d33240f827961c9a3febd10
- Sigstore transparency entry: 2168747802
- Sigstore integration time: Jul 14, 2026
Source repository:
- Permalink: m-mirz/cimoxide@185c40dd34100dc7857d99084995646a86dc8792
- Branch / Tag: refs/tags/v0.1.1
- Owner: https://github.com/m-mirz
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: pypi.yml@185c40dd34100dc7857d99084995646a86dc8792
- Trigger Event: push

Release history Release notifications | RSS feed

This release

0.1.1

Jul 14, 2026

0.0.5

Jul 14, 2026

0.0.4

May 25, 2026

cimoxide 0.1.1

cimoxide

Install

Quick start

Modify and re-encode

Validation

API surface

Examples

Benchmark

Tests

Development

License

Project links

Key dates

1 maintainer

GitHub Statistics

License expression

Requires

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed