pysnowclim 0.1.0

A standalone package for the pySnowclim hydrological module.

pySnowClim

pySnowClim is a robust, efficient, and open-source Python implementation of the original SnowClim model written in MATLAB. pySnowClim addresses the practical need for a snow models that can accurately simulate snow accumulation and melt across both large regions and fine spatial detail. pySnowClim combines key physical processes with efficient algorithms to provide high-resolution snowpack estimates, especially useful in complex terrain. Many current snow models are either too simple, too computationally costly, or not easy to use with modern workflows.

The target audience of pySnowClim includes hydrologists, climatologists, ecologists, water resource managers, and students who need reliable snow modeling capabilities for applications such as:

• Research: Detailed energy balance studies and process investigations
• Operations: Water resource forecasting and management
• Education: Teaching snow physics and energy balance concepts
• Climate Studies: Long-term snow evolution under changing conditions
• Adaptation Planning: anticipating and planning adaptations to impacts of warming on snow-dependent species, ecosystems, and communities

More information about the package and the model can be found in the documentation page and Lute et al., 2022.

Installation

Prerequisites

• Python 3.8 or higher
• Git (for cloning the repository)
• See the requirements.txt file to check the required packages.

Option 1: Install from source (Recommended for development)

1.Clone the repository:

git clone https://github.com/abbylute/pySnowClim.git
cd pySnowClim

2.Create a virtual environment (recommended):

python -m venv pysnowclim-env
source pysnowclim-env/bin/activate  # On Windows: pysnowclim-env\Scripts\activate

or with conda:

# Create environment with Python
conda create -n pysnowclim python=3.9
conda activate pysnowclim

3.Install the package and dependencies: This installs the package in "editable" mode, so changes to the source code are immediately available.

pip install -e .

To verify that pySnowClim is installed correctly:

python verify_installation.py

Option 2: Install for regular use

pip install git+https://github.com/abbylute/pySnowClim.git

To verify that pySnowClim is installed correctly:

python -c "from createParameterFile import create_dict_parameters;print(create_dict_parameters())"

Running the Model

pySnowClim provides two main ways to run snow simulations:

1. Python API: Use the run_model function directly in Python scripts.
2. Command Line: Run simulations from the terminal using run_main.py.

Both approaches require meteorological forcing data and optionally accept custom parameter configurations.

Input Data Requirements

pySnowClim requires time series of meteorological variables. The model accepts data in NetCDF format (Recommended) or legacy MATLAB .mat files.

Required Variables:

• lrad (kJ/m²/timestep): Incoming longwave radiation
• solar (kJ/m²/timestep): Incoming solar radiation
• tavg (°C): Mean air temperature
• ppt (m/timestep): Total precipitation
• vs (m/s): Wind speed at reference height
• psfc (hPa): Surface atmospheric pressure
• huss (kg/kg): Specific humidity
• relhum (%): Relative humidity
• tdmean (°C): Dewpoint temperature

The forcing data should be organized as a NetCDF file with dimensions:

• time: Temporal dimension
• lat: Latitude dimension
• lon: Longitude dimension

Python API Usage

The primary interface for programmatic use:

from src.runsnowclim_model import run_model

# Basic simulation
results = run_model(
    forcings_path='forcing_data.nc',      # Input forcing data
    parameters_path='parameters.json',     # Custom parameters (optional)
    outputs_path='simulation_results/',    # Output directory
    save_format='.nc'                     # Save as NetCDF
)

# Results is a list of SnowModelVariables objects, one per timestep
print(f"Simulation completed: {len(results)} timesteps")

Command Line Usage

For operational use and batch processing:

# Basic usage - uses all defaults
python run_main.py

# Specify input forcing file
python run_main.py forcing_data.nc

# Specify input and output directories
python run_main.py forcing_data.nc results/

# Full specification with custom parameters
python run_main.py forcing_data.nc results/ custom_params.json .nc

# Run with MATLAB-format inputs (legacy)
python run_main.py data/ results/ parameters.json .npy

Command Line Arguments:

1. forcings_path (optional): Path to forcing data

   • Default: 'data/'
   • Can be NetCDF file or directory with .mat files

2. output_path (optional): Output directory

   • Default: 'outputs/'
   • Directory will be created if it doesn't exist

3. parameters_path (optional): JSON parameter file

   • Default: None (uses model defaults)
   • Must be valid JSON format

4. save_format (optional): Output file format

   • Default: None (saves as .npy files)
   • Use '.nc' for NetCDF output

For more information about how to run the model:

python run_main.py --help

Examples

The run_snowclim_example.py` script provides a complete workflow that:

1. Loads meteorological forcing data and observations
2. Runs the pySnowClim model with default parameters
3. Compares model output with observed snow water equivalent
4. Generates validation plots and performance statistics

Command Line Execution:

cd examples
python run_snowclim_example.py

Troubleshooting

Installation Problems

• Verify Python version (3.8+) and required packages
• Check file paths and permissions
• Ensure NetCDF libraries are properly installed

Input Data Issues

• Validate forcing data units and ranges
• Check for missing values or unrealistic extremes
• Verify coordinate system consistency

Parameter Problems

• Use create_dict_parameters() to ensure proper parameter structure
• Check JSON syntax if using custom parameter files
• Validate parameter value ranges

Memory Errors

• Reduce spatial domain size
• Increase available system memory

Convergence Issues

• Check energy balance components for unrealistic values
• Enable stability corrections for turbulent flux calculations
• Adjust energy smoothing parameters for sub daily simulations

Output Problems

• Ensure output directory exists and is writable
• Check available disk space
• Verify save format specification