Package: openamundsen
openAMUNDSENopenAMUNDSEN is a modular snow and hydroclimatological modeling framework written in Python.OverviewopenAMUNDSEN is a fully distributed model, designed primarily for resolving the mass and energy
balance of snow and ice covered surfaces in mountain regions.
Typically, it is applied in areas ranging from the point scale to the regional scale (i.e., up to
some hundreds to thousands of square kilometers), using a spatial resolution of 10–100 m and a
temporal resolution of 1–3 h, however its potential applications are very versatile. Additional documentation can be found atdoc.openamundsen.org.Main features include:Spatial interpolation of scattered meteorological point measurements using a combined lapse
rate – inverse distance weighting schemeCalculation of solar radiation taking into account terrain slope and orientation, hill shading
and atmospheric transmission losses and gains due to scattering, absorption, and reflectionsAdjustment of precipitation using several correction functions for wind-induced undercatch and
redistribution of snow using terrain-based parameterizationsSimulation of the snow and ice mass and energy balance using either a multilayer scheme or a
bulk-layering scheme using separate layers for new snow, old snow, firn and iceModification of the meteorological variables for inside-canopy conditions in forested areas and
calculation of forest snow processes (interception, sublimation and melt unload)Calculation of snowmelt using the surface energy balance or a temperature index/enhanced
temperature index methodCalculation of evapotranspiration for snow-free surfaces using the FAO Penman-Monteith methodUsage of arbitrary timesteps (e.g. 10 minutes, daily) while resampling forcing data to the
desired time resolution if necessaryFlexible output of time series including arbitrary model variables for selected point locations in
NetCDF or CSV formatFlexible output of gridded model variables, either for specific dates or periodically (e.g., daily
or monthly), optionally aggregated to averages or sums in NetCDF, GeoTIFF or ASCII Grid formatLive view window for displaying the model state in real timeQuick startInstallationopenAMUNDSEN is a Python (3.8+) package and compatible with all major platforms (Linux, macOS,
Windows) and architectures.To help keep its dependencies separated from other Python packages installed on your system, we
recommend to install it either from within a conda environment (if you are using thecondapackage manager) or a standard Pythonvirtual
environment.Using condaWhen using conda, the recommended steps to install openAMUNDSEN are:InstallMiniconda(recommended) orAnacondaby downloading and executing
the installer for your operating system and architecture.From the terminal, create a conda environment for openAMUNDSEN by runningconda create --name openamundsenActivate the environment by runningconda activate openamundsenInstall openAMUNDSEN by runningconda install --channel=conda-forge openamundsenUsing virtualenvIf you want to install openAMUNDSEN in a virtual environment instead:Create a virtualenv in the current working directory by runningpython3 -m venv openamundsenActivate the environment by runningsource openamundsen/bin/activateInstall openAMUNDSEN by runningpip install openamundsenExamplesExample data sets for running the model can be downloaded fromhttps://github.com/openamundsen/openamundsen-examples.Setting up a model runInput dataRequired input data for running the model is at the least:a digital elevation model (DEM) as anArc/Info ASCII
Grid(.asc) file in a projected coordinate reference
system, with the same spatial resolution in which the model should be run,and time series of the meteorological variables air temperature, precipitation, relative humidity,
global radiation and wind speed in NetCDF or CSV format.Optionally, a region of interest (ROI) file can be additionally supplied defining a subset of the
DEM area in which the model should be applied.
All model calculations are then only performed for the pixels which are marked as 1 in the ROI file.Spatial input dataThe DEM file must be nameddem_{domain}_{resolution}.asc, where{domain}refers to the (freely
selectable) name of the respective model domain, and{resolution}to the spatial resolution in m.
Accordingly, the ROI file (if available) is namedroi_{domain}_{resolution}.asc.Meteorological input dataMeteorological input time series must be provided in the same or higher temporal resolution in which
the model should be run.
For each point location, a CSV or NetCDF file covering the entire time series must be provided.CSV inputWhen using CSV as input format, the input files should have one or more of the following columns
(columns for variables not available can be omitted):date: timestamp as apd.to_datetime-compatible
string (e.g.YYYY-MM-DD HH:MM)temp: air temperature (K)precip: precipitation sum (kg m-2)rel_hum: relative humidity (%)sw_in: global radiation (W m-2)wind_speed: wind speed (m s-1)Additionally, astations.csvfile containing the metadata of the point locations must be provided
containing the following columns:id: station ID, corresponding to the filename of the respective data filename: station namex: longitude or projected x coordinatey: latitude or projected y coordinatealt: altitude (m)NetCDF inputWhen using NetCDF as input format, for each station a NetCDF file containing the meteorological time
series and the station metadata is read in (i.e., no additional metadata file is required in this
case).
The NetCDF files are expected to conform to the following schema (unavailable variables can be
omitted):netcdf dummy {
dimensions:
        time = UNLIMITED ;
variables:
        double alt ;
                alt:_FillValue = NaN ;
                alt:standard_name = "surface_altitude" ;
                alt:units = "m" ;
        float hurs(time) ;
                hurs:_FillValue = NaNf ;
                hurs:standard_name = "relative_humidity" ;
                hurs:units = "%" ;
        double lat ;
                lat:_FillValue = NaN ;
                lat:standard_name = "latitude" ;
                lat:units = "degree_north" ;
        double lon ;
                lon:_FillValue = NaN ;
                lon:standard_name = "longitude" ;
                lon:units = "degree_east" ;
        float pr(time) ;
                pr:_FillValue = NaNf ;
                pr:standard_name = "precipitation_flux" ;
                pr:units = "kg m-2 s-1" ;
        float rsds(time) ;
                rsds:_FillValue = NaNf ;
                rsds:standard_name = "surface_downwelling_shortwave_flux_in_air" ;
                rsds:units = "W m-2" ;
        float tas(time) ;
                tas:_FillValue = NaNf ;
                tas:standard_name = "air_temperature" ;
                tas:units = "K" ;
        int64 time(time) ;
                time:standard_name = "time" ;
                time:units = "hours since 1999-01-01 00:00:00" ;
                time:calendar = "proleptic_gregorian" ;
        float wss(time) ;
                wss:_FillValue = NaNf ;
                wss:standard_name = "wind_speed" ;
                wss:units = "m s-1" ;

// global attributes:
                :Conventions = "CF-1.6" ;
                :station_name = "dummy" ;
}ConfigurationThe configuration of an openAMUNDSEN model run can either be read in from aYAMLfile or be passed directly as a dictionary from within
Python.This is an example of a YAML configuration file:domain:rofental# name of the model domain (corresponding to the domain part of the spatial input data filenames)start_date:"2020-10-01"end_date:"2021-03-31"resolution:50# spatial resolution (m)timestep:H# temporal resolution as a pandas-compatible frequency string (e.g., "H", "3H", "D")crs:"epsg:32632"# CRS of the input gridstimezone:1# timezone of the model domain (difference to UTC in h)results_dir:results# directory for storing the model outputs# Input data configurationinput_data:grids:dir:input/grid# location of the input grids (DEM, ROI etc.)meteo:dir:input/meteo# location of the meteorological input dataformat:csv# input format (CSV or NetCDF)crs:"epsg:4326"# CRS of the station coordinates (when using CSV)# Output data configurationoutput_data:# Time series (point) outputs configurationtimeseries:# List of points to be writtenpoints:-x:642579# x coordinate in the domain CRSy:5193069# y coordinate in the domain CRSname:testpoint# point name (optional)add_default_variables:true# write default point output variablesvariables:# optional additional output variables not written by default-var:surface.turbulent_exchange_coeff# Configuration for gridded outputsgrids:format:netcdf# "netcdf", "ascii", "geotiff" or "memory"variables:-var:meteo.precip# internal variable namename:precip_month# NetCDF output variable namefreq:M# write frequency (if not specified, write every timestep)agg:sum# aggregation function ("sum", "mean" or empty)-var:snow.meltfreq:Magg:sum-var:snow.swefreq:Dmeteo:# Spatial interpolation parametersinterpolation:temperature:trend_method:fixed# use fixed monthly temperature lapse ratesprecipitation:trend_method:fractional# use fixed monthly fractional precipitation gradientslapse_rate:# (m-1)-0.00048# J-0.00046# F-0.00041# M-0.00033# A-0.00028# M-0.00025# J-0.00024# J-0.00025# A-0.00028# S-0.00033# O-0.00041# N-0.00046# Dhumidity:trend_method:fixed# use fixed monthly dew point temperature lapse rates# Precipitation phase determination parametersprecipitation_phase:method:wet_bulb_temp# use wet-bulb temperature for precipitation phase determinationthreshold_temp:273.65# threshold temperature (K) in which 50% of precipitation falls as snowtemp_range:1.# temperature range in which mixed precipitation can occur# Parameters for adjusting precipitation for wind-induced undercatch and snow redistributionprecipitation_correction:-method:wmogauge:hellmannsnow:model:multilayer# snow scheme ("multilayer" or "cryolayers")# Number of layers and minimum thicknesses (m) when using the multilayer modelmin_thickness:-0.1-0.2-0.4albedo:min:0.55# minimum snow albedomax:0.85# maximum snow albedocold_snow_decay_timescale:480# albedo decay timescale for cold (T < 0 °C) snow (h)melting_snow_decay_timescale:200# albedo decay timescale for melting snow (h)refresh_snowfall:0.5# snowfall amount for resetting albedo to the maximum value (kg m-2 h-1)Only few configuration parameters (domain,start_date,end_date,resolution,timezoneand
the input data directories) are mandatory, for all other parameters default values are used
otherwise.
A detailed documentation of all model parameters will be available soon (in
the meantime, the available parameters and their default values can be looked up inconfigschema.yml).Running the modelWhen the input data and the model configuration have been prepared, a model run can be started either
using theopenamundsencommand line utility (openamundsen config_file.yml), or from within
Python using the following syntax:importopenamundsenasoaconfig=oa.read_config('config_file.yml')# read in configuration filemodel=oa.OpenAmundsen(config)# create OpenAmundsen object and populate unspecified parameters with default valuesmodel.initialize()# read in input data files, initialize state variables etc.model.run()# run the model