Units
-----

### Objective

This module defines how physical units are attached to dimensionful H5MD
elements.


### Module name and version

The name of this module is `units`. The module version is 1.0.0.

### Unit system definition

The `units` group possesses, in addition to the `version` attribute, a `system`
attribute that defines the unit system in use. `system` is of scalar dataspace
and fixed-length string datatype.

### Unit attribute

The datasets of any H5MD element that have a physical dimension may carry an
attribute `unit` to indicate the physical unit of the respective data. In
general, this refers to the dataset itself for time-independent elements, or to
the datasets `value` and `time` in the time-dependent case:

    <element>
     \-- step: Integer[variable]
     \-- time: Float[variable]
     |    +-- (unit: String[])
     \-- value: <type>[variable][...]
          +-- (unit: String[])

The attribute `unit` is of scalar dataspace and fixed-length `String`
datatype using the ASCII character set.

### Unit string

The `unit` string consists of a sequence of unit factors separated by a space.
A unit factor is either a number (an integer or a decimal fraction) or a unit
symbol optionally followed by a non-zero, signed integer indicating the power
to which this factor is raised. Each unit symbol may occur only once. There may
also be at most one numeric factor, which must be the first one.

Examples:

  - "nm+3" stands for cubic nanometers

  - "um+2 s-1" stands for micrometers squared per second

  - "60 s" stands for a minute

  - "10+3 m" stands for a kilometer

### The "SI" unit system

The "SI" unit system [@SI] defines SI base units (§2.1), SI derived units
(§2.2), and SI prefixes (§3.1).

+---------------------+--------+-----------+
| dimension           | symbol | unit name |
+=====================+========+===========+
| length              | m      | meter     |
+---------------------+--------+-----------+
| mass                | kg     | kilogram  |
+---------------------+--------+-----------+
| time                | s      | second    |
+---------------------+--------+-----------+
| electric current    | A      | ampere    |
+---------------------+--------+-----------+
| temperature         | K      | kelvin    |
+---------------------+--------+-----------+
| amount of substance | mol    | mole      |
+---------------------+--------+-----------+
| luminous intensity  | cd     | candela   |
+---------------------+--------+-----------+

Table: SI base unit symbols and names.

+-----------------------+--------+----------------+-------------------+
| dimension             | symbol | unit name      | conversion        |
+=======================+========+==========================+=========+
| plane angle           | rad    | radian         | 1 rad = 1 m m⁻¹   |
+-----------------------+--------+----------------+-------------------+
| solid angle           | sr     | steradian      | 1 sr = 1 m² m⁻²   |
+-----------------------+--------+----------------+-------------------+
| frequency             | Hz     | hertz          | 1 Hz = 1 s⁻¹      |
+-----------------------+--------+----------------+-------------------+
| force                 | N      | newton         | 1 N = 1 m kg s⁻²  |
+-----------------------+--------+----------------+-------------------+
| pressure/stress       | Pa     | pascal         | 1 Pa = 1 N m⁻²    |
+-----------------------+--------+----------------+-------------------+
| energy/work           | J      | joule          | 1 J = 1 N m       |
+-----------------------+--------+----------------+-------------------+
| power                 | W      | watt           | 1 W = 1 J s⁻¹     |
+-----------------------+--------+----------------+-------------------+
| electric charge       | C      | coulomb        | 1 C = 1 A s       |
+-----------------------+--------+----------------+-------------------+
| voltage               | V      | volt           | 1 V = W A⁻¹       |
+-----------------------+--------+----------------+-------------------+
| capacitance           | F      | farad          | 1 F = C V⁻¹       |
+-----------------------+--------+----------------+-------------------+
| electric resistance   | ohm    | ohm            | 1 Ω = V A⁻¹       |
+-----------------------+--------+----------------+-------------------+
| electric conductance  | S      | siemens        | 1 S = 1 A V⁻¹     |
+-----------------------+--------+----------------+-------------------+
| magnetic flux         | Wb     | weber          | 1 Wb = 1 V s      |
+-----------------------+--------+----------------+-------------------+
| magnetic flux density | T      | tesla          | 1 T = 1 Wb m⁻²    |
+-----------------------+--------+----------------+-------------------+
| inductance            | H      | henry          | 1 H = 1 Wb A⁻¹    |
+-----------------------+--------+----------------+-------------------+
| Celsius temperature   | degC   | degree Celsius | 0 °C = 273.15 K   |
+-----------------------+--------+----------------+-------------------+
| luminous flux         | lm     | lumen          | 1 lm = 1 cd sr    |
+-----------------------+--------+----------------+-------------------+
| illuminance           | lx     | lux            | 1 lx = 1 lm m⁻²   |
+-----------------------+--------+----------------+-------------------+
| radioactivity         | Bq     | becquerel      | 1 Bq = 1 s⁻¹      |
+-----------------------+--------+----------------+-------------------+
| absorbed dose         | Gy     | gray           | 1 Gy = 1 J kg⁻¹   |
+-----------------------+--------+----------------+-------------------+
| dose equivalent       | Sv     | sievert        | 1 Sv = 1 J kg⁻¹   |
+-----------------------+--------+----------------+-------------------+
| catalytic activity    | kat    | katal          | 1 kat = 1 mol s⁻¹ |
+-----------------------+--------+----------------+-------------------+

Table: SI derived unit symbols, names and conversion rules.

+--------+--------+--------+
| prefix | symbol | factor |
+========+========+========+
| exa-   | E      | 10¹⁸   |
+--------+--------+--------+
| peta-  | P      | 10¹⁵   |
+--------+--------+--------+
| tera-  | T      | 10¹²   |
+--------+--------+--------+
| giga-  | G      | 10⁹    |
+--------+--------+--------+
| mega-  | M      | 10⁶    |
+--------+--------+--------+
| kilo-  | k      | 10³    |
+--------+--------+--------+
| hecto- | h      | 10²    |
+--------+--------+--------+
| deca-  | da     | 10¹    |
+--------+--------+--------+
| deci-  | d      | 10⁻¹   |
+--------+--------+--------+
| centi- | c      | 10⁻²   |
+--------+--------+--------+
| milli- | m      | 10⁻³   |
+--------+--------+--------+
| micro- | u      | 10⁻⁶   |
+--------+--------+--------+
| nano-  | n      | 10⁻⁹   |
+--------+--------+--------+
| pico-  | p      | 10⁻¹²  |
+--------+--------+--------+
| femto- | f      | 10⁻¹⁵  |
+--------+--------+--------+
| atto-  | a      | 10⁻¹⁸  |
+--------+--------+--------+

Table: SI prefixes.

### References