Skip to content

Installation

This guide covers all methods to install hydromodel on different platforms.

Requirements

  • Python: 3.9 or higher
  • Operating System: Windows, macOS, or Linux
  • Disk Space: ~500 MB for package + data storage for datasets

Quick Installation

The fastest way to install hydromodel:

1
pip install hydromodel

This installs the latest stable release from PyPI.

Method 1: Using pip (Standard)

For most users, pip is the recommended installation method:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# Create a virtual environment (recommended)
python -m venv hydromodel-env

# Activate virtual environment
# On Windows:
hydromodel-env\Scripts\activate
# On macOS/Linux:
source hydromodel-env/bin/activate

# Install hydromodel
pip install hydromodel

# Install hydrodataset for data access
pip install hydrodataset

Method 2: Using uv (Faster)

uv is a faster package manager:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# Install uv
pip install uv

# Create virtual environment
uv venv

# Activate virtual environment
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install packages
uv pip install hydromodel hydrodataset

Installation with uv is typically 10-100x faster than pip.

Method 3: Using conda

If you use conda/mamba:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Create environment
conda create -n hydromodel python=3.11

# Activate environment
conda activate hydromodel

# Install from conda-forge (if available)
conda install -c conda-forge hydromodel

# Or use pip within conda
pip install hydromodel hydrodataset

Installation from Source

For developers or to get the latest development version:

Option A: Direct from GitHub

1
pip install git+https://github.com/OuyangWenyu/hydromodel.git

Option B: Clone and Install

1
2
3
4
5
6
7
8
9
# Clone repository
git clone https://github.com/OuyangWenyu/hydromodel.git
cd hydromodel

# Install in editable mode (for development)
pip install -e .

# Or install with all development dependencies
pip install -e ".[dev,docs]"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Clone repository
git clone https://github.com/OuyangWenyu/hydromodel.git
cd hydromodel

# Create environment and install dependencies
uv sync --all-extras

# Activate environment
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

Optional Dependencies

For Data Access

1
2
# CAMELS and other public datasets
pip install hydrodataset

For Visualization

1
2
# Plotting and analysis
pip install matplotlib seaborn plotly

For Development

1
2
# Testing, linting, documentation
pip install pytest black flake8 mkdocs mkdocs-material

All Optional Dependencies

1
2
# Install everything
pip install "hydromodel[all]"

Platform-Specific Instructions

Windows

  1. Install Python:
  2. Download from python.org

  3. Check "Add Python to PATH" during installation

  4. Install hydromodel: 

    1
    pip install hydromodel hydrodataset

  5. Verify installation: 

    1
    python -c "import hydromodel; print(hydromodel.__version__)"

macOS

  1. Install Python (using Homebrew): 

    1
    brew install python@3.11

  2. Install hydromodel: 

    1
    pip3 install hydromodel hydrodataset

  3. Verify installation: 

    1
    python3 -c "import hydromodel; print(hydromodel.__version__)"

Linux (Ubuntu/Debian)

  1. Install Python: 

    1
2
    sudo apt update
sudo apt install python3 python3-pip python3-venv

  2. Install hydromodel: 

    1
    pip3 install hydromodel hydrodataset

  3. Verify installation: 

    1
    python3 -c "import hydromodel; print(hydromodel.__version__)"

Verifying Installation

After installation, verify everything works:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# Test import
import hydromodel
import hydrodataset

# Check versions
print(f"hydromodel version: {hydromodel.__version__}")

# Test basic functionality
from hydromodel.models.model_factory import model_factory

# Create a model
model = model_factory(model_name="xaj_mz")
print(f"✓ Successfully created {model.__class__.__name__}")
print(f"✓ Model has {model.param_limits.shape[0]} parameters")
print("✓ Installation verified!")

Expected output: 

1
2
3
4
hydromodel version: 0.1.0
✓ Successfully created XajMz
✓ Model has 15 parameters
✓ Installation verified!

Configuration Setup

After installation, configure data paths:

Step 1: Create Configuration File

Create hydro_setting.yml in your home directory:

Windows: C:\Users\YourUsername\hydro_setting.yml macOS/Linux: ~/hydro_setting.yml

1
2
3
4
local_data_path:
  root: '/path/to/data'
  datasets-origin: '/path/to/data/datasets'
  cache: '/path/to/data/.cache'

Step 2: Verify Configuration

1
2
3
4
5
from hydromodel import SETTING

print("Configuration loaded:")
print(f"Root: {SETTING.get('local_data_path', {}).get('root')}")
print(f"Datasets: {SETTING.get('local_data_path', {}).get('datasets-origin')}")

Troubleshooting

Common Issues

Issue 1: "No module named 'hydromodel'"

Solution: Make sure the virtual environment is activated: 

1
2
3
4
5
# Check Python path
which python  # macOS/Linux
where python  # Windows

# Should point to virtual environment, not system Python

Issue 2: "Permission denied" during installation

Solution: Use --user flag or virtual environment: 

1
pip install --user hydromodel

Issue 3: Dependency conflicts

Solution: Use a fresh virtual environment: 

1
2
3
python -m venv fresh-env
source fresh-env/bin/activate  # or fresh-env\Scripts\activate on Windows
pip install hydromodel

Issue 4: Slow pip installation

Solution: Use uv for faster installation: 

1
2
pip install uv
uv pip install hydromodel

Issue 5: "Microsoft Visual C++ required" (Windows)

Solution: Install Visual C++ Build Tools: - Download from visualstudio.microsoft.com - Or install via Anaconda which includes pre-compiled packages

Getting Help

If you encounter issues:

  1. Check documentation: Browse docs
  2. Search issues: GitHub Issues
  3. Ask questions: Open a new issue with:
  4. Your OS and Python version
  5. Full error message
  6. Installation command used

Updating hydromodel

Update to Latest Stable Version

1
pip install --upgrade hydromodel

Update to Development Version

1
pip install --upgrade git+https://github.com/OuyangWenyu/hydromodel.git

Check Current Version

1
2
import hydromodel
print(hydromodel.__version__)

Uninstallation

To remove hydromodel:

1
pip uninstall hydromodel

To remove everything including dependencies:

1
2
3
4
5
# List installed packages
pip list | grep hydro

# Uninstall
pip uninstall hydromodel hydrodataset

To remove the virtual environment:

1
2
3
4
5
6
# Deactivate first
deactivate

# Remove directory
rm -rf hydromodel-env  # Linux/macOS
rmdir /s hydromodel-env  # Windows

Docker Installation (Advanced)

For reproducible environments:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# Dockerfile
FROM python:3.11-slim

# Install dependencies
RUN pip install --no-cache-dir hydromodel hydrodataset

# Set working directory
WORKDIR /app

# Copy your code
COPY . .

# Run your script
CMD ["python", "your_script.py"]

Build and run:

1
2
docker build -t hydromodel-app .
docker run -v $(pwd)/data:/app/data hydromodel-app

Next Steps

After successful installation:

  1. Quick Start: Follow the Quick Start Guide
  2. Configuration: Set up data paths and settings
  3. Tutorial: Try the usage examples
  4. API Documentation: Browse the API reference

Support

  • Documentation: https://OuyangWenyu.github.io/hydromodel
  • Issues: https://github.com/OuyangWenyu/hydromodel/issues
  • Discussions: https://github.com/OuyangWenyu/hydromodel/discussions