hydromodpy.core.units.types#

Pydantic-pint annotated types for hydrogeological quantities.

Two flavors are provided:

  • Length, Area, Volume, Time, FlowRate, Velocity, HydraulicConductivity, SpecificStorage, Dimensionless: Pydantic-pint Quantity types. Values keep their pint Quantity wrapper (useful for ratio arithmetic / serialization).

  • LengthMeters, AreaSquareMeters, VolumetricFlowM3PerSecond, DurationSeconds, HydraulicConductivityMPerS: float-valued annotated types that accept the same string/number inputs but expose a plain float in the canonical SI unit. Use these on existing fields whose downstream consumers expect plain numbers.

This module exports Annotated type aliases that can be used directly in Pydantic v2 models to enforce unit consistency. Each type accepts either a bare number (interpreted as the canonical SI unit) or a string “<value> <unit>” that pint can parse; the resulting value is always a pint Quantity in the canonical unit.

Example#

>>> from pydantic import BaseModel
>>> from hydromodpy.core.units import HydraulicConductivity
>>> class Aquifer(BaseModel):
...     k: HydraulicConductivity
>>> Aquifer(k="1e-4 m/s").k.to("m/s").magnitude
0.0001
>>> Aquifer(k=1e-4).k.to("m/s").magnitude  # bare number, fallback m/s
0.0001
>>> Aquifer(k="0.36 m/h").k.to("m/s").magnitude  # auto-convert
0.0001

Design notes#

  • All annotations reuse the shared UREG registry (see registry.py) so that quantities from different fields remain comparable.

  • BeforeValidator coerces bare numeric inputs (int/float, but NOT bool) to the canonical-unit string before handing off to pydantic-pint. Important: in an Annotated[...] chain, later entries wrap earlier ones, so BeforeValidator must be listed after PydanticPintQuantity - otherwise pydantic-pint’s custom core schema replaces the chain and the before-validator never runs.

  • SpecificYield is a plain float constrained to [0, 1] (it is genuinely dimensionless with a physical range) - not a pint Quantity.

  • Dimensionless is the pint way to express a pure-number quantity when the pipeline expects a Quantity object regardless.

Module attributes

Length

Length in metres.

Area

Area in square metres.

Volume

Volume in cubic metres.

Time

Duration in seconds.

FlowRate

Volumetric flow rate in m^3/s.

Velocity

Velocity / flux density in m/s.

HydraulicConductivity

Hydraulic conductivity (K) in m/s.

SpecificStorage

Specific storage (Ss) in m^-1.

SpecificYield

Specific yield (Sy), a pure number in [0, 1].

Dimensionless

Dimensionless pint Quantity (-).

LengthMeters

Length in metres expressed as float.

AreaSquareMeters

Area in m^2 expressed as float.

VolumetricFlowM3PerSecond

Volumetric flow rate in m^3/s expressed as float.

DurationSeconds

Duration in seconds expressed as float.

HydraulicConductivityMPerS

Hydraulic conductivity in m/s expressed as float.
On this page