Skip to main content

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, ...], ...} — copies the whole index
ds.count_type("ACLineSegment")  # 7561 — O(1), copies nothing
ds.get_type("ACLineSegment")  # [{"_type": "ACLineSegment", "ACLineSegment.r": "0.12", ...}, ...]

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

Each element is a plain Python dict with "_type" (the CIM class name) and "id" (the mRID), plus one key per attribute the XML carried, named "Class.attr" as in the XML. Every value is the string the XML wrote — numbers are not parsed — and a reference is the referenced mRID; an attribute written more than once is a list of 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["ACLineSegment.r"] = "0.15"
ds["ACLineSegment.1"] = line

# Add a brand-new element the same way — the "_type" key selects the CIM class, which
# also says which keys are references.
ds["BaseVoltage.NEW"] = {"_type": "BaseVoltage", "id": "BaseVoltage.NEW", "BaseVoltage.nominalVoltage": "110"}

# 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 multiple RDF/XML files in parallel (one thread each, GIL released) and merge them.
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[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; copies one str per MRID.
CimDataset.count_type(name) Number of elements of one CIM class. O(1), copies nothing.
CimDataset.get_type(name) All element dicts for one CIM class.
CimDataset.entries() All entries as dict[mrid, dict] (deserializes everything).
CimDataset.query(sparql) Run SPARQL 1.1 over the dataset. Builds an RDF graph on first call, then caches it.
CimDataset.drop_sparql_store() Release that cached graph (it roughly doubles resident memory).
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.

query() materialises the dataset into an in-memory RDF graph the first time it is called and reuses it afterwards, so the first query costs far more than the rest — on a ~150k-element dataset, roughly 1.1 s then ~4 ms. The cache is dropped automatically whenever the dataset is mutated, and drop_sparql_store() releases it explicitly.

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, 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 (cimmodel, cimvalidation, cimsparql). 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

Metadata

Release files for cimoxide 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cimoxide 0.7.0
File Size Uploaded Provenance Actions
cimoxide-0.7.0.tar.gz 1.1 MB With provenance Details for cimoxide-0.7.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for cimoxide 0.7.0
File Interpreter ABI Platform Actions
cimoxide-0.7.0-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for cimoxide-0.7.0-cp39-abi3-win_amd64.whl
cimoxide-0.7.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.9 abi3 Linux glibc 2.17+ x86-64 Details for cimoxide-0.7.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
cimoxide-0.7.0-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for cimoxide-0.7.0-cp39-abi3-macosx_11_0_arm64.whl

Total release size: 15.1 MB

Release files / cimoxide-0.7.0.tar.gz

Download URL cimoxide-0.7.0.tar.gz
Size 1.1 MB
Tags Source
SHA-256 checksum
How to use checksums
09faa482f1b7abbc477aff5f491467c2017f5573382721e8c8fcc92f404b35b7
BLAKE2b-256 checksum
How to use checksums
02f2ab62fab2868993129582127d603c8bfa389b7a06d1b6f935d8fd8e7844cb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / cimoxide-0.7.0-cp39-abi3-win_amd64.whl

Download URL cimoxide-0.7.0-cp39-abi3-win_amd64.whl
Size 4.0 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
7ad51a93dbf722d630ae65dff8e27b820f5317b23231b16ff5066fe13b2a961d
BLAKE2b-256 checksum
How to use checksums
e184459ee1309fcb4fee4ddb9fc5299f075912b34246a1047a712d628335464f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / cimoxide-0.7.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL cimoxide-0.7.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 5.5 MB
Tags CPython 3.9 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
9420e4b015d41abd0afbb70cbfa8ef31d688ddd69e8c054248cad88a4e4cc26e
BLAKE2b-256 checksum
How to use checksums
2f8cd594fe5807149411b87894bd3ecac0b842e779bef55352725d4906a8d862
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / cimoxide-0.7.0-cp39-abi3-macosx_11_0_arm64.whl

Download URL cimoxide-0.7.0-cp39-abi3-macosx_11_0_arm64.whl
Size 4.5 MB
Tags CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
3ec8d4c2ac022008ca61d0b5ae44f447e368f10c8a0f62973348a0ec2851e185
BLAKE2b-256 checksum
How to use checksums
da57552b47e1e863692f847c4af82d91fcb57683a73fab8500818c8e5d2ad189
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for cimoxide 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 4 files in this release have been uploaded with provenance metadata.

Select from 4 files

Attestation for cimoxide-0.7.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page