HydroMind

HydroMind helps you prepare hydrological data, train and evaluate machine-learning models, make predictions, and inspect the results. Most users choose one of three ways to work. Mind provides guided browser pages and charts. A compatible external Agent lets you describe the task in ordinary language while it handles supported workspace operations. Python gives you direct access to data, models, and evaluation functions when you want to write code or build a repeatable analysis.

中文说明 · What you can do · Start with Mind · Start with an Agent · Start with Python · Documentation

What you can do

Suppose you have daily rainfall, temperature, and streamflow observations. HydroMind can help you organize those values with their dates, basin IDs, variable names, and units; use them to train, validate, test, or run a hydrological model; and inspect the resulting metrics, logs, trained Checkpoint, or prediction file. The same tools also support model comparison, table recognition from scanned records, watershed extraction, and deployment of a reviewed model to a trusted application. Each focused guide states the required input, the action to take, the result to expect, and the checks that still belong to you.

HydroMind runs the computation you request. You choose the scientific question and assess whether the model is suitable for research or operational use. Before trusting a result, check the data source, units, missing values, time split, availability of forecast inputs, evaluation rules, and the conditions under which the model will be used. A completed task means the computation finished and its outputs are available for review. Hydrological soundness and transfer to another basin or period require further evaluation.

Start with Mind

Mind is the browser application and the simplest place to explore HydroMind. After installation and workspace initialization, start it from the project directory:

uv run hydro mind

The terminal prints a local address, normally beginning with http://localhost:8501. Keep the terminal running, open the printed address in a browser, and choose the page that matches your task from the top navigation. Begin with the Documentation page if you are not sure where to go. Use the Modeling pages to prepare data, describe a training or prediction task, follow its progress, and inspect its outputs. Use HydroAI inside Mind when you already have a clear goal and want to request supported modeling operations in ordinary language.

Mind keeps related task settings and results together, so you can leave a long computation running and return later to inspect its state. You can use the guided pages without writing Python. You still need to know what your variables mean and what result you expect. Mind shows missing or incompatible inputs; you interpret the scientific meaning of your data and whether a metric supports your conclusion.

Start with an Agent

Use a compatible external Agent when you want to describe the goal in ordinary language and leave HydroMind's operating details inside the conversation. Open the Agent in an initialized HydroMind project, tell it what data you have, what result you want, which scientific conditions must remain fixed, and whether it may execute the task or should stop after checking it. The Agent handles command names and configuration JSON. It should ask before making a choice that changes the scientific meaning, then report the final status and concrete outputs. The external Agent guide gives a short example and explains what you should confirm.

Start with Python

Use the Python interface when you want to prepare data in a script, develop or inspect a model, evaluate predictions, or connect HydroMind to other scientific code. The example below opens a prepared NetCDF file as HydroMind data and prints the dimensions, variables, and units that should be checked before modeling:

from hydromind.data import read_netcdf

data = read_netcdf("hydrodata.nc")

print(dict(data.sizes))
for name in data.data_vars:
    print(name, data[name].dims, data[name].attrs.get("units", "unit missing"))

The output should list the time and basin dimensions present in hydrodata.nc, followed by every variable, the dimensions it uses, and its unit. A missing unit is printed explicitly instead of being guessed. The HydroData guide shows how to construct this file from checked source data, and the Python modeling pages explain how data windows, model inputs, training, prediction, and evaluation fit together.

Direct calls to hydromind.data, hydromind.model, and hydromind.eval behave like ordinary Python code: your script decides what to run and what to save. When you want HydroMind to keep a submitted task, its status, and its outputs together so that Mind can display them later, use Mind or the recorded workspace operations documented in the modeling workflow.

Install HydroMind

Install the protected HydroMind Wheel from PyPI. Its formal build and product support target is Ubuntu 24.04 x86-64 with free-threaded CPython 3.14t, and its filename contains cp314-cp314t-manylinux_2_34_x86_64. The manylinux_2_34 part states the glibc compatibility baseline independently of the Linux distribution name. Use the website account that owns the license intended for this computer.

Create a clean uv project, install the published Wheel, and initialize the workspace:

uv init --bare --python 3.14t hydromind-workspace
cd hydromind-workspace
uv python pin 3.14t
uv add hydromind
uv run hydro init

hydro init authenticates the workspace online. It contacts the HydroMind server, prints a complete confirmation URL and a six-character code, and waits while you sign in with the licensed account. The server checks the account, license, and computer binding; initialization continues only after you confirm the matching code within 10 minutes and the server accepts the binding. After the command finishes, start the browser application from the same workspace with uv run hydro mind and open the URL printed by the terminal. Every later HydroMind process must still be able to reach the official server for authorization checks; while its license and binding remain valid, the computer needs no further manual confirmation. The HydroMind Overview gives the complete compatibility, binding, expiry, and first-launch checks.

Develop the repository from source

For contributors changing or testing the HydroMind repository, use the commands below. Repository development supports Python 3.13 or 3.14 on Linux, WSL, and Windows; use the dependency set that matches the development machine.

git clone https://github.com/CMajorChords/HydroMind.git
cd HydroMind
uv sync --extra cuda
uv run --no-sync hydro --help

Use uv sync --extra cpu instead when isolating CUDA dependency problems or developing on a CPU-only host. The repository's Agent instructions and focused validation commands own the rest of the contributor workflow; customer workspaces should continue to use the Wheel commands without --no-sync.

Direct command-line use

Use the hydro command-line program for exact, repeatable workspace operations or to inspect what an Agent does. Start with uv run hydro --help, then read the relevant leaf command help before using an option. Research is an optional Agent workflow for a study that continues across conversations or becomes a paper. Ordinary modeling uses the same training system directly.

Documentation

HydroMind uses the PolyForm Strict License 1.0.0. If you use it in research, cite the repository.