Convert a methane flux from moles to mass#

This example converts a methane flux of 10 nmol m-2 s-1 (nanomoles per square meter per second) to kg km-2 d-1 (kilograms per square kilometer per day), the unit lair’s inventories convert to when you ask them to standardize their units. Two rules come out of it:

  • Moles and mass need a molecular weight. A flux in moles and a flux in mass are different dimensions, so pint converts between them only inside the mass_flux context, given mw: the molecular weight, as a quantity in g/mol. Without the context the conversion raises DimensionalityError; inside it, a missing mw, or one that is a plain number, raises a TypeError that names mw and shows what to pass.

  • pint reads kt as a knot, a unit of speed. For a mass of a thousand tonnes, write Gg or kilotonne.

This page runs when the docs build.

The units#

lair.units is a pint unit registry (the one pint-xarray uses). A quantity is a number with a unit, and pint reads the unit from text. Units written the way CF files write them parse too, so m-2 s-1 works. In the output, ~P asks pint for the short symbols:

In [1]: from lair import units

In [2]: flux = 10 * units("nmol m-2 s-1")

In [3]: print(f"{flux:~P}")
10.0 nmol/m²/s

Moles to mass#

Ask for the flux in mass and pint refuses: it cannot get from moles to kilograms without knowing which molecule the moles are of.

In [4]: try:
   ...:     flux.to("kg km-2 d-1")
   ...: except Exception as err:
   ...:     print(f"{type(err).__name__}: {err}")
   ...: 
DimensionalityError: Cannot convert from 'nanomole / meter ** 2 / second' ([substance] / [length] ** 2 / [time]) to 'kilogram / kilometer ** 2 / day' ([mass] / [length] ** 2 / [time])

The mass_flux context supplies the missing piece. Importing lair adds it to the registry. Its mw is the molar mass of the gas, with its unit: 16.04 g/mol for methane.

In [5]: mw = 16.04 * units("g/mol")

In [6]: with units.context("mass_flux", mw=mw):
   ...:     flux_kg = flux.to("kg km-2 d-1")
   ...: 

In [7]: print(f"{flux_kg:~P.2f}")
13.86 kg/km²/d

The same context goes the other way, from mass to moles. This returns the 10 nmol m-2 s-1 it started from:

In [8]: with units.context("mass_flux", mw=mw):
   ...:     back = flux_kg.to("nmol m-2 s-1")
   ...: 

In [9]: print(f"{back:~P.2f}")
10.00 nmol/m²/s

To check the result by hand, convert one unit at a time. 10 nmol is 10e-9 mol, which weighs 10e-9 mol x 16.04 g/mol in grams, and 1000 g is 1 kg. Per square meter becomes per square kilometer by multiplying by 1e6, since a square kilometer is 1e6 square meters. Per second becomes per day by multiplying by 86,400, the seconds in a day (d is exactly 24 hours, whatever the local clock does; see the clock page for times):

In [10]: print(f"{10e-9 * 16.04 / 1000 * 1e6 * 86400:.2f}")
13.86

An array#

A grid of fluxes usually carries its unit as a units attribute, in CF form. .pint.quantify() reads it, .pint.to() converts, and .pint.dequantify() writes the new unit back into the attribute:

In [11]: import xarray as xr

In [12]: grid = xr.DataArray(
   ....:     [[10.0, 20.0], [30.0, 40.0]],
   ....:     dims=("y", "x"),
   ....:     attrs={"units": "nmol m-2 s-1"},
   ....: )
   ....: 

In [13]: with units.context("mass_flux", mw=mw):
   ....:     grid_kg = grid.pint.quantify().pint.to("kg km-2 d-1")
   ....: 

In [14]: grid_kg.pint.dequantify()
Out[14]: 
<xarray.DataArray (y: 2, x: 2)> Size: 32B
array([[13.85856, 27.71712],
       [41.57568, 55.43424]])
Dimensions without coordinates: y, x
Attributes:
    units:    kilogram / kilometer ** 2 / day

The same unit has more than one spelling, and pint reads them alike: kg km-2 d-1 and kilogram / kilometer ** 2 / day (what dequantify() writes) are one unit, and so are kg m-2 s-1 and kg/m**2/s (the units attribute of an inventory’s total_emissions).

lair.inventories.convert_units() does the same for any array or dataset with a units attribute, given the pollutant instead of mw: convert_units(grid, "CH4", "kg km-2 d-1") returns a plain array with the new values and units attribute. It needs the geo and science extras (see Optional dependencies). An Inventory has the same conversion for its data, with its own pollutant: convert_units().

The molecular weight#

For a gas other than methane, use its formula’s molar mass. molecular_weight() and the molar_mass of a Pollutant compute it with the molmass package, which the science extra installs (see Optional dependencies). This page runs without the extras, so it writes the number. For methane molmass gives 16.0425 g/mol, which moves the result from 13.8586 to 13.8607.

Kilotonnes#

pint’s kt is the knot, one nautical mile per hour. It parses without complaint, so the mistake shows only when you convert to a mass, with a message about lengths and times:

In [15]: print(f"{(1 * units('kt')).to('m/s'):~P.3f}")
0.514 m/s

In [16]: try:
   ....:     (22.6 * units("kt")).to("kg")
   ....: except Exception as err:
   ....:     print(f"{type(err).__name__}: {err}")
   ....: 
DimensionalityError: Cannot convert from 'knot' ([length] / [time]) to 'kilogram' ([mass])

A thousand tonnes is a gigagram, Gg, and pint also accepts kilotonne:

In [17]: print(f"{(22.6e6 * units('kg')).to('Gg'):~P.1f}")
22.6 Gg

In [18]: print(f"{(22.6 * units('kilotonne')).to('Gg'):~P.1f}")
22.6 Gg

Next#

Times and time zones are the other conversion that goes wrong without a rule. They are on the clock page, which also lists the errors convert_timezones raises.