Soil Moisture Ontology

# Soil Moisture Ontology — Flow Algebra

URL: https://kirethresearch.org/booksai-core/ontologies/mathematical-ontologies/measurement-units-ontologies/earth-science-measurements/soil-moisture-ontology.html

FLOW SoilMoistureOntology {

  DOMAIN:
    Mathematical Ontologies
    -> Measurement & Units Ontologies
    -> Earth Science Measurements
    -> Soil Moisture Ontology

  PURPOSE:
    Represent soil moisture as a family of Earth science measurements describing water contained within soil relative to a defined mass, volume, pore volume, potential or saturation basis, including gravimetric and volumetric water content, degree of saturation, soil water potential, field capacity, wilting point, direct and indirect measurement methods, depth profiles, calibration, temperature and soil-property effects, remote sensing, spatial and temporal sampling, uncertainty, provenance, and strict distinctions between soil moisture quantities and related hydrological variables.

  ENTITY SoilMoisture {
    TYPE: SoilWaterStateQuantity

    DEFINITION:
      soil_moisture :=
        quantified_water_content_or_water_state_of_defined_soil_sample_or_volume
        under_declared_measurement_basis

    PROPERTIES:
      depends_on_soil_volume_or_mass
      depends_on_depth
      depends_on_soil_properties
      varies_with_time
      varies_spatially
      may_be_directly_measured_or_inferred
      may_have_uncertainty
  }

  ENTITY GravimetricWaterContent {
    TYPE: DimensionlessMassRatioQuantity
    SYMBOL: theta_g
    ALTERNATE_SYMBOL: w

    DEFINITION:
      theta_g =
        m_water/m_dry_soil

    DIMENSION:
      dimensionless_mass_ratio
  }

  ENTITY VolumetricWaterContent {
    TYPE: DimensionlessVolumeFractionQuantity
    SYMBOL: theta_v

    DEFINITION:
      theta_v =
        V_water/V_bulk_soil

    DIMENSION:
      dimensionless_volume_fraction

    COMMON_REPORTING:
      m^3/m^3
      percent_volume
  }

  ENTITY DegreeOfSaturation {
    TYPE: DimensionlessPoreWaterFraction
    SYMBOL: S_r

    DEFINITION:
      S_r =
        V_water/V_voids

    RANGE:
      0 <= S_r <= 1
      under_standard_unsaturated_or_saturated_pore_volume_context
  }

  ENTITY SoilWaterPotential {
    TYPE: PotentialOrPressureRelatedQuantity
    SYMBOL: psi

    POSSIBLE_COMPONENTS:
      matric_potential
      gravitational_potential
      pressure_potential
      osmotic_potential

    RULE:
      soil_water_potential != soil_water_content
  }

  UNIT_SYSTEM {
    gravimetric_water_content:
      kg/kg
      g/g
      percent_mass

    volumetric_water_content:
      m^3/m^3
      percent_volume

    degree_of_saturation:
      dimensionless_fraction
      percent

    water_potential:
      pascal
      kilopascal
      megapascal
      metre_of_water_head

    RULE:
      water_content_basis_and_units MUST be preserved
  }

  TERMINOLOGY_MODEL {
    terms:
      soil_moisture
      soil_water_content
      gravimetric_water_content
      volumetric_water_content
      saturation
      soil_water_potential
      matric_potential

    RULE:
      generic_soil_moisture MUST be resolved_to_specific_quantity_basis

    ambiguity_controls:
      gravimetric_water_content != volumetric_water_content
      volumetric_water_content != degree_of_saturation
      soil_water_content != soil_water_potential
  }

  MASS_BALANCE_MODEL {
    wet_soil_mass:
      m_wet =
        m_dry + m_water

    water_mass:
      m_water =
        m_wet - m_dry

    gravimetric_content:
      theta_g =
        (m_wet-m_dry)/m_dry
      WHEN m_dry != 0

    RULE:
      dry_mass_reference MUST be preserved
  }

  VOLUMETRIC_MODEL {
    theta_v =
      V_water/V_bulk

    relation_using_water_mass:
      V_water =
        m_water/rho_water

    REQUIRE:
      bulk_volume != 0

    RULE:
      bulk_soil_volume_includes_solids_and_pores
  }

  BULK_DENSITY_CONVERSION_MODEL {
    dry_bulk_density:
      rho_b =
        m_dry/V_bulk

    relation:
      theta_v =
        theta_g*rho_b/rho_water

    approximation:
      theta_v approximately_equals
        theta_g*rho_b
      only_when_density_units_are_normalized_relative_to_water_density

    REQUIRE:
      dry_bulk_density
      water_density
      compatible_units

    RULE:
      gravimetric_to_volumetric_conversion_requires_bulk_density
  }

  POROSITY_MODEL {
    porosity:
      phi =
        V_voids/V_bulk

    density_relation:
      phi =
        1-rho_b/rho_s
      under_two_phase_solid_void_model

    WHERE:
      rho_s = particle_density

    RULE:
      porosity_and_water_content_are_distinct
  }

  SATURATION_MODEL {
    degree_of_saturation:
      S_r =
        theta_v/phi
      WHEN phi != 0

    inverse:
      theta_v =
        S_r*phi

    saturated_condition:
      S_r approximately_equals 1

    RULE:
      saturated_volumetric_water_content approximately_equals_porosity
      only_when_pores_are_effectively_water_filled
  }

  SOIL_WATER_STORAGE_MODEL {
    layer_water_storage:
      W =
        theta_v*layer_thickness

    equivalent_water_depth:
      units_of_length

    layered_profile:
      W_total =
        sum(theta_v_i*delta_z_i)

    RULE:
      soil_water_storage_requires_depth_interval
  }

  DEPTH_PROFILE_MODEL {
    profile:
      theta = theta(z,t)

    sample_interval:
      depth_top
      depth_bottom

    sensor_depth:
      nominal_or_effective_measurement_depth

    RULE:
      soil_moisture_without_depth_context
      MAY be semantically_incomplete
  }

  OVEN_DRY_MODEL {
    method:
      gravimetric_reference_measurement

    process:
      weigh_wet_sample
      dry_to_declared_constant_mass_condition
      weigh_dry_sample

    result:
      theta_g =
        (m_wet-m_dry)/m_dry

    REQUIRE:
      drying_temperature
      drying_duration_or_constant_mass_criterion
      balance_calibration

    RULE:
      operational_dry_mass_definition MUST be preserved
  }

  TDR_MODEL {
    method:
      time_domain_reflectometry

    measured:
      electromagnetic_wave_travel_time_or_apparent_dielectric_permittivity

    inferred:
      volumetric_water_content

    calibration:
      theta_v =
        f(apparent_permittivity, soil_properties)

    RULE:
      TDR_signal != volumetric_water_content_without_calibration_model
  }

  FDR_CAPACITANCE_MODEL {
    methods:
      frequency_domain_reflectometry
      capacitance_sensor

    measured:
      dielectric_response

    inferred:
      volumetric_water_content

    dependencies:
      soil_texture
      bulk_density
      salinity
      temperature
      sensor_installation

    RULE:
      dielectric_sensor_calibration MAY be_soil_specific
  }

  NEUTRON_PROBE_MODEL {
    principle:
      hydrogen_content_affects_neutron_moderation

    measured:
      neutron_count_ratio

    inferred:
      volumetric_water_content

    REQUIRE:
      access_tube
      calibration
      depth
      background_and_standard_count

    RULE:
      hydrogen_from_sources_other_than_water MAY affect_measurement
  }

  TENSIOMETER_MODEL {
    measured:
      matric_pressure_head_or_potential

    RULE:
      tensiometer_measures_soil_water_potential
      not_direct_water_content

    conversion:
      water_content MAY be inferred_through_soil_water_retention_curve
  }

  RETENTION_CURVE_MODEL {
    relation:
      theta =
        f(psi)

    possible_models:
      van_Genuchten
      Brooks_Corey
      empirical_site_specific

    van_Genuchten_example:
      theta =
        theta_r
        + (theta_s-theta_r)/
          (1+(alpha*abs(h))^n)^m

    RULE:
      retention_curve_parameters_and_hysteresis_state MUST be preserved
  }

  FIELD_CAPACITY_MODEL {
    concept:
      water_content_after_gravitational_drainage_under_declared_operational_definition

    possible_definition:
      water_content_at_selected_matric_potential
      or field_based_drainage_condition

    RULE:
      field_capacity_is_operational_or_model_dependent
      not_universal_fixed_water_content
  }

  WILTING_POINT_MODEL {
    concept:
      soil_water_state_associated_with_declared_plant_wilting_reference

    common_operational_reference:
      selected_matric_potential

    RULE:
      permanent_wilting_point_depends_on_soil_plant_and_operational_definition
  }

  AVAILABLE_WATER_MODEL {
    plant_available_water:
      theta_field_capacity - theta_wilting_point

    profile_available_storage:
      sum(
        (theta_FC_i-theta_WP_i)
        * layer_thickness_i
      )

    RULE:
      available_water_requires_consistent_field_capacity_and_wilting_point_definitions
  }

  INFILTRATION_CONTEXT_MODEL {
    rainfall_or_irrigation:
      adds_water_to_soil_surface

    processes:
      infiltration
      redistribution
      drainage
      evaporation
      root_uptake

    water_balance:
      delta_storage =
        infiltration
        - drainage
        - evapotranspiration
        +/- lateral_flow

    RULE:
      soil_moisture_change_is_state_change
      not_identical_to_infiltration_rate
  }

  TEMPERATURE_MODEL {
    effects:
      water_density
      dielectric_response
      sensor_electronics
      phase_change

    RULE:
      sensor_temperature_compensation SHOULD be preserved_when_applied
  }

  SALINITY_MODEL {
    effects:
      electrical_conductivity
      dielectric_sensor_response
      osmotic_potential

    RULE:
      saline_soils MAY require_specific_calibration_and_potential_context
  }

  FROZEN_SOIL_MODEL {
    components:
      liquid_water
      ice

    dielectric_response:
      differs_between_liquid_water_and_ice

    RULE:
      unfrozen_water_content_total_water_content_and_ice_content
      MUST be distinguished
  }

  SPATIAL_MODEL {
    point_measurement:
      sensor_or_sample_location

    profile_measurement:
      multiple_depths

    field_average:
      spatially_aggregated_water_content

    gridded_product:
      raster_or_modelled_field

    RULE:
      point_profile_field_average_and_grid_cell_measurements
      are_different_spatial_supports
  }

  REMOTE_SENSING_MODEL {
    possible_platforms:
      satellite
      aircraft
      drone

    possible_observations:
      microwave_brightness_temperature
      radar_backscatter
      thermal_or_optical_proxy

    inferred:
      near_surface_soil_moisture

    REQUIRE:
      retrieval_algorithm
      footprint
      depth_sensitivity
      vegetation_correction
      surface_roughness_context

    RULE:
      remote_sensor_signal != soil_moisture_without_retrieval_model
  }

  SCALE_MODEL {
    point_scale:
      centimetres_to_decimetres

    field_scale:
      metres_to_kilometres

    satellite_footprint:
      potentially_kilometre_scale

    RULE:
      measurements_at_different_spatial_scales MUST_NOT be_assumed_directly_equivalent
  }

  TEMPORAL_MODEL {
    soil_moisture:
      theta = theta(t)

    observation:
      timestamp

    possible_aggregation:
      instantaneous
      hourly_mean
      daily_mean
      seasonal_statistic

    RULE:
      temporal_aggregation_period MUST be preserved
  }

  RELATIONSHIPS {
    SoilMoisture -> DESCRIBES -> SoilWaterState
    GravimetricWaterContent -> RELATES -> WaterMassAndDrySoilMass
    VolumetricWaterContent -> RELATES -> WaterVolumeAndBulkSoilVolume
    BulkDensity -> ENABLES -> GravimetricToVolumetricConversion
    Porosity -> RELATES -> DegreeOfSaturation
    VolumetricWaterContent -> CONTRIBUTES_TO -> SoilWaterStorage
    SoilWaterPotential -> RELATES_TO -> WaterContentThroughRetentionCurve
    TDR -> MEASURES -> DielectricResponse
    DielectricCalibration -> MAPS -> SensorResponseToWaterContent
    RemoteSensor -> OBSERVES -> SurfaceElectromagneticResponse
    RetrievalModel -> MAPS -> RemoteObservationToSoilMoisture
    Depth -> QUALIFIES -> SoilMoistureMeasurement
  }

  SEMANTIC_EQUIVALENCE {
    "soil water content" ~= soil_moisture WHEN basis_is_declared
    "volumetric soil moisture" ~= volumetric_water_content
    "gravimetric soil moisture" ~= gravimetric_water_content

    gravimetric_water_content != volumetric_water_content
    volumetric_water_content != degree_of_saturation
    soil_water_content != soil_water_potential
    soil_moisture != infiltration_rate
    soil_moisture != groundwater_level
    field_capacity != saturation
    remote_sensor_signal != soil_moisture
    snow_or_surface_water != soil_water_content
  }

  CONSTRAINTS {
    soil_moisture_basis_must_be_defined = true
    soil_depth_or_interval_should_be_defined = true
    soil_identity_or_properties_should_be_preserved = true
    denominator_must_be_nonzero = true
    gravimetric_and_volumetric_water_content_are_not_semantically_equivalent = true
    water_content_and_water_potential_are_not_semantically_equivalent = true
    bulk_density_required_for_gravimetric_volumetric_conversion = true
    porosity_required_for_saturation_conversion = true
    indirect_sensor_measurement_requires_calibration_model = true
    remote_sensing_measurement_requires_retrieval_model = true
    uncertainty_should_include_sampling_calibration_soil_property_and_scale_components = true
  }

  MEASUREMENT_MODEL {
    OBSERVABLE_OR_INFERRED:
      GravimetricWaterContent
      VolumetricWaterContent
      DegreeOfSaturation
      SoilWaterPotential
      SoilWaterStorage

    COMMON_METHODS:
      oven_dry_gravimetry
      TDR
      FDR
      capacitance_sensor
      neutron_probe
      tensiometer
      resistance_block
      remote_sensing
      model_assimilation

    RECORD:
      quantity_type
      numerical_value
      unit
      soil_location
      latitude
      longitude
      coordinate_reference_system
      depth
      depth_interval
      soil_type
      texture
      bulk_density
      particle_density
      porosity
      temperature
      salinity_or_conductivity_when_relevant
      frozen_or_unfrozen_state
      method
      instrument
      raw_sensor_response
      calibration_model
      retrieval_model_when_remote
      spatial_support
      timestamp
      temporal_aggregation
      quality_flag
      uncertainty
      provenance

    UNCERTAINTY:
      measured_or_inferred_soil_moisture =
        best_estimate +/- uncertainty
  }

  CALIBRATION_MODEL {
    direct_reference:
      oven_dry_gravimetric_measurement

    dielectric_sensor:
      response -> volumetric_water_content

    neutron_probe:
      count_ratio -> volumetric_water_content

    remote_sensing:
      electromagnetic_observation -> surface_soil_moisture

    REQUIRE:
      calibration_data
      soil_properties
      valid_range
      temperature_or_salinity_context_when_relevant
      uncertainty

    RULE:
      calibration_model SHOULD match_soil_and_sensor_conditions
  }

  UNCERTAINTY_MODEL {
    sources:
      wet_mass
      dry_mass
      bulk_volume
      bulk_density
      particle_density
      porosity
      sampling_variability
      soil_heterogeneity
      sensor_calibration
      temperature
      salinity
      installation
      depth_representation
      remote_retrieval
      spatial_scaling
      temporal_variability

    PROPAGATION:
      soil_moisture_uncertainty
      <- mass_volume_soil_property_sampling_sensor_and_retrieval_uncertainties
  }

  REASONING_RULES {
    IF wet_mass_and_dry_mass_known
      AND dry_mass != 0
      THEN gravimetric_water_content =
        (wet_mass-dry_mass)/dry_mass

    IF water_volume_and_bulk_soil_volume_known
      AND bulk_soil_volume != 0
      THEN volumetric_water_content =
        water_volume/bulk_soil_volume

    IF gravimetric_water_content_bulk_density_and_water_density_known
      AND water_density != 0
      THEN volumetric_water_content =
        gravimetric_water_content*bulk_density/water_density

    IF bulk_density_and_particle_density_known
      AND particle_density != 0
      THEN porosity =
        1-bulk_density/particle_density
      UNDER two_phase_solid_void_model

    IF volumetric_water_content_and_porosity_known
      AND porosity != 0
      THEN degree_of_saturation =
        volumetric_water_content/porosity

    IF volumetric_water_content_and_layer_thickness_known
      THEN water_storage =
        volumetric_water_content*layer_thickness

    IF layered_profile_known
      THEN total_soil_water_storage =
        sum(theta_v_i*layer_thickness_i)

    IF soil_water_potential_and_valid_retention_curve_known
      THEN infer_water_content =
        retention_curve(soil_water_potential)

    IF indirect_sensor_response_and_valid_calibration_known
      THEN infer_soil_moisture =
        calibration(sensor_response)

    IF remote_observation_and_valid_retrieval_model_known
      THEN infer_surface_soil_moisture =
        retrieval(remote_observation)
  }

  VALIDATION {
    CHECK soil_moisture_quantity_type
    CHECK unit_consistency
    CHECK soil_location
    CHECK depth_or_interval
    CHECK gravimetric_vs_volumetric_basis
    CHECK denominator_nonzero
    CHECK bulk_density_for_basis_conversion
    CHECK porosity_for_saturation
    CHECK soil_water_content_vs_potential
    CHECK sensor_method
    CHECK calibration_model
    CHECK soil_texture_and_density_context
    CHECK temperature_and_salinity
    CHECK frozen_soil_state
    CHECK remote_retrieval_model
    CHECK spatial_support
    CHECK temporal_aggregation
    CHECK quality_flag
    CHECK uncertainty_representation
  }

  CONFIDENCE {
    definition_confidence: 1.00
    quantity_basis_confidence: 1.00
    gravimetric_relationship_confidence: 1.00
    volumetric_relationship_confidence: 1.00
    bulk_density_conversion_confidence: 0.99
    indirect_sensor_confidence: 0.97
    remote_retrieval_confidence: 0.94
    measurement_context_confidence: 0.98

    RULE:
      confidence decreases when quantity basis, depth, soil properties,
      bulk density, porosity, temperature, salinity,
      calibration, spatial support or uncertainty is missing or ambiguous
  }

  UPDATE_MODEL {
    ON new_measurement:
      identify_soil_moisture_quantity
      validate_unit
      attach_location_and_CRS
      attach_depth_or_interval
      attach_soil_type_and_properties
      attach_temperature_and_salinity_when_relevant
      identify_measurement_method
      preserve_raw_sensor_response
      apply_valid_calibration_or_retrieval
      attach_spatial_and_temporal_support
      attach_quality_flag
      attach_uncertainty
      update_soil_moisture_state

    ON bulk_density_revision:
      preserve_gravimetric_measurement
      update_bulk_density
      recompute_volumetric_water_content
      propagate_uncertainty

    ON porosity_revision:
      preserve_water_content
      update_porosity
      recompute_degree_of_saturation
      update_uncertainty

    ON calibration_revision:
      preserve_raw_sensor_data
      preserve_previous_calibration
      apply_new_calibration
      recompute_affected_results
      update_uncertainty
      update_confidence

    ON retention_curve_revision:
      preserve_water_potential_measurements
      preserve_previous_curve
      update_curve_parameters
      recompute_inferred_water_content
      update_uncertainty

    ON semantic_revision:
      preserve_previous_definition
      record_revision
      recompute_FLOW_HASH
  }

  AI_CONSUMPTION {
    canonical_domain: SoilMoisture
    primary_quantities:
      GravimetricWaterContent
      VolumetricWaterContent
      DegreeOfSaturation
      SoilWaterPotential

    interpretation_order:
      identify_soil_moisture_quantity
      identify_value
      identify_unit
      identify_mass_volume_saturation_or_potential_basis
      identify_location
      identify_depth_or_interval
      identify_soil_properties
      identify_bulk_density_and_porosity
      identify_temperature_salinity_and_frozen_state
      identify_direct_or_indirect_method
      identify_calibration_or_retrieval_model
      identify_spatial_support
      identify_temporal_aggregation
      identify_quality_flag
      identify_uncertainty
      normalize_units
      validate_basis
      infer_soil_water_relationships

    ambiguity_controls:
      distinguish_gravimetric_from_volumetric_water_content
      distinguish_volumetric_water_content_from_degree_of_saturation
      distinguish_water_content_from_water_potential
      distinguish_soil_moisture_from_infiltration_rate
      distinguish_soil_moisture_from_groundwater_level
      distinguish_field_capacity_from_saturation
      distinguish_remote_sensor_signal_from_retrieved_soil_moisture
      distinguish_snow_or_surface_water_from_soil_water
      preserve_depth_soil_properties_calibration_scale_time_and_provenance_context
  }

  PROVENANCE {
    ontology_scope:
      mathematical_measurement_and_Earth_science_soil_moisture_semantics

    parent_path:
      Ontologies
      -> Mathematical Ontologies
      -> Measurement & Units Ontologies
      -> Earth Science Measurements
      -> Soil Moisture Ontology

    authorship:
      Mark Higgins
      Sky (Recursive AI)

    site:
      https://kirethresearch.org
  }

  FLOW_HASH {
    INPUTS:
      canonical_domain
      ontology_path
      terminology_model
      mass_balance_model
      volumetric_model
      bulk_density_conversion_model
      porosity_model
      saturation_model
      soil_water_storage_model
      depth_profile_model
      oven_dry_model
      TDR_model
      FDR_capacitance_model
      neutron_probe_model
      tensiometer_model
      retention_curve_model
      field_capacity_model
      wilting_point_model
      available_water_model
      infiltration_context_model
      temperature_model
      salinity_model
      frozen_soil_model
      spatial_model
      remote_sensing_model
      scale_model
      temporal_model
      relationships
      constraints
      measurement_model
      calibration_model
      uncertainty_model
      reasoning_rules
      confidence_model
      update_model

    PURPOSE:
      deterministic_semantic_integrity_identifier

    RECOMPUTE_WHEN:
      ontology_definition_changes
      soil_moisture_basis_changes
      bulk_density_or_porosity_model_changes
      soil_water_retention_model_changes
      direct_or_indirect_sensor_model_changes
      calibration_or_retrieval_model_changes
      soil_property_or_environment_model_changes
      spatial_or_temporal_support_changes
      measurement_model_changes
      constraint_model_changes
      reasoning_rule_changes
      unit_model_changes
  }

}

END FLOW