Measurement:Units: Difference between revisions

Latest revision as of 11:11, 19 August 2026

Part of: Measurement:Main_Page
Related to: Measurement:Canonical_Units

AOWIS uses a canonical representation for measurement quantities. Each measurement quantity has one canonical unit defined in Canonical Units.

Canonical units are selected individually based on SI, established engineering practice, numerical practicality, and interoperability. Values MAY use other units at system boundaries and in user interfaces, but the authoritative AOWIS representation remains canonical.

Purpose

This specification defines the AOWIS unit system for measurement quantities, including canonical representation, unit identifiers, boundary conversion, and the resolution of context-dependent units.

A single canonical representation:

provides an unambiguous data contract between AOWIS components;
prevents backend- or locale-specific units from leaking into the domain model;
simplifies validation, comparison, computation, serialization, and testing;
allows user interfaces and external systems to use alternative units without changing the authoritative representation.

The canonical measurement quantities and units themselves are defined in Measurement:Canonical_Units.

Terminology

AOWIS domain model: The authoritative representation of concepts, entities, relationships, and state managed by AOWIS.

Measurement quantity: A defined physical or engineering quantity being represented, such as volumetric flow rate, pressure head, power, or efficiency.

Canonical unit: The single unit assigned by AOWIS to a measurement quantity for authoritative representation.

Canonical value: The authoritative numerical representation of a measurement value expressed in the canonical unit defined for its measurement quantity.

Source value: A numerical value and unit received from a user, device, file, backend, component, or external system before conversion into the canonical AOWIS representation.

Unit identifier: The machine-readable identifier of a unit. AOWIS uses UCUM for physical unit identifiers.

Fixed-schema measurement field: A field whose measurement quantity and canonical unit are defined by the schema.

Context-dependent measurement value: A value whose measurement quantity depends on another field, enum, object type, equation, or operating mode.

Requirements

General

REQ-MEAS-001: All authoritative numerical values representing measurement quantities within the AOWIS domain model MUST be represented using the canonical unit defined for the measurement quantity.

REQ-MEAS-002: Each fixed or resolved measurement quantity MUST be assigned exactly one canonical unit.

REQ-MEAS-003: Measurement quantities with different meanings MUST remain distinct even when they use the same canonical unit.

REQ-MEAS-004: Physical unit identifiers MUST conform to UCUM.

REQ-MEAS-005: The measurement quantity identifier defines what is measured, while the unit identifier defines the unit in which it is expressed.

REQ-MEAS-006: Dimensionless physical measurement quantities MUST use the UCUM unit identifier "1". A fixed-schema field with canonical unit "1" MAY omit a unit suffix when its field name unambiguously identifies the quantity.

REQ-MEAS-007: Numeric values that are not measurement quantities MUST NOT be assigned measurement units solely because they are numeric.

REQ-MEAS-008: A value whose measurement quantity depends on another field, enum, object type, equation, or operating mode MUST be represented using quantity-specific fields or a discriminated structure that identifies the resolved quantity.

REQ-MEAS-009: An equation coefficient whose dimensions depend on configurable equation parameters MUST retain the parameters required to determine its dimensional meaning and MUST NOT be represented using a misleading fixed unit.

REQ-MEAS-010: Values entering the AOWIS domain model in non-canonical units MUST be converted to their defined canonical units at the applicable system boundary. Values leaving AOWIS MAY be converted to the representation required by the receiving system or interface.

REQ-MEAS-011: Conversion artifacts, rounding errors, and precision loss introduced by an implementation MUST NOT exceed the documented precision of the measurement.

REQ-MEAS-012: A retained non-canonical source representation MUST be clearly distinguished from the authoritative canonical value.

REQ-MEAS-013: Monetary values that depend on a currency MUST identify that currency using its ISO 4217 alphabetic code or by reference to a configured currency carrying that code.

User Interface Specific

REQ-MEAS-UI-001: User interfaces MUST clearly indicate the unit associated with every displayed or entered numerical value representing a measurement quantity.

REQ-MEAS-UI-002: User interfaces MAY display measurement values in supported non-canonical units.

REQ-MEAS-UI-003: User interfaces accepting values in non-canonical units MUST convert the entered value to its canonical unit before it enters the AOWIS domain model.

REQ-MEAS-UI-004: Rounding performed for presentation MUST NOT modify the underlying canonical value.

Interpretation of the Requirements

This section is informative. The normative requirements above remain authoritative.

A canonical unit belongs to a measurement quantity, not merely to a numeric data type. Two quantities can therefore use the same unit while remaining semantically different. For example, elevation, hydraulic head, pressure head, and water level are all expressed in metres but represent different quantities.

Dimensionless physical quantities remain measurement quantities. Examples include demand multipliers, pump speed ratios, hydraulic coefficients, and exponents. Their canonical UCUM unit is 1. Fixed-schema fields normally express their meaning through the field name and do not need an artificial unit suffix such as _1.

Conversely, a number is not automatically a measurement. Counts, indices, priorities, identifiers, decimal precision settings, and similar values do not require measurement units.

Some values cannot be assigned a unit until their context is known. A valve setting, for example, may represent pressure head, volumetric flow rate, valve position, a loss coefficient, or another quantity depending on the valve type. Such values must therefore be represented so that their actual measurement quantity is unambiguous.

The same principle applies to control values, rule values, water-quality values, report thresholds, generic curve coordinates, and similar context-dependent data.

Equation coefficients require additional care when their dimensional meaning depends on configurable equation parameters. For example, in an emitter relation

Q = C H^n

the dimensional meaning of C depends on the exponent n. The coefficient and the parameters required to interpret it must therefore remain associated.

Alternative backend, import, export, user-selected, and display units do not change the canonical AOWIS representation. Conversion occurs at the boundary where the alternative representation enters or leaves AOWIS.

Examples

Value	Interpretation
`volumetric_flow_rate = 12.5 m3/h`	Measurement quantity with canonical unit `m3/h`
`demand_multiplier = 1.2`	Dimensionless measurement quantity with canonical UCUM unit `1`
`rule_priority = 5`	Numeric value that is not a measurement quantity
FCV setting `20 m3/h`	Setting resolved to volumetric flow rate
PRV setting `30 m`	Setting resolved to pressure head

Boundary Conversion

The AOWIS domain model uses canonical units independently of the unit systems used by backends, files, external systems, devices, or user interfaces.

An adapter or interface is responsible for converting values whenever its representation differs from the canonical AOWIS representation.

For example, an EPANET project MAY use any EPANET-supported flow or pressure unit system. The EPANET adapter converts those values to and from the canonical quantities defined in Measurement:Canonical_Units.

A backend configuration option that selects a backend unit system does not alter the canonical AOWIS data contract.

Fixed and Dynamic Schema Values

For a fixed-schema field, the measurement quantity and canonical unit MAY be defined entirely by the schema.

For example:

flow_m3_per_h
pressure_head_m
power_kw

do not require a separate unit property when their schema definition unambiguously establishes the measurement quantity and unit.

Generic or dynamically typed measurement values MUST identify or resolve to their measurement quantity. Where the unit is represented explicitly, the canonical UCUM identifier defined in Measurement:Canonical_Units MUST be used.

Data Model

Concrete AOWIS data structures and field definitions are specified by the AOWIS Server Model.

Measurement fields defined by the Model MUST follow this specification and the canonical quantity registry in Measurement:Canonical_Units.

References

Unified Code for Units of Measure (UCUM)^[1]
International Bureau of Weights and Measures (BIPM), International System of Units (SI)^[2]
ISO 4217 currency codes^[3]

[UCUM-1] ttps://ucum.org

[BIPM-2] ttps://www.bipm.org/en/measurement-units

[ISO4217-3] ttps://www.iso.org/iso-4217-currency-codes.html

[1]

[2]

[3]

@@ Line 1: / Line 1: @@
 * Part of: [[Measurement:Main_Page]]
-* Related to: [[Measurement:Unit_Identifiers]]
+* Related to: [[Measurement:Canonical_Units]]
-AOWIS systems, components, and data models MUST use the International System of Units (SI) as the canonical unit system.<ref name="BIPM-SI">International Bureau of Weights and Measures (BIPM) — International System of Units (SI) https://www.bipm.org/en/measurement-units/si-base-units</ref><ref name="NIST-SI">NIST — The International System of Units (SI) https://www.nist.gov/pml/owm/metric-si/si-units</ref>
+AOWIS uses a canonical representation for measurement quantities. Each measurement quantity has one canonical unit defined in [[Measurement:Canonical_Units|Canonical Units]].
-SI is the globally accepted standard for scientific and technical measurement and is defined and maintained by the International Bureau of Weights and Measures (BIPM).<ref name="Wikipedia-SI">Wikipedia — International System of Units https://en.wikipedia.org/wiki/International_System_of_Units</ref>
+Canonical units are selected individually based on SI, established engineering practice, numerical practicality, and interoperability. Values MAY use other units at system boundaries and in user interfaces, but the authoritative AOWIS representation remains canonical.
 == Purpose ==
-This specification establishes a single authoritative unit system for all physical quantities represented by AOWIS.
+This specification defines the AOWIS unit system for measurement quantities, including canonical representation, unit identifiers, boundary conversion, and the resolution of context-dependent units.
+A single canonical representation:
+* provides an unambiguous data contract between AOWIS components;
+* prevents backend- or locale-specific units from leaking into the domain model;
+* simplifies validation, comparison, computation, serialization, and testing;
+* allows user interfaces and external systems to use alternative units without changing the authoritative representation.
+The canonical measurement quantities and units themselves are defined in [[Measurement:Canonical_Units]].
+== Terminology ==
+; AOWIS domain model
+: The authoritative representation of concepts, entities, relationships, and state managed by AOWIS.
+; Measurement quantity
+: A defined physical or engineering quantity being represented, such as volumetric flow rate, pressure head, power, or efficiency.
+; Canonical unit
+: The single unit assigned by AOWIS to a measurement quantity for authoritative representation.
+; Canonical value
+: The authoritative numerical representation of a measurement value expressed in the canonical unit defined for its measurement quantity.
+; Source value
+: A numerical value and unit received from a user, device, file, backend, component, or external system before conversion into the canonical AOWIS representation.
-The use of a single unit system reduces implementation complexity, eliminates ambiguity during data exchange, simplifies validation and testing, and improves interoperability between independent AOWIS implementations.
+; Unit identifier
+: The machine-readable identifier of a unit. AOWIS uses UCUM for physical unit identifiers.
-User Interfaces can show numerical values in non-SI units for convenience, but this is only allowed ''additionally'' to the official SI-unit, and the UI needs to transfer this to the user.
+; Fixed-schema measurement field
+: A field whose measurement quantity and canonical unit are defined by the schema.
+; Context-dependent measurement value
+: A value whose measurement quantity depends on another field, enum, object type, equation, or operating mode.
 == Requirements ==
 === General ===
 <pre>
-REQ-MEAS-001: All authoritative numerical values representing physical quantities within the AOWIS domain model MUST be represented using their defined canonical SI units.
+REQ-MEAS-001: All authoritative numerical values representing measurement quantities within the AOWIS domain model MUST be represented using the canonical unit defined for the measurement quantity.
-REQ-MEAS-002: Implementations MUST produce results that are numerically consistent with SI-based processing.
+REQ-MEAS-002: Each fixed or resolved measurement quantity MUST be assigned exactly one canonical unit.
-REQ-MEAS-003: Implementations MUST NOT introduce conversion artifacts, rounding errors, or precision loss exceeding the documented precision of the measurement.
+REQ-MEAS-003: Measurement quantities with different meanings MUST remain distinct even when they use the same canonical unit.
-REQ-MEAS-004: Interfaces between an AOWIS-compliant component and a component or system using non-canonical unit representations MUST perform the required conversion at the component or system boundary. Values entering the AOWIS measurement model MUST be converted to their canonical AOWIS units. Values leaving AOWIS MAY be converted to the representation required by the receiving component or system.
+REQ-MEAS-004: Physical unit identifiers MUST conform to UCUM.
-REQ-MEAS-005: Each distinct measurement quantity in AOWIS MUST be mapped to exactly one canonical unit. Measurement quantities with different meanings MUST have separate identifiers, even when they use the same canonical unit.
+REQ-MEAS-005: The measurement quantity identifier defines what is measured, while the unit identifier defines the unit in which it is expressed.
+REQ-MEAS-006: Dimensionless physical measurement quantities MUST use the UCUM unit identifier "1". A fixed-schema field with canonical unit "1" MAY omit a unit suffix when its field name unambiguously identifies the quantity.
+REQ-MEAS-007: Numeric values that are not measurement quantities MUST NOT be assigned measurement units solely because they are numeric.
+REQ-MEAS-008: A value whose measurement quantity depends on another field, enum, object type, equation, or operating mode MUST be represented using quantity-specific fields or a discriminated structure that identifies the resolved quantity.
+REQ-MEAS-009: An equation coefficient whose dimensions depend on configurable equation parameters MUST retain the parameters required to determine its dimensional meaning and MUST NOT be represented using a misleading fixed unit.
+REQ-MEAS-010: Values entering the AOWIS domain model in non-canonical units MUST be converted to their defined canonical units at the applicable system boundary. Values leaving AOWIS MAY be converted to the representation required by the receiving system or interface.
+REQ-MEAS-011: Conversion artifacts, rounding errors, and precision loss introduced by an implementation MUST NOT exceed the documented precision of the measurement.
+REQ-MEAS-012: A retained non-canonical source representation MUST be clearly distinguished from the authoritative canonical value.
+REQ-MEAS-013: Monetary values that depend on a currency MUST identify that currency using its ISO 4217 alphabetic code or by reference to a configured currency carrying that code.
 </pre>
 === User Interface Specific ===
 <pre>
-REQ-MEAS-UI-000: User interfaces MUST clearly indicate the unit associated with every displayed or entered numerical value representing a physical quantity.
+REQ-MEAS-UI-001: User interfaces MUST clearly indicate the unit associated with every displayed or entered numerical value representing a measurement quantity.
-REQ-MEAS-UI-001: User interfaces MAY display measurement values in supported non-SI units for convenience, provided that the displayed unit is clearly indicated.
+REQ-MEAS-UI-002: User interfaces MAY display measurement values in supported non-canonical units.
-REQ-MEAS-UI-002: User interfaces accepting non-SI input MUST convert the entered value to the canonical SI unit before it enters the AOWIS domain model.
+REQ-MEAS-UI-003: User interfaces accepting values in non-canonical units MUST convert the entered value to its canonical unit before it enters the AOWIS domain model.
-REQ-MEAS-UI-003: Original non-SI input values and their unit identifiers MAY be stored as provenance data but MUST NOT be used as the authoritative values for computation, comparison, validation, or control logic.
+REQ-MEAS-UI-004: Rounding performed for presentation MUST NOT modify the underlying canonical value.
+</pre>
+== Interpretation of the Requirements ==
+''This section is informative. The normative requirements above remain authoritative.''
-REQ-MEAS-UI-004: Rounding performed for presentation MUST NOT modify the underlying canonical value.
+A canonical unit belongs to a '''measurement quantity''', not merely to a numeric data type. Two quantities can therefore use the same unit while remaining semantically different. For example, elevation, hydraulic head, pressure head, and water level are all expressed in metres but represent different quantities.
+Dimensionless physical quantities remain measurement quantities. Examples include demand multipliers, pump speed ratios, hydraulic coefficients, and exponents. Their canonical UCUM unit is <code>1</code>. Fixed-schema fields normally express their meaning through the field name and do not need an artificial unit suffix such as <code>_1</code>.
+Conversely, a number is not automatically a measurement. Counts, indices, priorities, identifiers, decimal precision settings, and similar values do not require measurement units.
+Some values cannot be assigned a unit until their context is known. A valve setting, for example, may represent pressure head, volumetric flow rate, valve position, a loss coefficient, or another quantity depending on the valve type. Such values must therefore be represented so that their actual measurement quantity is unambiguous.
+The same principle applies to control values, rule values, water-quality values, report thresholds, generic curve coordinates, and similar context-dependent data.
+Equation coefficients require additional care when their dimensional meaning depends on configurable equation parameters. For example, in an emitter relation
+<pre>
+Q = C H^n
+</pre>
+the dimensional meaning of <code>C</code> depends on the exponent <code>n</code>. The coefficient and the parameters required to interpret it must therefore remain associated.
+Alternative backend, import, export, user-selected, and display units do not change the canonical AOWIS representation. Conversion occurs at the boundary where the alternative representation enters or leaves AOWIS.
+=== Examples ===
+{| class="wikitable"
+! Value !! Interpretation
+|-
+| <code>volumetric_flow_rate = 12.5 m3/h</code> || Measurement quantity with canonical unit <code>m3/h</code>
+|-
+| <code>demand_multiplier = 1.2</code> || Dimensionless measurement quantity with canonical UCUM unit <code>1</code>
+|-
+| <code>rule_priority = 5</code> || Numeric value that is not a measurement quantity
+|-
+| FCV setting <code>20 m3/h</code> || Setting resolved to volumetric flow rate
+|-
+| PRV setting <code>30 m</code> || Setting resolved to pressure head
+|}
+== Boundary Conversion ==
+The AOWIS domain model uses canonical units independently of the unit systems used by backends, files, external systems, devices, or user interfaces.
+An adapter or interface is responsible for converting values whenever its representation differs from the canonical AOWIS representation.
+For example, an EPANET project MAY use any EPANET-supported flow or pressure unit system. The EPANET adapter converts those values to and from the canonical quantities defined in [[Measurement:Canonical_Units]].
+A backend configuration option that selects a backend unit system does not alter the canonical AOWIS data contract.
+== Fixed and Dynamic Schema Values ==
+For a fixed-schema field, the measurement quantity and canonical unit MAY be defined entirely by the schema.
+For example:
+<pre>
+flow_m3_per_h
+pressure_head_m
+power_kw
 </pre>
-== Notes ==
+do not require a separate unit property when their schema definition unambiguously establishes the measurement quantity and unit.
+Generic or dynamically typed measurement values MUST identify or resolve to their measurement quantity. Where the unit is represented explicitly, the canonical UCUM identifier defined in [[Measurement:Canonical_Units]] MUST be used.
+== Data Model ==
+Concrete AOWIS data structures and field definitions are specified by the [https://github.com/aowis-org/AOWIS-SERVER-MODEL AOWIS Server Model].
-External systems MAY use alternative unit systems. Any required conversion between such systems and AOWIS is performed at the system boundary in accordance with REQ-MEAS-004.
+Measurement fields defined by the Model MUST follow this specification and the canonical quantity registry in [[Measurement:Canonical_Units]].
 == References ==
 <references />
+* Unified Code for Units of Measure (UCUM)<ref name="UCUM">https://ucum.org</ref>
+* International Bureau of Weights and Measures (BIPM), International System of Units (SI)<ref name="BIPM">https://www.bipm.org/en/measurement-units</ref>
+* ISO 4217 currency codes<ref name="ISO4217">https://www.iso.org/iso-4217-currency-codes.html</ref>

Samuel (talk | contribs)