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 performs the computation you request, but it does not choose the scientific question or certify a model for scientific or operational use. Before trusting a result, you still need to 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. It does not by itself show that the model is hydrologically sound or transferable to another basin or period.

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 do not need to know Python to use these guided pages. You do, however, need to know what your variables mean and what result you expect. Mind will show missing or incompatible inputs, but it cannot infer the scientific meaning of an unexplained table or decide 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. You do not need to supply command names or configuration JSON. The Agent should ask before making a choice that changes the scientific meaning and should report the real final status and concrete outputs rather than treating submission as completion. 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 the distributed Wheel

HydroMind is installed from the protected Wheel supplied by its distributor, not by cloning this repository. 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; it neither identifies nor restricts the Linux distribution. Keep the Wheel at a stable absolute path, confirm that the CPU architecture and Python ABI match, and use the website account that owns the license intended for this computer.

Create a clean uv project and replace the example path with the absolute path of the Wheel you received:

uv init --bare --python 3.14t hydromind-workspace
cd hydromind-workspace
uv python pin 3.14t
uv add '/absolute/path/to/hydromind-customer.whl'
uv run hydro init

hydro init is an online server-authentication step, not a local configuration shortcut. It contacts the HydroMind server, prints a complete confirmation URL and a six-digit 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, although the computer does not need another manual confirmation while its license and binding remain valid. The HydroMind Overview gives the complete compatibility, binding, expiry, and first-launch checks.

Develop the repository from source

The commands in this section are only for contributors who are changing or testing the HydroMind repository. They do not install the customer product and do not replace the protected-Wheel and server-authentication route above. 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

The hydro command-line program remains available when you want exact, repeatable workspace operations or want to inspect what an Agent does. It is not a fourth user route and is not something Agent users must learn first. Start with uv run hydro --help, then read the relevant leaf command help before using an option. Research is a separate, optional Agent workflow for a study that must continue across conversations or become a paper; it is not required for ordinary modeling and is not another training backend.

Documentation

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