Measurement:Units

• 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 how measurement quantities, values, units, conversions, and measurement-related numeric data are represented and handled by AOWIS.

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: Original source values and unit identifiers MAY be retained as provenance data. Retained source values MUST be clearly distinguished from authoritative canonical values and MUST NOT be used as authoritative values for computation, comparison, validation, or control logic.

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

Context-Dependent Measurement Values

The following concepts cannot be assigned one fixed canonical unit until their applicable context has been resolved.

Model Concept	Context-Dependent Meaning	Required Representation
Valve setting	PRV, PSV, and PBV: pressure head; FCV: volumetric flow rate; TCV: minor-loss coefficient; PCV: valve position; GPV: curve reference	Use quantity-specific fields or a discriminated valve-setting structure
Pump setting	Pump speed relative to nominal speed	Resolve as pump_speed_ratio
Control action setting	Quantity supported by the controlled link type	Use the same quantity-specific setting representation as the target link
Control trigger	Water level, pressure head, elapsed time, or time of day depending on control type	Use quantity-specific trigger representations
Rule premise value	Quantity selected by the rule variable	Store or resolve the rule variable together with its quantity-specific value
Rule action setting	Quantity supported by the target link	Use the target link's quantity-specific setting representation
Initial and simulated quality	Chemical concentration, water age, or source-trace percentage depending on analysis mode	Resolve through the active quality-analysis mode
Water-quality solver tolerance	Quantity depends on quality-analysis mode	Resolve through the active quality-analysis mode
Quality-source strength	Chemical concentration or chemical mass flow rate depending on source type	Use a source-type-specific representation
Reaction coefficient	Dimensions depend on reaction order	Use fixed quantities only for defined fixed-order cases; otherwise retain the reaction order with the coefficient
Emitter coefficient	In Q = C H^n, the dimensional meaning of C depends on n	Store coefficient and exponent together
Generic curve coordinates	Quantities depend on curve type	Prefer typed curve structures; genuinely generic curves require explicit quantity metadata
Report thresholds	Quantity depends on the corresponding report field	Associate each threshold with the report field's measurement quantity
EPANET map and backdrop coordinates	Coordinate interpretation depends on the associated map configuration	Resolve to an explicitly identified geographic, projected, or local coordinate representation

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)
• International Bureau of Weights and Measures (BIPM), International System of Units (SI)
• ISO 4217 currency codes