GitHub

HydroModels.jl

Overview

HydroModels.jl is a modern hydrological modeling framework that extends and enhances SUPERFLEX's design philosophy. Built on Julia language and the SciML (Scientific Machine Learning) ecosystem, it combines flexible model construction with computational efficiency, particularly supporting deep learning integration in hydrological modeling.

Key Features

  • 🎯 Type-Stable Configuration: New HydroConfig system for optimal compiler optimization
  • 🚀 Differentiable Solvers: ForwardDiff and Mooncake support for model and ODE gradients
  • 🔧 Flexible Model Construction: Supports lumped, semi-distributed, and distributed models
  • 💡 Dual Construction Approaches: Both symbolic (@macros) and functional (pure functions) interfaces
  • 🧠 Deep Learning Integration: Neural network components for hybrid modeling
  • ⚡ High Performance: Leverages Julia v1.12+ advanced features
  • 📊 Efficient Solvers: Multiple solver types (Mutable, Immutable, ODE, Discrete)

Framework Capabilities

HydroModels.jl offers:

  • Easy implementation and customization of hydrological models
  • Integration with Julia's scientific computing ecosystem
  • Support for various modeling approaches:
    • Traditional conceptual models
    • Neural network enhanced models
    • Distributed hydrological systems

Installation

using Pkg
Pkg.add("HydroModels")

Quick Start

Get started quickly with our updated examples:

using HydroModels

# Define model using macros
@variables temp prcp flow
@parameters k

flux = @hydroflux flow ~ k * prcp
bucket = @hydrobucket :simple begin
    fluxes = begin
        flux
    end
end

# Configure and run
config = HydroConfig(solver = MutableSolver)
output = bucket(input_data, params, config)

See the Getting Started Guide for a complete tutorial.

New in Version 0.7

  • ✅ Clearer Interpolation Names: ConstantInterpolation and LinearInterpolation replace confusing old names
  • ✅ Type-Stable Configuration System: New HydroConfig replaces NamedTuple
  • ✅ Simplified Solver Types: MutableSolver, ImmutableSolver, ODESolver, DiscreteSolver
  • ✅ Enhanced Performance: 5-10% speed improvement, better memory efficiency
  • ✅ AD coverage: Gradient regression tests compare ForwardDiff, Mooncake, and finite differences
  • ✅ Functional Construction: Build fluxes with pure Julia functions
  • ✅ Better Error Messages: Clear validation and helpful error reporting
  • ✅ Consistent Terminology: htypes for multi-node modeling
  • ✅ Extension-First Neural Integration: Lux-backed neural constructors and initialization are provided by HydroModelsLuxExt

See the v0.6 to v0.7 migration guide for the breaking API changes.

Important Notes

Contributing

HydroModels.jl is an open-source project available on Github. We welcome contributions from the community to help advance deep learning applications in hydrology.