API Reference

This page provides detailed documentation for the main pySnowClim modules and functions.

Core Model Functions

Main Model Runner

The main entry point for running pySnowClim simulations. This module handles loading forcing data, parameter files, and coordinating model execution.

SnowClim Model Engine

snowclim_model.run_snowclim_model(forcings_data, parameters)

Simulates snow accumulation, melting, sublimation, condensation, and energy balance over a given time period based on meteorological inputs.

Parameters:

• forcings_data (dict) -- meteorological inputs.

• parameters (dict) -- Parameters required by the model.

Returns:

list with the results based on time.

Return type:

snow_model_instances (list)

The core snow model that performs the physics calculations and timestep iterations.

Parameter Configuration

This script creates and saves a dictionary of parameters for a snow model to read. Default values are based on the application of the snow model to the western United States. The parameters include settings for albedo, stability, snow density, and other model configurations.

createParameterFile.create_dict_parameters(cal=None, hours_in_ts=24, stability=None, windHt=None, tempHt=None, snowoff_month=None, snowoff_day=None, albedo_option=None, max_albedo=None, z_0=None, z_h=None, lw_max=None, Tstart=None, Tadd=None, maxtax=None, E0_value=None, E0_app=None, E0_stable=None, Ts_add=None, smooth_time_steps=None, ground_albedo=None, snow_emis=None, snow_dens_default=None, G=None, max_swe_height=None, downward_longwave_radiation_factor=None, downward_longwave_radiation_factor_start_month=None, downward_longwave_radiation_factor_end_month=None)

Writes parameters to a dictionary. Default values are those used in application of the snow model to the western United States, some of which were determined through calibration at SNOTEL stations (Lute et al., 2022).

Parameters:

• cal -- Time period for the model run (default: (2001-10-01 to 2002-09-30))

• hours_in_ts -- Hours in time step (default: 4)

• stability -- Stability setting (default: 1)

• windHt -- Wind height (default: 10)

• tempHt -- Temperature height (default: 2)

• snowoff_month -- Month of snow-off (default: 9)

• snowoff_day -- Day of snow-off (default: 1)

• albedo_option -- Albedo option (default: 2)

• max_albedo -- Maximum albedo (default: 0.85)

• z_0 -- Roughness length (default: 0.00001)

• z_h -- Roughness length for heat (default: z_0/10)

• lw_max -- Maximum liquid water fraction (default: 0.1)

• Tstart -- Starting temperature (default: 0)

• Tadd -- Temperature adjustment (default: -10000)

• maxtax -- Maximum tax (default: 0.9)

• E0_value -- Windless exchange coefficient (default: 1)

• E0_app -- Windless exchange application option (default: 1)

• E0_stable -- Windless exchange stability option (default: 2)

• Ts_add -- Temperature add factor (default: 2)

• smooth_time_steps -- Smoothing time steps (default: 12)

• ground_albedo -- Ground albedo (default: 0.25)

• snow_emis -- Snow emissivity (default: 0.98)

• snow_dens_default -- Default snow density (default: 250)

• G -- Ground conduction (default: 173/86400 kJ/m2/s)

• max_swe_height -- Max height of SWE before downward radiation factor starts to work (default: 100 m)

• downward_longwave_radiation_factor -- Factor to be multiplied by downward radiation when SWE > max_swe_height (default: 1.3)

• downward_longwave_radiation_factor_start_month -- Month where downward_longwave_radiation_factor start to be applied (default: 6)

• downward_longwave_radiation_factor_end_month -- Month where downward_longwave_radiation_factor ends (default: 10)

Functions for creating and managing model parameter configurations.

Data Structures

The model uses several key data structure classes:

Model Variables

class SnowModelVariables.SnowModelVariables(outdim)

SnowModelVariables initializes the key variables needed to run the snow model, pre-allocating arrays with NaN values for snowpack and energy flux calculations.

Container for all model output variables including snow properties, energy fluxes, and surface conditions.

__init__(outdim)

Snowpack State

class SnowpackVariables.Snowpack(n_lat, parameters)

Manages the internal state of the snowpack including temperature, density, liquid water content, and other physical properties.

__init__(n_lat, parameters)

Class to handle initialization and management of snowpack-related variables.

Args:

n_lat (int): Number of latitude points. parameters (dict): Dictionary of model parameters, including 'ground_albedo' and 'snow_dens_default'.

initialize_snowpack_base()

Initialize all core snowpack-related variables except 'lastpacktemp' and 'snowage'.

initialize_snowpack_runoff()

Initialize runoff.

initialize_full_snowpack()

Initialize all snowpack variables, including 'lastpacktemp' and 'snowage'.

apply_temperature_instability_correction(input_forcings)

Apply a temperature instability correction to adjust lastpacktemp and lastpackcc for snow with small SWE values.

Parameters:

• input_forcings (dict) -- Input meteorological forcings, including 'tavg'.

• sec_in_ts (float) -- Number of seconds in the timestep.

calculate_new_snow_temperature_and_cold_content(precip, input_forcings)

Calculate snow temperature and cold content and updates pack conditions.

Parameters:

• precip (object) -- Precipitation data with snowfall and rainfall properties.

• input_forcings -- dict, containing current timestep forcings such as temperature.

update_snowpack_water(has_snow, lw_max)

Update snowpack liquid water content based on thresholds for irreducible and maximum water.

Parameters:

• has_snow (numpy.ndarray) -- Active snowpack mask.

• sec_in_ts (int) -- Seconds in each timestep.

• lw_max (float) -- Maximum liquid water content as fraction of snow depth.

update_snowpack_state(input_forcings, parameters, snow_vars, precip, coords, time_value)

Updates the snowpack state variables based on surface temperature, snowfall, pack density, water content, and albedo.

Parameters:

• input_forcings (dict) -- Dictionary with temperature and other input forcings.

• parameters (dict) -- Model parameters for snowpack calculations.

• snow_vars (object) -- Snow model variables object for storing outputs.

• precip (class) -- Precipitation properties.

• sec_in_ts (float) -- Number of seconds in a timestep.

• coords (dict) -- Coordinates information.

• time_value (tuple) -- Current time step and other time-related info.

adjust_temp_snow()

Temperature adjustment for snow with positive SWE.

update_class_no_snow(parameters)

Temperature adjustment for snow with positive SWE.

update_pack_sublimation(Sublimation, has_sublimation)

Update snowpack properties by calculating sublimation.

Parameters:

• sublimation: Current sublimation value (kg/m²).

• has_sublimation: Where sublimatino occurs.

complete_pack_sublimation(Evaporation, no_snow_left, SnowDensDefault)

Finishes the sublimation process in the snowpack.

Parameters:

• Evaporation: Current Evaporation value (kg/m²).

• no_snow_left: Where snows is gone.

• SnowDensDefault: default values for the packsnowdensity.

Precipitation Properties

class PrecipitationProperties.PrecipitationProperties(rain, sfe, snowdens, snowfallcc)

This class takes the precipitation properties as inputs and computes the snow depth based on SWE and snow density.

rain

Rainfall in mm for the given timestep.

Type:

np.ndarray

sfe

Snowfall water equivalent in mm.

Type:

np.ndarray

snowdens

Density of the freshly fallen snow in kg/m^3.

Type:

np.ndarray

snowdepth

Calculated depth of snow based on SWE and snow density.

Type:

np.ndarray

calculate_snowdepth(water_density)

Computes the snow depth using SWE and snow density with a water density constant.

Handles precipitation phase partitioning and properties of rainfall and snowfall.

__init__(rain, sfe, snowdens, snowfallcc)

Initializes the PrecipitationProperties class with rainfall, SWE, and snow density values, and computes the snow depth.

Parameters:

• rain (np.ndarray) -- Rainfall amount (mm).

• sfe (np.ndarray) -- snowfall water equivalent (mm).

• snowdens (np.ndarray) -- Density of the fresh snow (kg/m^3).

• water_density (float) -- Constant representing water density (kg/m^3), typically 1000 for fresh water.