gimli.units 0.4.0

An object-oriented Python interface to udunits

gimli.units

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

NOTE: gimli.units includes a vendored version of udunits2 so that you do not have to install the udunits2 library separately.

Installation

pip install gimli.units

or

conda install gimli.units -c conda-forge

From Source

pip install git+https://github.com/mcflugen/gimli.git

Note: gimli.units requires the libudunits library. You will need to have this installed before building gimli.units. You can do this using conda,

conda install udunits2 -c conda-forge

or by building udunits2 from source (we use a vendored version of udunits2, which can be found in the extern folder of this repository).

Usage

Quick conversions

Use gimli.convert to convert scalars or arrays between unit strings:

>>> from gimli import convert_units

>>> convert_units(10.0, "N", "lb.ft/s2")
72.33013851209893
>>> convert_units([0.0, 250.0, 1000.0], "N", "lb*ft/s^2")
array([   0.        , 1808.2534628 , 7233.01385121])

Reuse converters

If you will apply the same conversion many times, build a converter once:

>>> from gimli import UnitConverter

>>> m_to_ft = UnitConverter("m", "ft")
>>> m_to_ft([0.0, 1.0, 2.0])
array([0.        , 3.2808399 , 6.56167979])
>>> m_to_ft(3.0)
9.842519685039369

Unit Systems

You primarily will access gimli through gimli.units,

>>> from gimli.units 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.

units is a dict-like object whose keys are strings representing units and values are instances of those units. For example,

>>> units["m"]
Unit('meter')
>>> units["m/s"]
Unit('meter-second^-1')
>>> units["kg m-3"]
Unit('meter^-3-kilogram')
>>> units["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["lb"]
>>> kgs = units["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["ft / s"]
>>> m_per_s = units["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

5280.000000

Values to convert can be passed through the files (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

Notice of Vendored Libraries

gimli.units includes two third-party libraries, expat and udunits, which are "vendored" as part of our codebase. This means that these libraries are embedded directly within gimli.units, rather than being external dependencies.

Reasons for Vendoring

• udunits: A library for units of physical quantities, vendored to provide robust unit conversion and management, ensuring compatibility and consistency in unit operations.
• expat: An XML parser library written in C, vendored to ensure consistent and reliable XML parsing across various platforms and environments without requiring separate installation of the library. expat is a dependency of udunits.

Implications for Users

• No Additional Installations: Users do not need to install these libraries separately; they are fully integrated into our package.
• Package Size: The inclusion of these libraries increases the size of our package. We have taken care to ensure that this does not significantly impact the installation and usage experience.
• Compatibility: Vendoring these libraries helps us manage compatibility and reliability issues, as we use specific versions tested to work with our package.

Licensing

• udunits License: License Information for udunits
• Our use of these vendored libraries complies with their respective licenses. Users of our package are also subject to these terms.
• expat License: License Information for expat

Updates and Security

• We actively monitor and incorporate updates, including security patches, for these vendored libraries. Should there be any significant updates or security concerns, we aim to address these in a timely manner.

Further Information

• For more information on udunits, refer to udunits' website.
• For more details about expat, please visit expat's website.