Datatypes and Units of Measure

VladimirAlexiev commented 2 months ago

CGMES datatype properties are defined like this:

cim:ACDCConverter.baseS a owl:FunctionalProperty , owl:DatatypeProperty ;
  rdfs:domain cim:ACDCConverter ;
  rdfs:range  cim:ApparentPower.

cim:ApparentPower a owl:Class ;
  rdfs:label "ApparentPower"@en ;
  eq:Package "Package_CoreEquipmentProfile" ;
  eq:isCIMDatatype "True" ;
  skos:definition "\nProduct of the RMS value of the voltage and the RMS value of the current.\n\n\t"@en .

cim:ApparentPower.multiplier
  a owl:FunctionalProperty , owl:DatatypeProperty ;
  rdf:value "M" ;
  rdfs:domain cim:ApparentPower ;
  rdfs:label "multiplier"@en ;
  rdfs:range cim:UnitMultiplier ;
  eq:isFixed "True " .

cim:ApparentPower.unit
  a owl:FunctionalProperty , owl:DatatypeProperty ;
  rdf:value "VA" ;
  rdfs:domain cim:ApparentPower ;
  rdfs:label "unit"@en ;
  rdfs:range cim:UnitSymbol ;
  eq:isFixed "True " .

cim:ApparentPower.value
 a owl:FunctionalProperty , owl:DatatypeProperty ;
 rdfs:domain cim:ApparentPower ;
 rdfs:label "value"@en ;
 rdfs:range xsd:float .

There are numerous problems:

cim:ApparentPower is a class, and datatype properties cannot point to a class
cim:ApparentPower is not used in any CGMES instance data
In CGMES instance data, ACDCConverter.baseS is a string, but should be marked as ^^xsd:float
The meta-properties eq:isCIMDatatype, eq:isFixed use profile dataspaces rather than cims
The key value "True " is spelled with a space for multiplier, unit

CIM defines a large set of units of measure, eg:

cim:UnitSymbol a owl:Class ;
  rdfs:label "UnitSymbol"@en ;
  eq:Package "Package_CoreEquipmentProfile" ;
  owl:oneOf (... cim:UnitSymbol.VA ...).
cim:UnitSymbol.VA a owl:NamedIndividual, owl:Thing ;
  rdfs:label "VA "@en ;
  eq:isenum "True" ;
  rdfs:domain cim:UnitSymbol ;
  skos:definition "Apparent power in volt amperes. See also real power and reactive power."@en .

cim:UnitMultiplier a owl:Class ;
  rdfs:label "UnitMultiplier"@en ;
  owl:oneOf (... cim:UnitMultiplier.M ...).
cim:UnitMultiplier.M a owl:NamedIndividual, owl:Thing ;
  rdfs:label "M "@en ;
  eq:isenum "True" ;
  rdfs:domain cim:UnitMultiplier ;
  skos:definition "Mega 10**6."@en .

But they are not used: eg cim:ApparentPower.unit says it has rdfs:range cim:UnitSymbol, but uses a string value "VA". Same for cim:ApparentPower.multiplier
cim:UnitSymbol.VA uses a different label rdfs:label "VA "@en, which has two mistakes:
- Trailing space
- lang tag @en (in fact it's a SI symbol that has no language)
cim:UnitSymbol.VA wrongly says a owl:Thing; rdfs:domain cim:UnitSymbol.
- Instead it should say a cim:UnitSymbol.
Similar problems apply to cim:UnitMultiplier.M, and:
- It doesn't express the multiplier as a number 1e6 but only as a string "Mega 10**6"

See sec ## Datatypes and Units of Measure for more analysis and a fixing plan . But I only plan to fix datatype props: so we need to discuss whether to:

remove unit/multiplier/value props,
remove cim:UnitSymbol nodes that are not used

VladimirAlexiev commented 2 months ago

Fixed Units Representation

We want to fix the representation as follows, and also connect to QUDT (see https://github.com/qudt/qudt-public-repo/issues/969) . To be clear, this below is just a blueprint, which parts of it will be implemented and where is still for discussion.

First we correct the property: give a numeric range, but also specify hasQuantityKind and hasUnit using qudt props. We link to a global QUDT unit, but also give the multiplier and unitSymbol separately, using cims props:

@prefix qudt: <http://qudt.org/schema/qudt/> .
@prefix unit: <http://qudt.org/vocab/unit/> .

cim:ACDCConverter.baseS a owl:FunctionalProperty , owl:DatatypeProperty ;
  rdfs:domain cim:ACDCConverter ;
  rdfs:range  xsd:float ;
  qudt:hasQuantityKind cim:ApparentPower;
  qudt:hasUnit    unit:MegaV-A;
  cims:multiplier cim:UnitMultiplier.M;
  cims:unitSymbol cim:UnitSymbol.VA.

Then we correct the QuantityKind and relate it to QUDT.

In QUDT, unit:MegaV-A applies to quantitykind:ComplexPower, but is this "nearly the same" as ApparentPower?
If you google "ApparentPower vs ComplexPower", you can find electrical textbooks that define them as follows:
- ComplexPower is the vector sum of real power and reactive power.
- ApparentPower is the magnitude of complex power.
But units don't apply to vectors, they apply to magnitudes
QUDT defines ComplexPower as "under sinusoidal conditions, is the product of the phasor U representing the voltage between the terminals of a linear two-terminal element or two-terminal circuit and the complex conjugate of the phasor I representing the electric current in the element or circuit"
Which to me (not being an electrical engineer), is "close enough' to the CIM definition of ApparentPower (see below)
```
@prefix qudt: <http://qudt.org/schema/qudt/> .
@prefix quantitykind: <http://qudt.org/vocab/quantitykind/> .
```

cim:ApparentPower a qudt:QuantityKind ; rdfs:label "ApparentPower"@en ; eq:Package "Package_CoreEquipmentProfile" ; eq:isCIMDatatype "True" ; qudt:applicableUnit cim:cim:UnitSymbol.VA; skos:broader quantitykind:ComplexPower; skos:definition "\nProduct of the RMS value of the voltage and the RMS value of the current.\n\n\t"@en .


We delete `cim:ApparentPower.multiplier, cim:ApparentPower.unit` 
because they are replaced by universal props `cims:multiplier, cims:unitSymbol` respectively.

We delete `cim:ApparentPower.value` because the actual DatatypeProperty `cim:ACDCConverter.baseS`
now carries a number (`xsd:float`).

We correct CIM unit symbols and relate them to QUDT:
```ttl
cim:UnitSymbol a owl:Class ;
  rdfs:label "UnitSymbol"@en ;
  owl:oneOf (... cim:UnitSymbol.VA ...);
  skos:exactMatch qudt:Unit.

cim:UnitSymbol.VA a cim:UnitSymbol ;
  rdfs:label "VA" ;
  cims:isenum "True" ;
  skos:definition "Apparent power in volt amperes. See also real power and reactive power."@en;
  qudt:hasQuantityKind cim:ApparentPower;
  skos:exactMatch unit:V-A.

We correct CIM multipliers and relate them to QUDT (where they are called "prefixes"):

@prefix prefix: <http://qudt.org/vocab/prefix/> .

cim:UnitMultiplier a owl:Class ;
  rdfs:label "UnitMultiplier"@en ;
  owl:oneOf (... cim:UnitMultiplier.M ...);
  skos:exactMatch qudt:DecimalPrefix.

cim:UnitMultiplier.M a cim:UnitMultiplier;
  rdfs:label "M" ;
  cims:isenum "True" ;
  skos:definition "Mega 10**6."@en ;
  skos:exactMatch prefix:Mega.

VladimirAlexiev commented 2 months ago

I checked https://github.com/Sveino/Inst4CIM-KG/issues/29, and this issue is more comprehensive (so tagged that one as duplicate)
@Sveino can you check that https://github.com/3lbits/CIM4NoUtility/issues/338 doesn't have anything more than this one?

griddigit-ci commented 2 months ago

Yes, the direction would be to be more explicit with QUDT. we need to see if we need cim: properties in RDFS - maybe not as this will be result of transformation from UML to the RDFS

VladimirAlexiev commented 2 months ago

@griddigit-ci

we need to see if we need cim: properties in RDFS

This statement is rich since QUDT has all sort of info about MegaV-A:

cim:ACDCConverter.baseS qudt:hasUnit    unit:MegaV-A

including info what is its base unit, and what is its multiplier.

But @Sveino also suggested we keep props multiplier and unitSymbol for an easier transition

cim:ACDCConverter.baseS 
  cims:multiplier cim:UnitMultiplier.M;
  cims:unitSymbol cim:UnitSymbol.VA.

(I eliminated the parasitic intermediate props cim:ApparentPower.multiplier, cim:ApparentPower.unit and converted from strings to things.)

It looks like we have an agreement now to exchange in basic units i.e. no M but in form 1e6

We should keep an object to represent "Mega", not just the multiplication factor.

When we link multipliers to QUDT:

cim:UnitMultiplier.M a cim:UnitMultiplier;
  skos:exactMatch prefix:Mega.

people can get rich info:

prefix:Mega
  a qudt:DecimalPrefix ;
  a qudt:Prefix ;
  dcterms:description "'mega' is a decimal prefix for expressing a value with a scaling of \\(10^{6}\\)."^^qudt:LatexString ;
  qudt:dbpediaMatch "http://dbpedia.org/resource/Mega"^^xsd:anyURI ;
  qudt:informativeReference "http://en.wikipedia.org/wiki/Mega?oldid=494040441"^^xsd:anyURI ;
  qudt:prefixMultiplier 1.0E6 ;
  qudt:siExactMatch si-prefix:mega ;
  qudt:symbol "M" ;
  qudt:ucumCode "M" ;
  rdfs:isDefinedBy <http://qudt.org/2.1/vocab/prefix> ;
  rdfs:label "Mega"@en ;
.

Of course, we can copy selected info from QUDT, eg prefixMultiplier 1.0E6. There is a lot richer info about units and quantity kinds. But I was content to just link to QUDT.

VladimirAlexiev commented 2 months ago

This was a big one, the fix queries are: fix05-units-76,77.ru fix06-quantityKind-38.ru fix07-dataProps-38.ru fix08-remove-qkProps-38.ru fix09-map-qkUnitsMultipliers-38.ru

Sveino / Inst4CIM-KG

Datatypes and Units of Measure #38

Fixed Units Representation