ccut 1.0.0

A package for identifying, parsing and transforming units of measure

Canonicalization Compound Unit Representation & Transformation (CCUT)

• Identifying individual units, their exponents and multipliers
• Representing units in a canonical format
• Mapping units to Ontology
• Finding the dimensions of each atomic unit
• Converting from one unit to another

This is the implementation accompanying the MWS 2019 paper, Parsing, Representing and Transforming Units of Measure.

How to run:

Here's how you can use this library. Import the module and then create an instance:

from ccut import ccut
cc = ccut()

CCU Representation:

get_top_ccu:

This method is used to get the top (single) CCU representation (dictionary) for a given string.
Run with a single argument (string of atomic/compound unit).
For example, running:

cc.get_top_ccu("kg/s^2")

Will return:

{
  'qudtp:abbreviation': 'kg s-2',
  'ccut:hasPart': [
    {
      'qudtp:symbol': 'kg',
      'qudtp:quantityKind': 'http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#Gram',
      'ccut:prefix': 'http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#Kilo',
      'ccut:prefixConversionMultiplier': 1000.0,
      'ccut:prefixConversionOffset': 0.0,
      'ccut:hasDimension': 'M',
      'qudtp:conversionMultiplier': 0.001,
      'qudtp:conversionOffset': 0.0
    },
    {
      'qudtp:symbol': 's',
      'qudtp:quantityKind': 'http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#SecondTime',
      'ccut:hasDimension': 'T',
      'qudtp:conversionMultiplier': 1.0,
      'qudtp:conversionOffset': 0.0,
      'ccut:exponent': '-2'
    }
  ],
  'ccut:hasDimension': 'M T-2'
}

get_all_ccu:

This method is used to get all the (multiple) CCU representations (ordered list of dictionaries) for a given string.
Run with a single argument (string of atomic/compound unit).
For example, running:

cc.get_all_ccu("oz")

Will return:

[
  {
    'ccut:hasPart': [
      {
        'qudtp:symbol': 'oz',
        'qudtp:quantityKind': 'http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#LiquidOunceUS',
        'ccut:hasDimension': 'L3',
        'qudtp:conversionMultiplier': 2.95735296e-05,
        'qudtp:conversionOffset': 0.0
      }
    ],
    'qudtp:abbreviation': 'oz',
    'ccut:hasDimension': 'L3'
  },
  {
    'ccut:hasPart': [
      {
        'qudtp:symbol': 'oz',
        'qudtp:quantityKind': 'http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#OunceImperial',
        'ccut:hasDimension': 'L3',
        'qudtp:conversionMultiplier': 2.84130625e-05,
        'qudtp:conversionOffset': 0.0
      }
    ],
    'qudtp:abbreviation': 'oz',
    'ccut:hasDimension': 'L3'
  },
  {
    'ccut:hasPart': [
      {
        'qudtp:symbol': 'oz',
        'qudtp:quantityKind': 'http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#OunceTroy',
        'ccut:hasDimension': 'M',
        'qudtp:conversionMultiplier': 0.0311034768,
        'qudtp:conversionOffset': 0.0
      }
    ],
    'qudtp:abbreviation': 'oz',
    'ccut:hasDimension': 'M'
  }
]

CCU Transformation (Conversion):

convert_ccu2ccu:

This method is used to perfrom compound unit conversion given the CCU representations.
Run with three arguments (ccu representation of the source unit, ccu representation of the destination unit, value to transform).
This method will return 3 values:

• the value after conversion
• the return status (see below)
• the return status in readable format (string) Where:

# Status key: 0: "OK"
#             1: "TRANSFORMATION_IS_NOT_SYMMETRIC"
#             2: "DIMENSION_MISMATCH"
#             3: "TRANSFORMATION_UNKNOWN"
#             4: "UNSUPPORTED_FLOW"

For example, running:

src_ccu = cc.get_top_ccu("m/s")
dst_ccu = cc.get_top_ccu("mi/hr")
cc.convert_ccu2ccu(src_ccu, dst_ccu, 2.7)

Will return:

(6.039727988546887, 0, 'OK')

convert_str2str:

This method is used to perfrom compound unit conversion given the strings of the source and destination units.
Run with three arguments (string of source unit, string of destination unit, value to transform).
This method will return 5 values:

• the value after conversion
• the return status
• the return status in readable format (string)
• CCU representaiton of the source string
• CCU representaiton of the destination string For example, running:

cc.convert_str2str("m/s", "mi/hr", 2.7)

Will return:

(6.039727988546887,
 0,
 'OK',
 {
   'qudtp:abbreviation': 'm s-1',
   'ccut:hasPart': [
     {
       'qudtp:symbol': 'm',
       'qudtp:quantityKind': 'http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#Meter',
       'ccut:hasDimension': 'L',
       'qudtp:conversionMultiplier': 1.0,
       'qudtp:conversionOffset': 0.0
     },
     {
       'qudtp:symbol': 's',
       'qudtp:quantityKind': 'http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#SecondTime',
       'ccut:hasDimension': 'T',
       'qudtp:conversionMultiplier': 1.0,
       'qudtp:conversionOffset': 0.0,
       'ccut:exponent': '-1'
     }
   ],
   'ccut:hasDimension': 'L T-1'
 },
 {
   'qudtp:abbreviation': 'mi hr-1',
   'ccut:hasPart': [
     {
       'qudtp:symbol': 'mi',
       'qudtp:quantityKind': 'http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#MileInternational',
       'ccut:hasDimension': 'L',
       'qudtp:conversionMultiplier': 1609.344,
       'qudtp:conversionOffset': 0.0
     },
     {
       'qudtp:symbol': 'hr',
       'qudtp:quantityKind': 'http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#Hour',
       'ccut:hasDimension': 'T',
       'qudtp:conversionMultiplier': 3600.0,
       'qudtp:conversionOffset': 0.0,
       'ccut:exponent': '-1'
     }
   ],
   'ccut:hasDimension': 'L T-1'
 }
)

Citing CCUT

If you would like to cite the this tool in a paper or presentation, the following is recommended (BibTeX entry):

@article{shbita2019parsing,
  title={Parsing, Representing and Transforming Units of Measure},
  author={Shbita, Basel and Rajendran, Arunkumar and Pujara, Jay and Knoblock, Craig A}
  journal={Modeling the World’s Systems},
  year={2019},
}