Package: ucumvert
Easier access to UCUM from PythonFeedback welcome!Currently only the conversion direction from UCM to pint is supported.
Please review the definitions before you trust them.
While we have many tests in place and reviewed the mappings carefully, bugs may still be present.UCUM(Unified Code for Units of Measure) is a code system intended to cover all units of measures.
It provides a formalism to express units in an unambiguous way suitable for electronic communication.
Note that UCUM does non provide a canonical representation, e.g.m/sandm.s-1are expressing the same unit in two ways.ucumvertis a pip-installable Python package. Features:Parser for UCUM unit strings that implements the full grammar.Converter for creatingpintunits from UCUM unit strings.A pint unit definition filepint_ucum_defs.txtthat extends pint´s default units with UCUM units. All UCUM units from Version 2.1 of the specification are included.ucumvertgenerates the UCUM grammar by filling a template with unit codes, prefixes etc. from the officialucum-essence.xmlfile (a copy is included in this repo).
So updating the parser for new UCUM releases is straight forward.
The parser is built with the greatlarkparser toolkit.
The generated lark grammar file for case-sensitive UCUM codes is included in the repository, seeucum_grammar.lark.Some of the UCUM unit atoms are invalid unit names in pint, for examplecal_[15],m[H2O],10*,[in_i'H2O].
For all of them we define mappings to valid pint unit names inucum_pint.py, e.g.{"cal_[15]": "cal_15"}.Installucumvert is available as Python package fromPyPiand can be pip-installed in the usual way.pipinstallucumvertTo install the most recent code from git in developer mode including creation of a virtual environment use:Linuxgitclonehttps://github.com/dalito/ucumvert.gitcducumvert
python-mvenv.venvsource.venv/bin/activate
python-mpipinstall--upgradepip
pipinstall-e.[dev]Windowsgitclonehttps://github.com/dalito/ucumvert.gitcducumvert
py-mvenv.venv
.venv\Scripts\activate.bat
py-mpipinstall--upgradepip
pipinstall-e.[dev]Optionally you can visualize the parse trees withGraphvizas shown below. It requires the additional packagepydot; install by runningpip install pydot.DemoWe provide a basic command line interface.(.venv) $ ucumvertIt has an interactive mode to test parsing UCUM codes:(.venv) $ ucumvert -i
Enter UCUM unit code to parse, or 'q' to quit.
> m/s2.kg
Created visualization of parse tree (parse_tree.png).
main_term
  term
    term
      simple_unit       m
      /
      annotatable
        simple_unit     s
        2
    .
    simple_unit
      k
      g
--> Pint <Quantity(1.0, 'kilogram * meter / second ** 2')>
> qSo the intermediate result is a tree which is then traversed to convert the elements to pint quantities (or pint-compatible strings):The package includes an UCUM-aware pint UnitRegistry which loads all definitions for UCUM units on instantiation.
It comes with an additional methodfrom_ucumto convert UCUM codes to pint.>>>fromucumvertimportPintUcumRegistry>>>ureg=PintUcumRegistry()>>>ureg.from_ucum("m/s2.kg")<Quantity(1.0,'kilogram * meter / second ** 2')>>>>ureg.from_ucum("m[H2O]{35Cel}")# UCUM code with annotation<Quantity(1,'m_H2O')>>>>_.to("mbar")<Quantity(98.0665,'millibar')>>>>ureg("degC")# a standard pint unit<Quantity(1,'degree_Celsius')>>>>TestsThe unit tests include parsing and converting all common UCUM unit codes from the official repo. Run the test suite by:pytestThe common UCUM unit codes are available only in binary form (xlsx, docs, pdf).
Here we keep a copy in tsv-formatucum_examples.tsv.
To (re)generate this tsv-file from the official xlsx-file in theUCUM repositoryrunpipinstallopenpyxl
pythonsrc/src/ucumvert/vendor/get_ucum_example_as_tsv.pyUseful linksUCUMonline-validatorIssue in pint that motivated this work:To what extent is pint compatible with UCUM?LicenseThe code in this repository is distributed under MIT license with the exception of theucum-*.*files in the directorysrc/ucumvert/vendorthat fall under theUCUM Copyright Notice and License(Version 1.0).
We considerucumvertaccording to §1.3 not as "Derivative Works" of UCUM becauseucumvertonly"interoperates with an unmodified instance of the Work".