# Unit definitions

New units of measurement can be introduced with the `unit`

keyword. There are two types of units: base units and derived units.

A new **base unit** can be defined by specifying the *physical dimension* it represents. For example, in the
International System of Units (SI), the *second* is the base unit for measuring times:

```
unit second: Time
```

Here, `Time`

denotes the physical dimension. To learn more, you can read the corresponding chapter. But for now, we can just assume that they are already given.

**Derived units** are also introduced with the `unit`

keyword. But unlike base units, they are defined through their relation to
other units. For example, a *minute* can be defined as

```
unit minute: Time = 60 second
```

Here, the `: Time`

annotation is optional. If a dimension is specified, it will be used to verify that the right hand side expression (`60 second`

) is indeed of physical dimension `Time`

. This is apparent in this simple example, but can be useful for more complicated unit definitions like

```
unit farad: Capacitance = ampere^2 second^4 / (kilogram meter^2)
```

## Prefixes

If a unit may be used with metric prefixes such as `milli`

/`m`

, `kilo`

/`k`

or `mega`

/`M`

, we can prepend the unit definition with the `@metric_prefixes`

decorator:

```
@metric_prefixes
unit second: Time
```

This allows identifiers such as `millisecond`

to be used in calculations. See the section below how prefixes interact with aliases.

Similarly, if a unit should be prependable with *binary* (IEC) prefixes such as `kibi`

/`Ki`

, `mebi`

/`Mi`

or `gibi`

/`Gi`

, you can
add the `@binary_prefixes`

decorator. A unit might also allow for both metric and binary prefixes, for example:

```
@binary_prefixes
@metric_prefixes
unit byte = 8 bit
```

This allows the usage of both `mebibyte`

(1024² byte) as well as `megabyte`

(1000² byte).

## Aliases

It is often useful to define alternative names for a unit. For example, we might want to use the plural form `seconds`

or the commonly
used short version `s`

. We can use the `@aliases`

decorator to specify them:

```
@metric_prefixes
@aliases(meters, metre, metres, m: short)
unit meter: Length
```

In addition to the name, we can also specify how aliases interact with prefixes using `: long`

(the default), `: short`

, `: both`

or
`: none`

. The actual unit name (`meter`

) and all `long`

aliases will accept the long version of prefixes (…, `milli`

, `kilo`

, `mega`

, `giga`

, …).
All `short`

aliases (`m`

in the example above) will only accept the respective short versions of the prefixes (…, `m`

, `k`

, `M`

, `G`

, …).
Aliases annotated with `: both`

or `: none`

accept either both long *and* short prefixes, or none of them.
The unit definition above allows all of following expressions:

```
millimeter
kilometer
millimeters
kilometers
millimetre
kilometre
millimetres
kilometres
mm
km
...
```