> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poelis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Units Management - User manual

Units Management defines how **numeric properties** are interpreted, validated, and converted in Poelis. By organizing values into **categories** and **units**, Poelis ensures that numbers are not just stored, but understood correctly, making comparisons, conversions, and dependencies reliable across products and versions.
Units are managed at the **workspace level** and are shared by all products in that workspace.
Units management in Poelis is built around three ideas:

* **Categories** describe *what kind of quantity* a value represents
  (for example: temperature, mass, pressure, voltage).

* **Units** describe *how that quantity is measured*
  (for example: °C, kg, bar, V).

* **Base units** define the canonical reference for each category, enabling conversion.

Every numeric property belongs to exactly one category and uses one unit from that category.

## Categories

A **category** represents a physical or logical dimension.
Poelis includes a wide set of **standard categories** out of the box:

* The **seven SI base quantities**, from which all other physical quantities are derived. In Poelis, they form the foundation of many other categories.

| Quantity | Description |
| - | - |
| mass | Amount of matter |
| length | Spatial dimension |
| time | Duration |
| current | Electric current |
| temperature | Thermodynamic temperature |
| luminous intensity | Light emitted in a given direction |
| amount of substance | Quantity of elementary entities |

* Few **derived from one or more SI base quantities**. They typically involve combinations of base units (multiplication, division, powers).

| Quantity | Typical dimension |
| - | - |
| force | mass × length / time² |
| energy | force × length |
| power | energy / time |
| pressure | force / area |
| electric charge | current × time |
| electric capacitance | charge / potential |
| electric potential | energy / charge |
| electric resistance | potential / current |
| electric inductance | potential × time / current |
| electric conductance | 1 / resistance |
| magnetic flux | potential × time |
| magnetic flux density | flux / area |
| frequency | 1 / time |
| angle | ratio of lengths (dimensionless in SI, but often treated explicitly) |

* Few **unitless** or represent abstract, non-physical quantities. They do not reduce to SI base units.

| Quantity | Notes |
| - | - |
| unitless | Pure ratios or normalized values |
| bit | Information quantity |
| angle | Often treated as dimensionless, but kept explicit for clarity |

### Custom categories

You can create **custom categories** when your domain requires quantities that are not covered by standard dimensions.
Custom categories behave exactly like standard ones:

* they can have a base unit

* they can contain multiple units

* they can be used by numeric properties

Categories should represent *dimensions*, not units or formulas.

## Units

A **unit** defines how values in a category are expressed. Each category has:

* one **base unit**

* zero or more **derived units**

The base unit is the canonical reference used internally for conversions. For example, in the *mass* category:

* `kg` is the base unit

* `g`, `ton`, `ounce`, `stone`, etc. are derived units

### Base units

The **base unit** anchors all conversions in a category. Every other unit in the category is defined *relative to the base unit*. Changing the base unit would change how all other units are interpreted, which is why base units are fixed once defined.
You do not usually need to think about base units explicitly, but they are what make conversions safe and consistent.

### Custom units

You can add **custom units** to any category. When creating a custom unit, you define:

* the unit name (symbol)

Custom units are useful when:

* working with domain-specific conventions

* importing data from external systems

* matching supplier or legacy documentation

Once created, custom units behave exactly like standard units and can be used in properties, conversions, and dependencies.
When writing unit formulas:

* Use **standard unit symbols** (`m`, `s`, `kg`, `A`)

* Use `^` for exponents, not superscripts

* Avoid spaces inside expressions

* Be explicit, clarity is better than brevity

Correct:

```text theme={null}
m/s
kg*m/s^2
```

Avoid:

```text theme={null}
m s-1
kg ms-2
```

Units must be written using multiplication, division, and powers.
Examples:

* `m/s`

* `m^2`

* `kg*m/s^2`

* `N*m`

* `J/s`

Use:

* `*` for multiplication

* `/` for division

* `^` for powers

* etc…

Parentheses must be used to clarify precedence:

* `(m*s)/kg`

* `m/(s^2)`

### Unit compatibility

Units are only compatible **within the same category**.
For example:

* temperature units can convert among °C, K, °F

* mass units can convert among kg, g, ton

* temperature and mass can never be mixed

This prevents invalid comparisons and ensures numeric dependencies remain meaningful.

## Using units in properties

When you assign a unit to a numeric property:

* the value is stored with full dimensional meaning

* conversions become available automatically

* dependencies can validate comparisons correctly

## Unit conversion

Numeric properties support **on-the-fly unit conversion**.
Conversions:

* respect category compatibility

* preserve value meaning

* do not modify stored values unless explicitly changed

Conversions are provided to aid interpretation, comparison, and review—not to silently mutate data.

## Best practices

When managing units:

* choose clear, standard base units

* avoid redefining common units unnecessarily

* use custom categories sparingly and intentionally

* prefer explicit compound units over ambiguous names

* keep unit formulas simple and readable

A clean unit system makes properties easier to understand, compare, validate, and automate across the entire product lifecycle.