gimli.units 0.3.0

An object-oriented Python interface to udunits

gimli.units

An object-oriented Python interface to udunits2 built with cython.

Requirements

gimli.units requires Python 3 and udunits2.

Apart from Python, gimli has a number of other requirements, the main one being udunits2. udunits2 is the unit conversion C library that gimli wraps using cython. The easiest way to install udunits2 is through Anaconda (see the Install section), or yum (as udunits2-devel on ubuntu-based Linux). It can, however, also be compiled and installed from source. You can get the source code either as a .tar.gz or from GitHub.

All other requirements are available using either pip or conda. To see a full listing of the requirements, have a look at the project’s requirements.txt file.

If you are a developer of gimli you will also want to install additional dependencies for running gimli’s tests to make sure that things are working as they should. These dependencies are listed in requirements-testing.txt.

Installation

To install gimli, first create a new environment in which gimli will be installed. This, although not necessary, will isolate the installation so that there won’t be conflicts with your base Python installation. This can be done with conda as:

$ conda create -n gimli python=3
$ conda activate gimli

Stable Release

gimli, and its dependencies, can be installed either with pip or conda. Using pip:

$ pip install gimli.units

Using conda:

$ conda install gimli.units -c conda-forge

From Source

After downloading the gimli source code, run the following from gimli’s top-level folder (the one that contains setup.py) to install gimli into the current environment:

$ pip install -e .

Usage

Primarily, gimli.units is a Python library with an API that reflects that of the udunits2 library. gimli, however, also comes with a command-line interface.

API

You primarily will access gimli through gimli.units,

>>> from gimli import units

units is an instance of the default UnitSystem class, which contains all of the units contained in a given unit system. If you like, you can create your own unit system but, typically, the default should be fine.

To get a specific unit from the system, do so by passing a unit string to the Units class. For example,

>>> units.Unit("m")
Unit('meter')
>>> units.Unit("m/s")
Unit('meter-second^-1')
>>> units.Unit("kg m-3")
Unit('meter^-3-kilogram')
>>> units.Unit("N m")
Unit('joule')

Every Unit instance has a to method, which returns a unit converter for converting values from one unit to another,

>>> lbs = units.Unit("lb")
>>> kgs = units.Unit("kg")
>>> kgs_to_lbs = kgs.to(lbs)
>>> kgs_to_lbs(1.0)
2.2046226218487757

You can also construct units that are a combination of other units.

>>> ft_per_s = units.Unit("ft / s")
>>> m_per_s = units.Unit("m s-1")
>>> ft_per_s.to(m_per_s)([1.0, 2.0])
array([0.3048, 0.6096])

Command-line interface

From the command line you can use gimli to convert values from one unit to another.

$ gimli --from=miles --to=ft --data=1.0
5280.000000

Values to convert are passed through the –data option as a comma-separated list of numbers. You can also provide values through files and use a dash for stdin.

$ echo "1.0" | gimli --from=cal --to=joule -
4.186800

When reading from a file, gimli tries to preserve the format of the input file,

$ cat values.csv
1.0, 2.0, 3.0
4.0, 5.0, 6.0
$ gimli --from=knot --to=m/s values.txt
0.514444, 1.028889, 1.543333
2.057778, 2.572222, 3.086667

Credits

Development Lead

• Eric Hutton (@mcflugen)

Contributors

None yet. Why not be the first?

Changelog for gimli

0.3.0 (2021-11-16)

• Added support for a wider range of array dtypes (#13)

• Fixed AttributeError when deallocating UnitSystem after exiting Python (#12)

• Fixed –version option for the gimli command (#11)

0.2.1 (2021-03-02)

• Fixed a bug caused by passing a single value to the cli (#10)

• Added content to the README, mainly installation and usage instructions (#9)

0.2.0b1 (2021-02-22)

• Added release and prerelease actions to publish on PyPI and TestPyPI (#8)

• Change name of package to gimli.units (#7)

0.2.0b0 (2021-02-20)

• Added gimli command-line interface (#6)

• Better handling of multi-dimensional and non-contiguous arrays (#5)

• Fixed a issue that caused a segmentation fault when using dimensionless units (#4)

0.1.1 (2021-02-17)

• Created the gimli package (#1)

• Set continuous integration using GitHub actions (#2)

• Deploy to TestPyPI on a version tag (#3)