- PyCGMES
Python dataclasses for CGMES 3 + RDF schema description + SHACL (validation) files.
The Common Grid Model Exchange Specification, or CGMES, is provided by ENTSO-E (the European Network of TSOs for Electricity) to facilitate the exchange of grid data between parties. It is based on CIM, the Common Information Model for electric utilities, provided by the IEC (see also CIM on Wikipedia).
CIM defines the vocabulary for electricity grids, meaning the names we use for different components and the way they relate to each other. CGMES takes a subset of this vocabulary and provides RDF schema and SHACL validation files.
Further reading and all relevant CGMES (source) files are found on the CGMES page of the ENTSO-E website.
From Pypi.org, 2 packages are available (both from this repository):
They can easily be installed via pip: pip install pycgmes or pip install pycgmes-shacl.
You might want to add extra attributes. For instance, the color of a cable (ACLineSegment). This is possible in 2 ways:
- Adding the attribute to a custom class in an existing profile.
- Define a new profile including a custom class where the attribute is defined.
You can look at the examples
If you need to add your own attributes (example: cable colour), you can do that by subclassing the relevant class, and add one or more new atributes there.
If this is a leaf node (for instance ACLineSegment), it "just works". If you want to add an extra attribute to a
class higher in the hierarchy (for instance Equipment) there is a lot more work to do.
@dataclass
class CustomBay(Bay):
colour: str = Field(
default="Red",
in_profiles=[
Profile.EQ,
],
)This approach is cleaner and more standard compliant: the official CGMES profiles stay untouched, while a new additional profile contains your customisations.
You can do this by extending the `BaseProfile`` Enum in profile.py.
While in Python it is not possible to extend or compose Enums which already have fields, you can create your own:
from pycgmes.utils.profile import BaseProfile
class CustomProfile(BaseProfile):
CUS="Tom"
FRO="Mage"And use it everywhere you would use a profile:
@dataclass
class CustomBayAttr(Bay):
colour: str = Field(
default="Red",
json_schema_extra={
"in_profiles": [
CustomProfile.CUS,
],
}
)
# And for instance:
custom_attrs = CustomBayAttr(colour="purple").cgmes_attributes_in_profile(CustomProfile.CUS)By default, an attribute is fully qualified. A standard attribute in ACLineSegment will appear as ACLineSegment.attribute in the serialisation.
In the case of a custom attribute defined via a sub class, the result would be: ACLineSegmentCustom.customAttribute. To preserve the original class name (i.e. serialise your attribute as ACLineSegment.customAttribute), you need to override the apparent_name of your custom class:
from pydantic.dataclasses import dataclass
from pycgmes.resources.ACLineSegment import ACLineSegment
@dataclass
class ACLineSegmentCustom(ACLineSegment):
@classmethod
def apparent_name(cls):
return "ACLineSegment"The default class (or resource) namespace is http://iec.ch/TC57/CIM100#.
You can override it when you create a custom resource by just redefining the property namespace:
In the serialisation, the namespace of all attributes is http://iec.ch/TC57/CIM100# by default.
The namespace of an attribute is the first value found:
- namespace defined in the Field (see
colourbelow - it would becustom) - namespace of the class (see
sizebelow - it would becustom ns class) - namespace of the first parent defining one. The top parent (
Base) definedcim.
from pydantic.dataclasses import dataclass
from pydantic import Field
from pycgmes.resources import ACLineSegment
@dataclass
class ACLineSegmentCustom(ACLineSegment):
colour: str = Field(
default="Red",
json_schema_extra={
"in_profiles": [
Profile.EQ, # Do not do this, see chapter "create a new profile"
],
"namespace": "custom",
},
)
size: str = Field(
default="Big",
json_schema_extra={
"in_profiles": [
Profile.EQ, # Do not do this, see chapter "create a new profile"
],
}
)
@property
def namespace(self) -> str:
return "custom ns class"
@classmethod
def apparent_name(cls):
return "ACLineSegment"It will be given when cgmes_attributes_in_profile() is called.
schemas are rdf definitions of CGMES. They are used once, to generate dataclasses, and can then happily be forgotten.
They are available on the ENTSO-E site. Look for CGMES Conformity Assessment Scheme v3 then Application Profiles v3.0.1
Older versions could be found on the ENTSO-E site.
Shapes Constraint Language is used for validation of the actual content of the CGMES files, not just XML validation. They can be found in shacl. This is the new validation standard. OCL is referenced, specially with older versions, but ENTSO-E is moving away from it.
To use them, there is another package pycmges-shacl, built from this repo as well.
From ENTSO-E, in data. This is one small-ish zip file, containing a bit more than just the SHACL and RDFS files (those extracted and mentioned above) but is usually not needed.
Generated from the modernpython serialisation of cimgen.
The CI happens in GitHub actions.
The standard black/pyright/ruff are run there, via scons.
Deployment happens to pypi.org, via the standard poetry commands poetry build, poetry publish.
This project is licensed under the Apache 2.0 license - see LICENSE for details.
Please read CODE_OF_CONDUCT.md, CONTRIBUTING.md, and PROJECT GOVERNANCE.md for details on the process for submitting pull requests to us.
Please read SUPPORT.mdfor how to connect and get into contact with the project.
This project represents an advanced evolution of two prior initiatives: CIMgen and CIMpy. For further details and insights into the foundational work that inspired this project, interested parties are encouraged to visit their respective repositories on GitHub. CIMgen can be accessed at CIMgen GitHub Repository, and CIMpy at CIMpy GitHub Repository.