tartes package — tartes documentation

# tartes package

This module provides several functions to compute optical properties of a given snowpack using the TARTES model. The most convenient functions are `albedo()`, `absorption_profile()` and `irradiance_profiles()` to compute respectively the albedo, the profile of absorbed energy and the irradiance profile within the snowpack. These functions are wrapper around the polyvalent function `tartes()` that performs the computation. The latter function should be used only when a combinaison of albedo, profile of absorbed energy and/or profile of irradiance is needed.

## Module contents

`tartes.` `albedo`(wavelength, SSA, density=None, thickness=None, g0=0.86, B0=1.6, y0=0.728, W0=0.0611, impurities=0, impurities_type=<class 'tartes.impurities.Soot'>, soilalbedo=0.0, dir_frac=0, theta_inc=0, refrac_index='w2008')

  compute the spectral albedo of a snowpack specified by the profiles of SSA and density using TARTES. The underlying interface has an albedo specified by soilalbedo (0.0 by default). For semi-infinite snowpack, use thickness = None (the default value).

  Parameters: | wavelength (array) – wavelength (m) SSA (array) – surface specific area (m^2/kg) for each layer density (array) – density (kg/m^3) thickness (array) – thickness of each layer (m). By default is None meaning a semi-infinite medium. g0 (array or scalar) – asymmetry parameter of snow grains at nr=1.3 and at non absorbing wavelengths (no unit). The default value is 0.86. g0 can be scalar (constant in the snowpack) or an array like the SSA. B0 (array or scalar) – absorption enhancement parameter of snow grains at nr=1.3 and at non absorbing wavelengths (no unit). The default value is 1.6, taken from Libois et al. 2014. B0 can be scalar (constant in the snowpack) or an array like the SSA. y0 (array or scalar) – Value of y of snow grains at nr=1.3 (no unit). See Eqs 72 and 75 in the “science” doc for the default value. y0 can be scalar (same for all layers) or an array like the SSA. W0 (array or scalar) – Value of W of snow grains at nr=1.3 (no unit). See Eqs 72 and 75 in the “science” doc for the default value. W0 can be a scalar (same for all layers) or an array like the SSA. impurities (array or scalar) – impurities concentration (kg/kg) in each layer. It is either a constant or an array with size equal to the number of layers. The array is 1-d if only one type of impurities is used and 2-d otherwise. impurities_type (object or list of object) – specify the type of impurities. By defaut it is “soot”. Otherwise it should be a class (or an instance) that defines the density and the imaginary part of the refractive index like the Soot class (see tartes.impurities for possible choices and to add new impurities types). It can also be a list of classes if several types of impurities are present in the snowpack. In this case, the impurities parameter must be a 2-d array. soilalbedo (scalar or array) – spectral albedo of the underlying layer (no unit). soilalbedo can be a scalar or an array like wavelength. dir_frac (array) – fraction of directional flux over the total flux (teh default is dir_frac = 0 meaning 100% diffuse incident flux) theta_inc (scalar) – incident angle of direct light (degree, 0 means nadir) refrac_index (tuple of two arrays) – real and imaginary parts of the refractive index for each wavelength or a string refering to Warren’s paper (“w2008” the default or “w1995”)
  Returns: | spectral albedo for each wavelength

`tartes.` `ssa`(r_opt)

  return the specific surface area (SSA) from optical radius

  Parameters: | r_opt (scalar or array) – optical radius (m)
  Returns: | SSA in m^2/kg

`tartes.` `absorption_profile`(wavelength, SSA, density=None, thickness=None, g0=0.86, B0=1.6, y0=0.728, W0=0.0611, impurities=0, impurities_type=<class 'tartes.impurities.Soot'>, soilalbedo=0.0, dir_frac=0.0, totflux=1.0, theta_inc=0, refrac_index='w2008')

  compute the energy absorbed in every layer and in the soil. The parameters are the same as for the albedo function. If both the albedo and the absorption_profile is needed, a direct call to the tartes function is recommended.

  Parameters: | wavelength (array) – wavelength (m) SSA (array) – surface specific area (m^2/kg) for each layer density (array) – density (kg/m^3) thickness (array) – thickness of each layer (m). By default is None meaning a semi-infinite medium. g0 (array or scalar) – asymmetry parameter of snow grains at nr=1.3 and at non absorbing wavelengths (no unit). The default value is 0.86. g0 can be scalar (constant in the snowpack) or an array like the SSA. B0 (array or scalar) – absorption enhancement parameter of snow grains at nr=1.3 and at non absorbing wavelengths (no unit). The default value is 1.6, taken from Libois et al. 2014. B0 can be scalar (constant in the snowpack) or an array like the SSA. y0 (array or scalar) – Value of y of snow grains at nr=1.3 (no unit). See Eqs 72 and 75 in the “science” doc for the default value. y0 can be scalar (same for all layers) or an array like the SSA. W0 (array or scalar) – Value of W of snow grains at nr=1.3 (no unit). See Eqs 72 and 75 in the “science” doc for the default value. W0 can be a scalar (same for all layers) or an array like the SSA. impurities (array or scalar) – impurities concentration (kg/kg) in each layer. It is either a constant or an array with size equal to the number of layers. The array is 1-d if only one type of impurities is used and 2-d otherwise. impurities_type (object or list of object) – specify the type of impurity. By defaut it is “soot”. Otherwise it should be a class (or an instance) defining the density and the imaginary part of the refractive index like the Soot class (see tartes.impurities for possible choices and to add new impurities types). It can also be a list of classes if several impurities type are present in the snowpack. In this case, the impurities parameter must be a 2-d array. soilalbedo (scalar or array) – spectral albedo of the underlying (no unit). albedo can be a scalar or an array like wavelength. dir_frac (array) – fraction of directional flux over the total flux (teh default is dir_frac = 0 meaning 100% diffuse incident flux) totflux (array) – total spectral incident flux (direct+diffuse) (W/m^2) theta_inc (scalar) – incident angle of direct light (degree, 0 means nadir) refrac_index (tuple of two arrays) – real and imaginary parts of the refractive index for each wavelength or a string refering to Warren’s paper (“w2008” the default or “w1995”)
  Returns: | spectral absorption in every layer and in the soil. The return type is an array with the first dimension for the wavelength and the second for the layers + an extra value for the soil. If the wavelength is a scalar, the first dimension is squeezed.

`tartes.` `irradiance_profiles`(wavelength, z, SSA, density=None, thickness=None, g0=0.86, B0=1.6, y0=0.728, W0=0.0611, impurities=0, impurities_type=<class 'tartes.impurities.Soot'>, soilalbedo=0.0, dir_frac=0, totflux=1.0, theta_inc=0, refrac_index='w2008')

  compute the upwelling and downwelling irradiance at every depth z. The parameters are the same as for the absorption_profile function plus the depths z. If both the albedo and the absorption_profile is needed, a direct call to the tartes function is recommended.

  Parameters: | wavelength (array) – wavelength (m) z (array) – depths at which the irradiance are calculated (m) SSA (array) – surface specific area (m^2/kg) for each layer density (array) – density (kg/m^3) thickness (array) – thickness of each layer (m). By default is None meaning a semi-infinite medium. g0 (array or scalar) – asymmetry parameter of snow grains at nr=1.3 and at non absorbing wavelengths (no unit). The default value is 0.86. g0 can be scalar (constant in the snowpack) or an array like the SSA. B0 (array or scalar) – absorption enhancement parameter of snow grains at nr=1.3 and at non absorbing wavelengths (no unit). The default value is 1.6, taken from Libois et al. 2014. B0 can be scalar (constant in the snowpack) or an array like the SSA. y0 (array or scalar) – Value of y of snow grains at nr=1.3 (no unit). See Eqs 72 and 75 in the “science” doc for the default value. y0 can be scalar (same for all layers) or an array like the SSA. W0 (array or scalar) – Value of W of snow grains at nr=1.3 (no unit). See Eqs 72 and 75 in the “science” doc for the default value. W0 can be a scalar (same for all layers) or an array like the SSA. impurities (array or scalar) – impurities concentration (kg/kg) in each layer. It is either a constant or an array with size equal to the number of layers. The array is 1-d if only one type of impurities is used and 2-d otherwise. impurities_type (object or list of object) – specify the type of impurity. By defaut it is “soot”. Otherwise it should be a class (or an instance) defining the density and the imaginary part of the refractive index like the Soot class (see tartes.impurities for possible choices and to add new impurities types). It can also be a list of classes if several impurities type are present in the snowpack. In this case, the impurities parameter must be a 2-d array. soilalbedo (scalar or array) – spectral albedo of the underlying (no unit). soilalbedo can be a scalar or an array like wavelength. dir_frac (array) – fraction of directional flux over the total flux (the default is dir_frac = 0 meaning 100% diffuse incident flux) at every wavelength totflux (array) – total spectral incident flux (direct+diffuse) (W/m^2) theta_inc (scalar) – incident angle of direct light (degree, 0 means nadir) refrac_index (tuple of two arrays) – real and imaginary parts of the refractive index for each wavelength or a string refering to Warren’s paper (“w2008” the default or “w1995”)
  Returns: | a tupple with downwelling and upwelling irradiance profiles. The return type is an array with the first dimension for the wavelength and the second for the layers. If the wavelength argument is a scalar, the first dimension is squeezed.

`tartes.` `actinic_profile`(wavelength, z, SSA, density=None, thickness=None, g0=0.86, B0=1.6, y0=0.728, W0=0.0611, impurities=0, impurities_type=<class 'tartes.impurities.Soot'>, soilalbedo=0.0, dir_frac=0, totflux=1.0, theta_inc=0, refrac_index=None)

  compute the actinic flux at every depth z. The parameters are the same as for the irradiance profile.

  Parameters: | wavelength (array) – wavelength (m) z (array) – depths at which the irradiance are calculated (m) SSA (array) – surface specific area (m^2/kg) for each layer density (array) – density (kg/m^3) thickness (array) – thickness of each layer (m). By default is None meaning a semi-infinite medium. g0 (array or scalar) – asymmetry parameter of snow grains at nr=1.3 and at non absorbing wavelengths (no unit). The default value is 0.86. g0 can be scalar (constant in the snowpack) or an array like the SSA. B0 (array or scalar) – absorption enhancement parameter of snow grains at nr=1.3 and at non absorbing wavelengths (no unit). The default value is 1.6, taken from Libois et al. 2014. B0 can be scalar (constant in the snowpack) or an array like the SSA. y0 (array or scalar) – Value of y of snow grains at nr=1.3 (no unit). See Eqs 72 and 75 in the “science” doc for the default value. y0 can be scalar (same for all layers) or an array like the SSA. W0 (array or scalar) – Value of W of snow grains at nr=1.3 (no unit). See Eqs 72 and 75 in the “science” doc for the default value. W0 can be a scalar (same for all layers) or an array like the SSA. impurities (array or scalar) – impurities concentration (kg/kg) in each layer. It is either a constant or an array with size equal to the number of layers. The array is 1-d if only one type of impurities is used and 2-d otherwise. impurities_type (object or list of object) – specify the type of impurity. By defaut it is “soot”. Otherwise it should be a class (or an instance) defining the density and the imaginary part of the refractive index like the Soot class (see tartes.impurities for possible choices and to add new impurities types). It can also be a list of classes if several impurities type are present in the snowpack. In this case, the impurities parameter must be a 2-d array. soilalbedo (scalar or array) – spectral albedo of the underlying (no unit). soilalbedo can be a scalar or an array like wavelength. dir_frac (array) – fraction of directional flux over the total flux (the default is dir_frac = 0 meaning 100% diffuse incident flux) at every wavelength totflux (array) – total spectral incident flux (direct+diffuse) (W/m^2) theta_inc (scalar) – incident angle of direct light (degree, 0 means nadir) refrac_index (tuple of two arrays) – real and imaginary parts of the refractive index for each wavelength or a string refering to Warren’s paper (“w2008” the default or “w1995”)
  Returns: | the actinic flux profile. The return type is an array with the first dimension for the wavelength and the second for the layers. If the wavelength argument is a scalar, the first dimension is squeezed.

`tartes.` `tartes`(wavelength, SSA, density, thickness=None, g0=0.86, B0=1.6, y0=0.728, W0=0.0611, impurities=0, impurities_type=<class 'tartes.impurities.Soot'>, soilalbedo=0.0, dir_frac=0.0, totflux=1.0, mudir=0, compute_absorption=False, compute_irradiance_profiles=False, compute_actinic_profile=False, z=None, refrac_index=None)

  compute spectral albedo, and optionally the absorption in each layer and in the soil, the downwelling and upwelling irradiance profiles and the actinic flux from the physical properties of the snowpack and the incidence flux conditions.

  Parameters: | wavelength (array or scalar) – wavelength (m) SSA (array or scalar) – snow specific surface area (m^2/kg) density (array or scalar) – snow density (kg/m^3) thickness (array or scalar) – thickness of the layers (m) g0 (array or scalar) – asymmetry parameter of snow grains at nr=1.3 and at non absorbing wavelengths (no unit). The default value is 0.86. g0 can be scalar (constant in the snowpack) or an array like the SSA. B0 (array or scalar) – absorption enhancement parameter of snow grains at nr=1.3 and at non absorbing wavelengths (no unit). The default value is 1.6, taken from Libois et al. 2014. B0 can be scalar (constant in the snowpack) or an array like the SSA. y0 (array or scalar) – Value of y of snow grains at nr=1.3 (no unit). See Eqs 72 and 75 in the “science” doc for the default value. y0 can be scalar (same for all layers) or an array like the SSA. W0 (array or scalar) – Value of W of snow grains at nr=1.3 (no unit). See Eqs 72 and 75 in the “science” doc for the default value. W0 can be a scalar (same for all layers) or an array like the SSA. impurities (array or scalar) – impurities concentration (g/g/) in each layer. It is either a constant or an array with size equal to the number of layers. The array is 1-d if only one type of impurities is used and 2-d otherwise. impurities_type (object or list of object) – specify the type of impurity. By defaut it is “soot”. Otherwise it should be a class (or an instance) defining the density and the imaginary part of the refractive index like the Soot class (see tartes.impurities for possible choices and to add new impurities types). It can also be a list of classes if several impurities type are present in the snowpack. In this case, the impurities parameter must be a 2-d array. soilalbedo (scalar or array) – albedo of the bottom layer (no unit). soilalbedo can be a scalar or an array like wavelength. dir_frac (array) – fraction of directional flux over the total flux (the default is dir_frac = 0 meaning 100% diffuse incident flux) at every wavelength totflux (array) – total spectral incident flux (direct+diffuse) (W/m^2) mudir (scalar) – cosine of the incident angle of direct light compute_absorption (boolean) – if True compute the absorption profile and the absorption in the soil compute_irradiance_profiles (boolean) – if True compute the profiles of up- and down-welling irradiance at depths z compute_actinic_profile (boolean) – if True compute the profile of actinic flux at depths z z (array) – depth at which the irradiance is calculed. It is used only if compute_irradiance_profile is activated. refrac_index (tuple of two arrays) – real and imaginary parts of the refractive index for each wavelength
  Returns: | spectral albedo, and optionaly absorption by layer (note the bottom layer correspond to the absorption by the soil) and optionnaly the profile of irradiance: downwelling, upwelling