<!-- Sema documentation — std.quantities
     Sema is a new AI-native, neurosymbolic programming language most models
     have not been trained on. Full corpus: https://sema.cortex.a2olabs.com/llms-full.txt
     Install language support: https://sema.cortex.a2olabs.com/install-skill/ -->

# std.quantities

> Reflected API reference for the Sema standard-library module std.quantities.

> Generated by `sema doc` from `crates/sema-runtime/assets/stdlib/sema/quantities.sema`. Import with `from std.quantities import …`. For a narrative introduction see [std.quantities](/stdlib/quantities/).

# `quantities`

std.quantities - bounded physical dimensions and SI-normalized quantities.

Dimensions use the seven SI base exponents. Quantities store canonical SI values;
conversion and arithmetic validate dimensions explicitly. Affine units such as
Celsius, symbolic units, uncertainty-bearing quantities, and automatic equation
inference are intentionally outside this bounded foundation.

# `struct Dimension`

**Fields**

| field | type | descriptor |
|---|---|---|
| `length` | `int` |  |
| `mass` | `int` |  |
| `time` | `int` |  |
| `current` | `int` |  |
| `temperature` | `int` |  |
| `amount` | `int` |  |
| `luminosity` | `int` |  |

# `struct Unit`

**Fields**

| field | type | descriptor |
|---|---|---|
| `symbol` | `str` |  |
| `dimension` | `Dimension` |  |
| `scale_to_si` | `f64` |  |

# `struct Quantity`

**Fields**

| field | type | descriptor |
|---|---|---|
| `si_value` | `f64` |  |
| `dimension` | `Dimension` |  |
| `display_unit` | `Unit` |  |

# `def dimensionless`

```sema
def dimensionless() -> Dimension !{}
```

**Returns** `Dimension`

**Effects** `!{}`

# `def length_dimension`

```sema
def length_dimension() -> Dimension !{}
```

**Returns** `Dimension`

**Effects** `!{}`

# `def mass_dimension`

```sema
def mass_dimension() -> Dimension !{}
```

**Returns** `Dimension`

**Effects** `!{}`

# `def time_dimension`

```sema
def time_dimension() -> Dimension !{}
```

**Returns** `Dimension`

**Effects** `!{}`

# `def current_dimension`

```sema
def current_dimension() -> Dimension !{}
```

**Returns** `Dimension`

**Effects** `!{}`

# `def temperature_dimension`

```sema
def temperature_dimension() -> Dimension !{}
```

**Returns** `Dimension`

**Effects** `!{}`

# `def amount_dimension`

```sema
def amount_dimension() -> Dimension !{}
```

**Returns** `Dimension`

**Effects** `!{}`

# `def luminosity_dimension`

```sema
def luminosity_dimension() -> Dimension !{}
```

**Returns** `Dimension`

**Effects** `!{}`

# `def same_dimension`

```sema
def same_dimension(left: Dimension, right: Dimension) -> bool !{}
```

**Parameters**

| name | type |
|---|---|
| `left` | `Dimension` |
| `right` | `Dimension` |

**Returns** `bool`

**Effects** `!{}`

# `def multiply_dimensions`

```sema
def multiply_dimensions(left: Dimension, right: Dimension) -> Dimension !{}
```

**Parameters**

| name | type |
|---|---|
| `left` | `Dimension` |
| `right` | `Dimension` |

**Returns** `Dimension`

**Effects** `!{}`

# `def divide_dimensions`

```sema
def divide_dimensions(left: Dimension, right: Dimension) -> Dimension !{}
```

**Parameters**

| name | type |
|---|---|
| `left` | `Dimension` |
| `right` | `Dimension` |

**Returns** `Dimension`

**Effects** `!{}`

# `def power_dimension`

```sema
def power_dimension(value: Dimension, exponent: int) -> Dimension !{}
```

**Parameters**

| name | type |
|---|---|
| `value` | `Dimension` |
| `exponent` | `int` |

**Returns** `Dimension`

**Effects** `!{}`

# `def unit`

```sema
def unit(symbol: str, scale_to_si: f64, dimension: Dimension) -> Unit !{}
```

**Parameters**

| name | type |
|---|---|
| `symbol` | `str` |
| `scale_to_si` | `f64` |
| `dimension` | `Dimension` |

**Returns** `Unit`

**Effects** `!{}`

# `def scalar_unit`

```sema
def scalar_unit() -> Unit !{}
```

**Returns** `Unit`

**Effects** `!{}`

# `def seconds`

```sema
def seconds() -> Unit !{}
```

**Returns** `Unit`

**Effects** `!{}`

# `def milliseconds`

```sema
def milliseconds() -> Unit !{}
```

**Returns** `Unit`

**Effects** `!{}`

# `def meters`

```sema
def meters() -> Unit !{}
```

**Returns** `Unit`

**Effects** `!{}`

# `def kilometers`

```sema
def kilometers() -> Unit !{}
```

**Returns** `Unit`

**Effects** `!{}`

# `def kilograms`

```sema
def kilograms() -> Unit !{}
```

**Returns** `Unit`

**Effects** `!{}`

# `def quantity`

```sema
def quantity(value: f64, source_unit: Unit) -> Quantity !{}
```

**Parameters**

| name | type |
|---|---|
| `value` | `f64` |
| `source_unit` | `Unit` |

**Returns** `Quantity`

**Effects** `!{}`

# `def convert`

```sema
def convert(value: Quantity, target_unit: Unit) -> Quantity !{}
```

**Parameters**

| name | type |
|---|---|
| `value` | `Quantity` |
| `target_unit` | `Unit` |

**Returns** `Quantity`

**Effects** `!{}`

# `def display_value`

```sema
def display_value(value: Quantity) -> f64 !{}
```

**Parameters**

| name | type |
|---|---|
| `value` | `Quantity` |

**Returns** `f64`

**Effects** `!{}`

# `def canonical_unit`

```sema
def canonical_unit(symbol: str, dimension: Dimension) -> Unit !{}
```

**Parameters**

| name | type |
|---|---|
| `symbol` | `str` |
| `dimension` | `Dimension` |

**Returns** `Unit`

**Effects** `!{}`

# `def scale`

```sema
def scale(value: Quantity, factor: f64) -> Quantity !{}
```

**Parameters**

| name | type |
|---|---|
| `value` | `Quantity` |
| `factor` | `f64` |

**Returns** `Quantity`

**Effects** `!{}`

# `def powi`

```sema
def powi(value: Quantity, exponent: int) -> Quantity !{}
```

**Parameters**

| name | type |
|---|---|
| `value` | `Quantity` |
| `exponent` | `int` |

**Returns** `Quantity`

**Effects** `!{}`

# `def derivative_dimension`

```sema
def derivative_dimension(state: Dimension, independent: Dimension) -> Dimension !{}
```

**Parameters**

| name | type |
|---|---|
| `state` | `Dimension` |
| `independent` | `Dimension` |

**Returns** `Dimension`

**Effects** `!{}`

# `def derivative_compatible`

```sema
def derivative_compatible(state: Dimension, independent: Dimension, derivative: Dimension) -> bool !{}
```

**Parameters**

| name | type |
|---|---|
| `state` | `Dimension` |
| `independent` | `Dimension` |
| `derivative` | `Dimension` |

**Returns** `bool`

**Effects** `!{}`