Measurement:Canonical Units: Difference between revisions
mNo edit summary |
mNo edit summary |
||
| Line 47: | Line 47: | ||
REQ-MEAS-UNI-010: Currencies MUST NOT be represented as UCUM units in AOWIS. Monetary values MUST identify or reference a currency using its ISO 4217 currency identifier. | REQ-MEAS-UNI-010: Currencies MUST NOT be represented as UCUM units in AOWIS. Monetary values MUST identify or reference a currency using its ISO 4217 currency identifier. | ||
</pre> | </pre> | ||
== Interpretation of the Requirements == | |||
''This section is informative. The normative requirements above remain authoritative.'' | |||
The requirements distinguish physical measurement quantities from other numeric values and from monetary values. Physical measurement quantities use canonical UCUM units, including UCUM <code>1</code> for dimensionless physical quantities. Numeric values such as counts, priorities, indices, or precision settings are not measurement quantities merely because they are numeric and therefore do not require UCUM units. | |||
A measurement value whose physical quantity depends on another field, object type, operating mode, or equation must first be resolved to a specific measurement quantity. Once resolved, that quantity uses the canonical UCUM unit defined by AOWIS. This applies, for example, to valve settings, control and rule values, water-quality values, report thresholds, and similar context-dependent fields. | |||
Backend, import, export, user-selected, and display units do not change the canonical AOWIS representation. Conversion to and from non-canonical units occurs at system boundaries. | |||
Equation coefficients whose dimensions depend on configurable parameters, such as an arbitrary emitter exponent, must retain the parameters required to interpret their dimensional meaning and must not be assigned a misleading fixed unit. | |||
Monetary values are outside the UCUM measurement-unit system. Their currency is identified or referenced using ISO 4217, while any physical denominator such as kilowatt-hour or kilowatt remains governed by this measurement standard. | |||
=== Examples === | |||
{| class="wikitable" | |||
! Example !! Interpretation | |||
|- | |||
| <code>volumetric_flow_rate = 12.5 m3/h</code> || Physical measurement; canonical UCUM unit <code>m3/h</code> | |||
|- | |||
| <code>demand_multiplier = 1.2</code> || Dimensionless physical measurement; canonical UCUM unit <code>1</code> | |||
|- | |||
| <code>rule_priority = 5</code> || Numeric value, not a physical measurement; no UCUM unit | |||
|- | |||
| <code>energy_price = 0.25 EUR/kWh</code> || <code>EUR</code> is ISO 4217 currency information; <code>kW.h</code> is the physical unit in the denominator | |||
|- | |||
| FCV setting = <code>20 m3/h</code>; PRV setting = <code>30 m</code> || Both are settings, but they resolve to different measurement quantities and therefore different canonical units | |||
|} | |||
== Canonical Measurement Quantities and Units == | == Canonical Measurement Quantities and Units == | ||
Revision as of 15:05, 18 August 2026
- Part of: Measurement:Main_Page
- Related to: Measurement:Units
AOWIS uses the canonical SI-based engineering units specified in Units. UCUM[1] is the normative syntax and code system for machine-readable physical unit identifiers.
AOWIS defines a canonical set of UCUM unit identifiers used across all system interfaces, storage formats, APIs, and inter-system data exchanges.
Unit identifiers are machine-readable tokens and are not intended to represent typographic or human-readable unit notation.
Currencies are not represented as UCUM units in AOWIS. Monetary values use currencies identified by ISO 4217[2] and follow the monetary-value rules defined on this page.
General Rules
- All physical unit identifiers MUST conform to UCUM.
- Each fixed or resolved physical measurement quantity MUST be assigned exactly one UCUM unit identifier as its canonical unit identifier.
- Canonical unit identifiers MUST be used consistently across all AOWIS-compliant systems, interfaces, storage formats, APIs, and inter-system data exchanges.
- Canonical unit identifiers MUST be interpreted independently of locale, display format, implementation, and system context.
- Canonical unit identifiers MUST remain stable across AOWIS-compliant systems and data formats.
- A numeric value is not necessarily a measurement quantity. Counts, indices, priorities, precision values, identifiers, and similar non-measurement numbers do not receive UCUM unit identifiers merely because they are numeric.
- Dimensionless physical quantities use the UCUM unity unit
1. Fixed-schema fields whose canonical unit is1do not require an AOWIS unit suffix when the field name unambiguously identifies the dimensionless quantity. - A numeric value whose physical quantity depends on another field, enum, object type, equation, or operating mode MUST NOT be assigned a misleading fixed unit. It MUST be resolved through a quantity-specific field or discriminated structure.
- Equation coefficients whose dimensions depend on a configurable non-integer exponent MUST be stored together with the equation parameters that determine their dimensional meaning and MUST NOT be represented as if they had one fixed standalone UCUM unit.
- Backend-native, imported, display, and user-selected units MUST be converted to the canonical AOWIS representation at system boundaries unless the backend-native representation is itself the canonical AOWIS representation.
- Currencies and exchange rates are outside UCUM unit conversion. Monetary values MUST identify or reference their ISO 4217 currency.
Requirements
REQ-MEAS-UNI-001: All physical unit identifiers MUST conform to UCUM. REQ-MEAS-UNI-002: Each fixed or resolved physical measurement quantity MUST be assigned exactly one UCUM unit identifier as its canonical unit identifier. REQ-MEAS-UNI-003: The canonical unit identifier assigned to a measurement quantity MUST be used consistently across all AOWIS-compliant systems, interfaces, storage formats, APIs, and inter-system data exchanges. REQ-MEAS-UNI-004: The measurement quantity identifier defines what is measured, while the unit identifier defines the unit in which it is expressed. REQ-MEAS-UNI-005: 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-UNI-006: Numeric values that are not physical measurement quantities MUST NOT be assigned UCUM unit identifiers solely because they are numeric. REQ-MEAS-UNI-007: A value whose physical 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-UNI-008: An equation coefficient whose dimensions depend on a configurable non-integer exponent MUST be stored together with the parameters that determine its dimensional meaning and MUST NOT be assigned a misleading fixed standalone UCUM unit. REQ-MEAS-UNI-009: Non-canonical backend, import, display, or user-selected units MUST be converted to the canonical AOWIS representation at system boundaries. REQ-MEAS-UNI-010: Currencies MUST NOT be represented as UCUM units in AOWIS. Monetary values MUST identify or reference a currency using its ISO 4217 currency identifier.
Interpretation of the Requirements
This section is informative. The normative requirements above remain authoritative.
The requirements distinguish physical measurement quantities from other numeric values and from monetary values. Physical measurement quantities use canonical UCUM units, including UCUM 1 for dimensionless physical quantities. Numeric values such as counts, priorities, indices, or precision settings are not measurement quantities merely because they are numeric and therefore do not require UCUM units.
A measurement value whose physical quantity depends on another field, object type, operating mode, or equation must first be resolved to a specific measurement quantity. Once resolved, that quantity uses the canonical UCUM unit defined by AOWIS. This applies, for example, to valve settings, control and rule values, water-quality values, report thresholds, and similar context-dependent fields.
Backend, import, export, user-selected, and display units do not change the canonical AOWIS representation. Conversion to and from non-canonical units occurs at system boundaries.
Equation coefficients whose dimensions depend on configurable parameters, such as an arbitrary emitter exponent, must retain the parameters required to interpret their dimensional meaning and must not be assigned a misleading fixed unit.
Monetary values are outside the UCUM measurement-unit system. Their currency is identified or referenced using ISO 4217, while any physical denominator such as kilowatt-hour or kilowatt remains governed by this measurement standard.
Examples
| Example | Interpretation |
|---|---|
volumetric_flow_rate = 12.5 m3/h |
Physical measurement; canonical UCUM unit m3/h
|
demand_multiplier = 1.2 |
Dimensionless physical measurement; canonical UCUM unit 1
|
rule_priority = 5 |
Numeric value, not a physical measurement; no UCUM unit |
energy_price = 0.25 EUR/kWh |
EUR is ISO 4217 currency information; kW.h is the physical unit in the denominator
|
FCV setting = 20 m3/h; PRV setting = 30 m |
Both are settings, but they resolve to different measurement quantities and therefore different canonical units |
Canonical Measurement Quantities and Units
The canonical UCUM unit identifier assigned to a measurement quantity is authoritative whenever a unit identifier is represented in serialization or data exchange.
The AOWIS identifier suffix is an ASCII-safe representation used in field names, property names, database columns, and other technical identifiers. Division is represented by _per_, multiplication by _, and upper case is normalized to lower case. A quantity-specific semantic qualifier MAY be included where a literal unit-only suffix would be ambiguous or misleading; for example, mm2_per_m_head makes explicit that the denominator represents pressure head.
For fixed-schema measurement fields, the measurement quantity and canonical unit MAY be defined normatively by the schema and represented through the field name and its AOWIS identifier suffix. Such fields do not require a separate unit-identifier property.
Dimensionless fixed-schema fields whose canonical unit is 1 normally omit a unit suffix. Semantic words such as ratio, factor, coefficient, multiplier, and exponent describe the quantity and are not unit suffixes.
When a unit identifier is represented explicitly, it MUST use the canonical UCUM identifier assigned to the measurement quantity. The AOWIS identifier suffix is a technical field-naming convention and is not itself a UCUM unit identifier.
Generic or dynamically typed physical measurement values MUST explicitly identify their resolved measurement quantity and canonical UCUM unit and MUST NOT rely solely on a field-name suffix.
Each identifier suffix is explicitly defined in the following tables.
Length and Distance Quantities
| Measurement Quantity Identifier | Definition | Canonical Unit | Canonical UCUM Unit Identifier | AOWIS Identifier Suffix | AOWIS Model / EPANET Mapping |
|---|---|---|---|---|---|
length |
Linear spatial extent along an object or path | metre (m) | m |
m |
Pipe and link length |
elevation |
Vertical height relative to an engineering or hydraulic datum | metre (m) | m |
m |
Junction, tank, reservoir, and terrain elevation |
altitude |
Vertical position reported by a geographic positioning source | metre (m) | m |
m |
Geographic altitude; not necessarily suitable as hydraulic elevation |
distance |
Spatial separation between positions | metre (m) | m |
m |
Derived geometric distance |
vertical_offset |
Vertical difference between referenced elevations or heads | metre (m) | m |
m |
Elevation, tank-bottom, and reservoir-head offsets |
link_diameter |
Internal or nominal diameter of a pipe or valve | millimetre (mm) | mm |
mm |
EPANET pipe and valve diameter |
tank_diameter |
Internal diameter of a cylindrical storage tank | metre (m) | m |
m |
EPANET tank diameter |
darcy_weisbach_roughness_height |
Absolute pipe-wall roughness height used by the Darcy-Weisbach head-loss formulation | millimetre (mm) | mm |
mm |
EPANET Darcy-Weisbach pipe roughness |
Geographic Coordinate Quantities
| Measurement Quantity Identifier | Definition | Canonical Unit | Canonical UCUM Unit Identifier | AOWIS Identifier Suffix | AOWIS Model / EPANET Mapping |
|---|---|---|---|---|---|
latitude |
Angular position north or south of the equator | degree (°) | deg |
deg |
WGS 84 latitude |
longitude |
Angular position east or west of the prime meridian | degree (°) | deg |
deg |
WGS 84 longitude |
projected_easting |
Eastward coordinate within a projected coordinate reference system | metre (m) | m |
m |
UTM, UPS, and other projected-coordinate eastings |
projected_northing |
Northward coordinate within a projected coordinate reference system | metre (m) | m |
m |
UTM, UPS, and other projected-coordinate northings |
local_x |
X coordinate within an explicitly defined local engineering coordinate system | metre (m) | m |
m |
Local engineering coordinates when the local coordinate system is defined in metres |
local_y |
Y coordinate within an explicitly defined local engineering coordinate system | metre (m) | m |
m |
Local engineering coordinates when the local coordinate system is defined in metres |
Area and Volume
| Measurement Quantity Identifier | Definition | Canonical Unit | Canonical UCUM Unit Identifier | AOWIS Identifier Suffix | AOWIS Model / EPANET Mapping |
|---|---|---|---|---|---|
area |
Two-dimensional spatial extent | square metre (m²) | m2 |
m2 |
Tank cross-sectional area and other geometric areas |
volume |
Three-dimensional spatial extent or storage capacity | cubic metre (m³) | m3 |
m3 |
Tank volume |
Flow and Transport
| Measurement Quantity Identifier | Definition | Canonical Unit | Canonical UCUM Unit Identifier | AOWIS Identifier Suffix | AOWIS Model / EPANET Mapping |
|---|---|---|---|---|---|
volumetric_flow_rate |
Volume transported per unit time | cubic metre per hour (m³/h) | m3/h |
m3_per_h |
Demand, link flow, leakage flow, emitter flow, and pump-curve flow |
velocity |
Rate of linear movement | metre per second (m/s) | m/s |
m_per_s |
Link flow velocity |
Hydraulic Head, Pressure, and Stress
| Measurement Quantity Identifier | Definition | Canonical Unit | Canonical UCUM Unit Identifier | AOWIS Identifier Suffix | AOWIS Model / EPANET Mapping |
|---|---|---|---|---|---|
hydraulic_head |
Total mechanical energy per unit weight of fluid expressed as an equivalent fluid-column height | metre (m) | m |
m |
Junction, reservoir, and tank hydraulic head |
pressure_head |
Fluid pressure expressed as an equivalent fluid-column height | metre (m) | m |
m |
EPANET node pressure, pressure-driven demand thresholds, and pressure-control valve settings |
water_level |
Height of a water surface relative to a defined local reference level | metre (m) | m |
m |
Initial, minimum, maximum, and simulated tank levels |
head_gain |
Increase in hydraulic head across an energy-adding component | metre (m) | m |
m |
Pump head curves and pump simulation results |
head_loss |
Reduction in hydraulic head across a hydraulic component | metre (m) | m |
m |
Total head loss across pipes, valves, and other energy-dissipating components |
head_loss_gradient |
Hydraulic head loss per unit pipe length | metre per kilometre (m/km) | m/km |
m_per_km |
EPANET pipe head-loss reporting |
pressure |
Normal force per unit area within a fluid system | kilopascal (kPa) | kPa |
kpa |
Physical pressure measurements, sensors, SCADA data, and external-system exchange |
stress |
Internal force per unit area within a material | megapascal (MPa) | MPa |
mpa |
Structural and material analysis; not currently represented in the hydraulic model |
Time
| Measurement Quantity Identifier | Definition | Canonical Unit | Canonical UCUM Unit Identifier | AOWIS Identifier Suffix | AOWIS Model / EPANET Mapping |
|---|---|---|---|---|---|
elapsed_time |
Time elapsed from a defined simulation or process origin | second (s) | s |
s |
Simulation elapsed time and time-based control triggers |
duration |
Length of a time interval | second (s) | s |
s |
Simulation duration, hydraulic timesteps, quality timesteps, reporting intervals, and rule intervals |
time_of_day |
Time elapsed since the start of the current day | second (s) | s |
s |
Simulation start time of day and clock-time controls |
Hydraulic Coefficients and Other Dimensionless Quantities
The canonical UCUM unit identifier for the quantities in this section is 1. The AOWIS unit suffix is intentionally omitted. Semantic field-name components such as ratio, factor, coefficient, multiplier, and exponent remain part of the quantity name where useful.
| Measurement Quantity Identifier | Definition | Canonical Unit | Canonical UCUM Unit Identifier | AOWIS Identifier Suffix | AOWIS Model / EPANET Mapping |
|---|---|---|---|---|---|
hazen_williams_roughness_coefficient |
Empirical pipe roughness coefficient used by the Hazen-Williams head-loss formulation | dimensionless | 1 |
none | EPANET Hazen-Williams pipe roughness |
chezy_manning_roughness_coefficient |
Empirical pipe roughness coefficient used by the Chezy-Manning head-loss formulation | dimensionless | 1 |
none | EPANET Chezy-Manning pipe roughness |
minor_loss_coefficient |
Dimensionless coefficient representing local hydraulic losses through fittings, valves, or other components | dimensionless | 1 |
none | Pipe and valve minor-loss coefficient; TCV setting |
darcy_weisbach_friction_factor |
Dimensionless friction factor used in Darcy-Weisbach head-loss calculations | dimensionless | 1 |
none | Pipe simulation friction factor |
pump_speed_ratio |
Pump rotational speed relative to its nominal or reference speed | dimensionless | 1 |
none | Pump initial speed, simulated speed, pattern-modified speed, and pump control/rule settings |
pattern_multiplier |
Dimensionless factor applied by a hydraulic or energy pattern | dimensionless | 1 |
none | EPANET pattern factors |
demand_multiplier |
Global factor applied to base demands | dimensionless | 1 |
none | EPANET demand multiplier |
pressure_exponent |
Exponent used by the pressure-driven demand relation | dimensionless | 1 |
none | EPANET pressure exponent |
emitter_exponent |
Exponent used by the emitter pressure-flow relation | dimensionless | 1 |
none | EPANET emitter exponent |
reaction_order |
Exponent defining the order of a bulk, wall, or tank reaction equation | dimensionless | 1 |
none | EPANET bulk, wall, and tank reaction orders |
specific_gravity |
Fluid density relative to the reference density used by the hydraulic solver | dimensionless | 1 |
none | EPANET specific gravity |
relative_viscosity |
Fluid kinematic viscosity relative to the solver's reference viscosity | dimensionless | 1 |
none | EPANET relative viscosity |
relative_diffusivity |
Molecular diffusivity relative to the solver's reference diffusivity | dimensionless | 1 |
none | EPANET relative diffusivity |
mixing_fraction |
Fraction of tank volume assigned to the mixing zone in applicable tank mixing models | dimensionless | 1 |
none | EPANET tank mixing fraction |
hydraulic_accuracy |
Relative convergence criterion used by the hydraulic solver | dimensionless | 1 |
none | EPANET hydraulic accuracy |
hydraulic_damping_limit |
Relative accuracy threshold at which hydraulic solution damping/status checks are activated | dimensionless | 1 |
none | EPANET damping limit |
relative_error |
Relative numerical error reported by a solver or conformance check | dimensionless | 1 |
none | Hydraulic simulation statistics |
flow_balance_ratio |
Ratio of total outflow to total inflow | dimensionless | 1 |
none | EPANET flow-balance reporting |
quality_mass_balance_ratio |
Ratio expressing conservation of transported water-quality mass | dimensionless | 1 |
none | EPANET water-quality mass-balance statistic |
Percentage Quantities
| Measurement Quantity Identifier | Definition | Canonical Unit | Canonical UCUM Unit Identifier | AOWIS Identifier Suffix | AOWIS Model / EPANET Mapping |
|---|---|---|---|---|---|
efficiency |
Ratio of useful output to total input, expressed as a percentage | percent (%) | % |
percent |
Pump efficiency values and efficiency curves |
relative_flow |
Flow relative to a defined reference flow, expressed as a percentage | percent (%) | % |
percent |
Valve characteristic curves |
valve_position |
Valve opening position relative to its full operating range | percent (%) | % |
percent |
Position-control valves and valve characteristic curves |
source_trace_percentage |
Proportion of water originating from a specified source node | percent (%) | % |
percent |
EPANET source-trace analysis |
operating_time_percentage |
Fraction of a reporting period during which equipment is operating, expressed as a percentage | percent (%) | % |
percent |
Pump energy reporting time online |
demand_reduction_percentage |
Reduction in delivered demand relative to requested demand, expressed as a percentage | percent (%) | % |
percent |
Hydraulic simulation statistics |
leakage_loss_percentage |
Leakage loss relative to total system inflow, expressed as a percentage | percent (%) | % |
percent |
EPANET leakage-loss statistic |
Reaction and Leakage Quantities
| Measurement Quantity Identifier | Definition | Canonical Unit | Canonical UCUM Unit Identifier | AOWIS Identifier Suffix | AOWIS Model / EPANET Mapping |
|---|---|---|---|---|---|
first_order_bulk_reaction_coefficient |
First-order reaction-rate coefficient for a substance within the bulk fluid | per day (d⁻¹) | /d |
per_d |
Global, pipe-specific, and tank-specific first-order bulk reaction coefficients |
first_order_wall_reaction_coefficient |
First-order reaction-rate coefficient for a substance at a pipe wall | metre per day (m/d) | m/d |
m_per_d |
Global and pipe-specific first-order wall reaction coefficients |
leak_area_per_100m_pipe_length |
Effective leak area assigned per 100 metres of pipe length | square millimetre per 100 metres (mm²/100 m) | mm2/(100.m) |
mm2_per_100m |
EPANET 2.3 FAVAD leak area; EPANET defines the native value per 100 project length units, so non-metric projects require conversion at the adapter boundary[3] |
leak_area_expansion_per_pressure_head |
Increase in effective leak area per unit pressure head | square millimetre per metre of pressure head (mm²/m) | mm2/m |
mm2_per_m_head |
EPANET 2.3 FAVAD leak expansion; non-metric projects require pressure-head conversion at the adapter boundary[3] |
Water Quality Quantities
| Measurement Quantity Identifier | Definition | Canonical Unit | Canonical UCUM Unit Identifier | AOWIS Identifier Suffix | AOWIS Model / EPANET Mapping |
|---|---|---|---|---|---|
chemical_concentration |
Mass concentration of a chemical substance in water | milligram per litre (mg/L) | mg/L |
mg_per_l |
EPANET chemical-quality input, reaction limiting concentration, quality-source concentration, and simulation results |
chemical_mass_flow_rate |
Chemical mass introduced into or transported through the system per unit time | milligram per minute (mg/min) | mg/min |
mg_per_min |
EPANET mass-booster source strength and reported source mass rate when chemical concentration is canonicalized to mg/L |
water_age |
Time elapsed since water entered the modelled distribution system | hour (h) | h |
h |
EPANET water-age analysis |
Power, Energy, and Electrical Quantities
| Measurement Quantity Identifier | Definition | Canonical Unit | Canonical UCUM Unit Identifier | AOWIS Identifier Suffix | AOWIS Model / EPANET Mapping |
|---|---|---|---|---|---|
power |
Rate of energy transfer | kilowatt (kW) | kW |
kw |
Pump power and electrical power |
energy |
Work performed or energy transferred | kilowatt-hour (kWh) | kW.h |
kw_h |
Pump energy consumption and electrical energy |
energy_intensity |
Energy consumed per unit volume of transported water | kilowatt-hour per cubic metre (kWh/m³) | kW.h/m3 |
kw_h_per_m3 |
Pump energy-use reporting; canonical replacement for backend-dependent power-per-flow-unit values |
electric_current |
Rate of electric charge flow | ampere (A) | A |
a |
Electrical model |
voltage |
Electric potential difference | volt (V) | V |
v |
Electrical model |
electrical_resistance |
Opposition to electric current flow | ohm (Ω) | Ohm |
ohm |
Electrical model |
capacitance |
Ability to store electric charge | farad (F) | F |
f |
Electrical model |
Monetary Values and Currencies
Currencies are identifiers for monetary value and are not physical units in the AOWIS measurement system. AOWIS therefore does not encode currencies or currency compounds as UCUM unit identifiers.
A monetary value MUST identify or reference a currency definition whose identifier is the ISO 4217 alphabetic currency code. The currency definition MAY be managed by the AOWIS Controller or another authoritative subsystem.
AOWIS MAY support multiple currencies simultaneously. Exchange rates, exchange-rate timestamps, conversion policy, rounding policy, and accounting policy belong to the currency/controller subsystem and MUST NOT be treated as physical unit conversions.
Where a monetary quantity is normalized by a physical quantity, the physical denominator MUST use the canonical AOWIS physical unit. This yields the following canonical monetary semantics:
| Monetary Quantity Identifier | Definition | Currency Representation | Canonical Physical Denominator | AOWIS Model / EPANET Mapping |
|---|---|---|---|---|
energy_price |
Monetary price charged per unit of electrical energy | ISO 4217 currency reference | kilowatt-hour (kWh) | Global and pump-specific energy price |
demand_charge_rate |
Monetary demand charge per unit of peak power | ISO 4217 currency reference | kilowatt (kW) | Global demand charge |
daily_cost_rate |
Monetary cost accumulated or averaged per day | ISO 4217 currency reference | day (d) | Average pump cost, energy cost, demand charge, and total cost reporting |
A monetary value MUST NOT be interpreted without its currency reference. Two monetary values denominated in different currencies MUST NOT be compared, added, or aggregated without an explicit currency conversion performed by the currency/controller subsystem.
Context-Dependent Measurement Values
A numeric field whose measurement quantity or unit depends on another field, enum, object type, equation, or operating mode MUST NOT be assigned a single fixed canonical unit or AOWIS identifier suffix before that context has been resolved.
Such values MUST be represented using quantity-specific fields or a discriminated data structure that identifies the applicable measurement quantity. Once resolved to a defined measurement quantity, the value MUST use that quantity's canonical AOWIS unit.
| Current Model Concept | Context-Dependent Meaning | Required Resolution |
|---|---|---|
| Valve setting | PRV, PSV, and PBV settings are pressure head; FCV setting is volumetric flow rate; TCV setting is a minor-loss coefficient; PCV setting is valve position; GPV uses a curve reference rather than a numeric physical setting | Replace the generic numeric setting with quantity-specific fields or a discriminated valve-setting structure |
| Pump setting | Pump speed setting is a pump-speed ratio rather than a flow, head, or percentage | Represent pump settings explicitly as pump_speed_ratio
|
| Control action setting | The setting quantity supported by the controlled link type | Use the same quantity-specific representation as the target link |
| Control trigger level or pressure | Water level or pressure head, depending on the controlled node and control type | Represent water-level and pressure-head triggers separately |
| Rule premise value | Demand, hydraulic head, water level, pressure head, volumetric flow rate, power, elapsed time, time of day, fill time, drain time, or another quantity selected by the rule variable | Store the rule variable together with a quantity-specific value representation |
| Rule action setting | The setting quantity supported by the target link type | Use the same quantity-specific representation as the target link |
| Initial quality and simulation quality | Chemical concentration, water age, or source-trace percentage, depending on the quality-analysis mode | Represent each quality-analysis value using its defined measurement quantity |
| Water-quality solver tolerance | Chemical concentration, water age, or source-trace percentage, depending on the quality-analysis mode | Bind the tolerance to the selected quality-analysis mode and represent it using that mode's canonical quantity |
| Quality-source strength | Chemical concentration or chemical mass flow rate, depending on the quality-source type | Represent source strength using a source-type-specific structure |
| Reported source mass rate | Chemical mass flow rate in chemical-quality analysis; other quality-analysis modes must not be mislabeled as chemical mass | Resolve the result through the active quality-analysis mode before assigning chemical_mass_flow_rate
|
| Bulk and wall reaction coefficients | The dimensions of the coefficient depend on the configured reaction order | Use first-order fixed quantities only when the reaction order is exactly first order; otherwise store the coefficient together with reaction order in a discriminated reaction-coefficient structure |
| Roughness-correlation reaction parameter | The parameter belongs to the configured wall-reaction correlation model and does not have a universally valid standalone measurement unit | Store it as part of the applicable reaction model rather than assigning a guessed fixed unit |
| Emitter coefficient | In the canonical AOWIS emitter equation Q = C H^n, Q is volumetric flow rate in m³/h, H is pressure head in m, and n is the dimensionless emitter exponent; the dimensional meaning of C therefore depends on n |
Store the coefficient and exponent together in a dedicated emitter relation. The coefficient MUST NOT claim one fixed standalone UCUM unit for arbitrary non-integer n
|
| Generic curve coordinates | Coordinate quantities determined by the curve type | Use a typed curve structure whenever the coordinate quantities are known; only genuinely generic curves may carry explicit quantity metadata |
| Report thresholds | The measurement quantity of the corresponding report field | Associate each threshold with the report field's defined measurement quantity and canonical unit |
| EPANET map and backdrop coordinates | Coordinate units determined by the associated EPANET map or backdrop configuration; None does not define a physical unit |
Convert to an explicitly identified geographic, projected, or local coordinate representation before treating the coordinates as physical measurements |
Boundary Conversion Rules
AOWIS canonical units define the public data contract. Backend-selected unit systems MUST NOT leak into fixed-schema AOWIS measurement fields.
The EPANET adapter MUST convert EPANET values to and from the canonical AOWIS units whenever EPANET's selected unit system differs from the canonical AOWIS representation.
This includes, where applicable:
- volumetric flow rates to and from
m3/h; - lengths and hydraulic heads to and from
m; - link diameters to and from
mm; - tank diameters to and from
m; - Darcy-Weisbach roughness to and from
mm; - head-loss gradients to and from
m/km; - leakage area to and from
mm2/(100.m); - leakage expansion to and from
mm2/mof pressure head; - energy-use reporting to
kW.h/m3where the backend reports power per selected flow unit; - chemical concentration to
mg/Lwhen chemical-quality support is active; - chemical mass flow rate to
mg/minwhen chemical-quality support is active.
A backend configuration value that selects how the backend displays or interprets units is not itself a substitute for unit information in the AOWIS data contract.
Data Model
Concrete AOWIS data structures and field definitions are specified by the AOWIS Server Model.
Fixed-schema fields encode their canonical unit through the normative schema and, where applicable, the AOWIS identifier suffix. Dimensionless fixed-schema fields with UCUM unit 1 may omit a unit suffix when their quantity is unambiguous. Generic or dynamically typed physical measurement values carry or resolve to an explicit canonical UCUM unit identifier.
Measurement fields defined by the model MUST use the canonical units specified on this page.
Monetary fields defined by the model MUST identify or reference an ISO 4217 currency and MUST follow the monetary-value rules on this page.
References
- ↑ Unified Code for Units of Measure (UCUM) https://ucum.org
- ↑ ISO 4217 Currency Codes https://www.iso.org/iso-4217-currency-codes.html
- ↑ 3.0 3.1 OWA-EPANET 2.3 release notes https://github.com/OpenWaterAnalytics/EPANET/blob/v2.3/ReleaseNotes2_3.md