Getting started

Wether you want to typeset numbers, units, quantities or figure labels, you’ll first need to import mplunitx and create an instance of the sisetup class.

from mplunitx import sisetup

si = sisetup()

Through the created instance you’ll have access to the functions:

print(si.num("9.81"))
print(si.unit("meter;per.second.squared"))
print(si.qty("9.81", "meter;per.second.squared"))
print(si.label("a", "meter;per.second.squared"))

$9.81$
$\mathrm{m}\,\mathrm{s}^{-2}$
$9.81\,\mathrm{m}\,\mathrm{s}^{-2}$
${a}\;/\;\mathrm{m}\,\mathrm{s}^{-2}$

• si.num("9.81") \(\rightarrow\) $9.81$ \(\rightarrow 9.81\)

• si.unit("meter;per.second.squared") \(\rightarrow\) $\mathrm{m}\,\mathrm{s}^{-2}$ \(\rightarrow \mathrm{m}\,\mathrm{s}^{-2}\)

• si.qty("9.81", "meter;per.second.squared") \(\rightarrow\) $9.81\,\mathrm{m}\,\mathrm{s}^{-2}$ \(\rightarrow 9.81\,\mathrm{m}\,\mathrm{s}^{-2}\)

• si.label("a", "meter;per.second.squared") \(\rightarrow\) ${a}\;/\;\mathrm{m}\,\mathrm{s}^{-2}$ \(\rightarrow {a}\;/\;\mathrm{m}\,\mathrm{s}^{-2}\)

Units

Units are passed to the methods in strings and in a similar format to the LaTeX package siunitx.

If a unit consists of multiple units, they need to be seperated by a semicolon.

print(si.unit("meter;second"))

$\mathrm{m}\,\mathrm{s}$

\(\mathrm{m}\,\mathrm{s}\)

Prefixes and other keywords can be added to a unit seperated by dots ".".

print(si.unit("kilo.meter;micro.second"))

$\mathrm{km}\,\mathrm{µs}$

\(\mathrm{km}\,\mathrm{µs}\)

The following keywords can be added in the same way:

• per: Inverse of the unit "meter;per.second" \(\rightarrow\) \(\mathrm{m}\,\mathrm{s}^{-1}\)

• square, squared: Multipy power of the unit by \(2\) "meter;per.second.squared" \(\rightarrow\) \(\mathrm{m}\,\mathrm{s}^{-2}\)

• cube, cubed: Multipy power of the unit by \(3\) "meter;per.second.cubed" \(\rightarrow\) \(\mathrm{m}\,\mathrm{s}^{-3}\)

• float, int: Multipy power of the unit by the given number (can be a negative number, but only one number per unit ";" is allowed) "meter;second.-2" \(\rightarrow\) \(\mathrm{m}\,\mathrm{s}^{-2}\)

The following input strings produce equivalent outputs:

print(si.unit("meter;per.square.second"))
print(si.unit("meter;per.second.squared"))
print(si.unit("meter;per.second.2"))
print(si.unit("meter;second.-2"))

$\mathrm{m}\,\mathrm{s}^{-2}$
$\mathrm{m}\,\mathrm{s}^{-2}$
$\mathrm{m}\,\mathrm{s}^{-2}$
$\mathrm{m}\,\mathrm{s}^{-2}$

For some units exist abbreviations, like

print(si.unit("m;s.-2"))

$\mathrm{m}\,\mathrm{s}^{-2}$

and also some abbreviations including a prefix:

print(si.unit("km;s.-2"))

$\mathrm{km}\,\mathrm{s}^{-2}$

\(\mathrm{km}\,\mathrm{s}^{-2}\)

A full list of available units and prefixes can be found in mplunitx.unit.declared_units and mplunitx.unit.si_prefixes.

Additionally you can define your own units, when creating the sisetup instance by passing a dictionary:

si = sisetup(declare_unit={"arbitraryunit": "arb.\,u."})
print(si.unit("arbitraryunit"))

$\mathrm{arb.\,u.}$

\(\mathrm{arb.\,u.}\)

The keys need to be strings, which are used as input in the unit method and the values need to be strings containing the LaTeX code. The LaTeX code you provide will be put into a math environment and enclosed in “{}”. Depending on the unit_font_command setting, there will also be a command before the “{}” (Default: \mathrm).

Options affecting the formatting and style of the units are explained in the Unit options tutorial.

Numbers

The current implementation of sisetup.num is just a dummy version returning the input string as is enclosed in "$" characters. Number formatting similar to the one in siunitx will get added in future releases.

Quantities

Quantities sisetup.qty are currently just numbers sisetup.num concatenated with units sisetup.unit and a quantity_product character inbetween.

Labels

Labels are similar to quantities, but instead of a number a variable is concatenated with a unit. The way they are combined is set by passing a label_unit_mode parameter to sisetup.