Backend

Submodules

Constants module

In: scintillometry.backend.constants.py

Defines classes and functions for determining constants.

class scintillometry.backend.constants.AtmosConstants

Bases: object

Atmospheric constants.

There seems to be a contradiction between the values for \(\alpha_{11}\) in the Scintillometer Theory Manual 1.05 (Chapter 1.1.5)[11], and the BLS Manual 1.49 (A.2 Eq.6)[12]. The Scintillometer Theory Manual is more recent.

alpha11

\(C_{n}^{2}\) measurement coefficients \(\alpha_{11}\) for each BLS type, [m ^7/3].

Type:

dict

alpha12

\(C_{n}^{2}\) measurement coefficients \(\alpha_{12}\) for each BLS type.

Type:

dict

lamda

BLS wavelength, \(\lambda\) [nm].

Type:

float

lamda_error

BLS wavelength error, [nm].

Type:

float

at_opt

\(A_{T}\) coefficient for 880 nm & typical atmospheric conditions, from Ward et al. (2013).[14]

Type:

float

aq_opt

\(A_{q}\) coefficient for 880 nm & typical atmospheric conditions, Ward et al. (2013).[14]

Type:

float

most_coeffs_ft

Coefficients for MOST functions \(f_{C_{T}^{2}}\), in format: [(unstable 01, unstable 02), (stable 01, stable 02)]

Type:

dict[list[tuple, tuple]]

cp

Specific heat capacity of air at constant pressure, \(c_{p}\) [J \(\cdot\) K ^-1 kg ^-1].

Type:

float

dalr

Dry adiabatic lapse rate \(\Gamma_{d}\) [Km ^-1]. The lapse rate is positive.

Type:

float

g

Gravitational acceleration [ms ^-2].

Type:

float

k

von Kármán’s constant.

Type:

float

kelvin

0°C in kelvins.

Type:

float

latent_vapour

Latent heat of vapourisation at 20°C [J \(\cdot\) kg ^-1].

Type:

float

r_dry

Specific gas constant for dry air, \(R_{dry}\) [J \(\cdot\) K ^-1 kg ^-1].

Type:

float

r_vapour

Specific gas constant for water vapour, \(R_{v}\) [J \(\cdot\) K ^-1 kg ^-1].

Type:

float

ratio_rmm

Ratio of molecular masses of water vapour and dry air i.e. ratio of gas constants \(\epsilon\).

Type:

float

ref_pressure

Reference pressure (not SLP), \(P_{b}\) [Pa].

Type:

int

rho

Density of air at STP, \(\rho\) [kg \(\cdot\) m ^-3].

Type:

float

convert_pressure(pressure, base=True)

Converts pressure data to pascals [Pa] or hectopascals [hPa].

The input dataframe or series is copied, as this function may be called before the processing of the original data has finished.

This method handles 0 and NaN values, but only converts correctly for pressure values in these intervals:

• \(P\) [bar] < 2 bar

• 2 hPa < \(P\) [hPa] < 2000 hPa

• \(P\) [Pa] > 2000 Pa

This method should therefore only be used on pre-processed data as a convenience. By default, converts to pascals.

Parameters:

• pressure (Union[pd.DataFrame, pd.Series]) – Pressure measurements \(P\) in pascals [Pa], hectopascals [hPa], or bars [bar].

• base (bool) – If True, converts to pascals [Pa]. Otherwise, converts to hectopascals [hPa]. Default True.

Returns:

Pressure measurements \(P\) in either pascals [Pa] or hectopascals [hPa].

Return type:

Union[pd.DataFrame, pd.Series]

convert_temperature(temperature, base=True)

Converts temperature to Celsius [°C] or kelvins [K].

The input dataframe or series is copied, as this function may be called before the processing of the original data has finished.

This method handles 0 and NaN values, but only converts correctly for temperature values in these intervals:

• T [K] > 130 K

• T [°C] < 130 °C

This method should therefore only be used on pre-processed data as a convenience. By default, converts to kelvins.

Parameters:

• temperature (Union[pd.DataFrame, pd.Series]) – Temperature measurements \(T\) in kelvins [K] or Celsius [°C].

• base (bool) – If True, converts to kelvins [K]. Otherwise, converts to Celsius [°C]. Default True.

Returns:

Temperature measurements \(T\) in either kelvins [K] or Celsius [°C].

Return type:

Union[pd.DataFrame, pd.Series]

get(constant_name: str)

overwrite(constant_name: str, value: float)

Transects module

In: scintillometry.backend.transects.py

Calculates path weighting and effective height from a path transect.

class scintillometry.backend.transects.TransectParameters

Bases: object

Computes path heights from transect data and stability.

transform

Inherited methods for applying mathematical transformations to topographical data.

Type:

TransectTransform

get_all_path_heights(path_transect)

Calculates effective & mean path heights in all conditions.

Parameters:

path_transect (pd.DataFrame) – Parsed path transect data.

Returns:

Effective and mean path heights of transect \(z_{eff}\) and \(\bar{z}\) [m], with each stability condition as key.

Return type:

dict[str, tuple[np.floating, np.floating]]

get_b_value(stability_name)

Gets b-value for an implemented stability condition.

Parameters:

stability_name (str) – Name of stability condition.

Returns:

Constant “b” accounting for height dependence of

\(C_{n}^{2}\). Values of “b” are from Hartogensis et al. (2003)[3], and Kleissl et al. (2008)[4].

Return type:

float

Raises:

NotImplementedError – <stability_name> is not an implemented stability condition.

get_effective_path_height(path_heights, path_positions, stability)

Computes effective path height for a path transect.

Calculates the effective path height across the entire scintillometer beam path, using the actual path heights and normalised positions.

Parameters:

• path_heights (pd.Series) – Actual path heights, \(z\) [m].

• path_positions (pd.Series) – Normalised positions along transect.

• stability (str) – Stability conditions. Can be stable, unstable, or None for no height dependency.

Returns:

Effective path height, \(z_{eff}\) [m].

Return type:

np.floating

get_path_heights(transect_data, stability_condition)

Calculates effective and mean path height for a transect.

Parameters:

• transect_data (pd.DataFrame) – Parsed path transect data.

• stability_condition (str) – Stability conditions.

Returns:

Effective and mean path height of transect, \(z_{eff}\) and \(\bar{z}\) [m].

Return type:

tuple[np.floating, np.floating]

print_path_heights(z_eff, z_mean, stability)

Prints effective and mean path height for specific stability.

Parameters:

• z_eff (np.floating) – Effective path height of transect, \(z_{eff}\) [m].

• z_mean (np.floating) – Mean effective path height of transect, \(\bar{z}\) [m].

• stability (str) – Stability conditions. Can be stable, unstable, or None for no height dependency.

class scintillometry.backend.transects.TransectTransform

Bases: object

Applies mathematical transformations to topographical data.

bessel_second(x)

Calculates the Bessel function for a specific path position.

Parameters:

x (float) – Normalised path position.

Returns:

Bessel function of path position.

Return type:

float

path_weighting(path_coordinates)

Path weighting function for computing effective path height.

Parameters:

path_coordinates (pd.Series) – Normalised path position along path transect.

Returns:

Contains weights for each coordinate along the path.

Return type:

list

Derivations module

In: scintillometry.backend.derivations.py

Derives heat fluxes.

class scintillometry.backend.derivations.DeriveScintillometer

Bases: object

Derives structure parameters and fluxes from scintillometer.

constants

Inherited atmospheric constants.

Type:

AtmosConstants

compute_fluxes(input_data, effective_height, beam_params=None)

Compute kinematic and surface sensible heat fluxes.

The surface sensible heat flux \(H_{free}\) is calculated under free convection (little wind shear, high instability).

Parameters:

• input_data (pd.DataFrame) – Parsed and localised scintillometry and weather data. This must contain at least \(C_{n}^{2}\), temperature, and pressure.

• effective_height (np.floating) – Effective path height, \(z_{eff}\) [m].

• beam_params (tuple[int, int]) – Wavelength and wavelength error interval in nanometres. For BLS this is typically (880, 20). Default None.

Returns:

Updated dataframe containing derived values for \(C_{T}^{2}\), [K \(^{2}\cdot\) m \(^{-2/3}\)].

Return type:

pd.DataFrame

derive_ct2(dataframe, wavelength=880)

Derives the structure parameter of temperature, \(C_{T}^{2}\).

Derives \(C_{T}^{2}\) from measured structure parameter of refractive index \(C_{n}^{2}\) and weather data. The equation to derive \(C_{T}^{2}\) is precise to 10 ^-5 but doesn’t account for humidity fluctuations: errors are within 3% of inverse Bowen ratio (Moene 2003).[8]

Typical transmission beam wavelengths:

* Ward et al., (2013) [#ward2013]_, Scintillometer Theory
Manual [#scintec2022]_: 880 nm
* BLS Manual [#scintec2008]_: 850 nm (± 20 nm)
* SLS Manual: 670 nm (± 10 nm)

See specifications in the corresponding hardware maintenance manual.

Parameters:

• dataframe (pd.DataFrame) – Parsed and localised data, containing at least \(C_{n}^{2}\), temperature, and pressure.

• wavelength (int) – Wavelength of transmitter beam, in nanometres. Default 880 nm.

Returns:

Input dataframe with updated values for the structure parameter of temperature, \(C_{T}^{2}\) [K \(^{2}\cdot\) m \(^{-2/3}\)].

Return type:

pd.DataFrame

free_convection_shf(dataframe)

Calculates surface sensible heat flux under free convection.

Parameters:

dataframe (pd.DataFrame) – Must contain at least kinematic sensible heat flux, pressure, and temperature data.

Returns:

Dataframe with new columns for air density and surface sensible heat flux under free convection, \(H_{free}\) [W \(\cdot\) m ^-2].

Return type:

pd.DataFrame

kinematic_shf(dataframe, z_eff)

Calculates kinematic sensible heat fluxes.

Parameters:

• dataframe (pd.DataFrame) – Must contain at least \(C_{T}^{2}\) and temperature data.

• z_eff (float) – Effective path height, \(z_{eff}\) [m].

Returns:

Dataframe with new column for kinematic sensible heat flux \(Q_{0}\) [K \(\cdot\) ms ^-1].

Return type:

pd.DataFrame

Constructions module

In: scintillometry.backend.constructions.py

Constructs profiles from vertical measurements.

These definitions avoid confusion with interchangeable terms:

• Elevation: Vertical distance between mean sea-level and station.

• Height: Vertical distance between station elevation and measurement point.

• Altitude: Vertical distance between mean sea-level and measurement point.

Functions are written for performance. More legible versions are included as inline comments, and are used for tests.

class scintillometry.backend.constructions.ProfileConstructor

Bases: object

Constructs vertical profiles.

constants

Inherited atmospheric constants.

Type:

AtmosConstants

extrapolate_air_pressure(surface_pressure, temperature)

Extrapolates reference pressure measurements to scan levels.

Input series and dataframe do not need matching indices. Data for <surface_pressure> (1D time series) is mapped to the index and columns of <temperature> (2D time series), i.e. no interpolation occurs.

Parameters:

• surface_pressure (pd.Series) – Air pressure measurements at reference measurement height, \(P_{0}\) [Pa].

• temperature (pd.DataFrame) – Vertical measurements, air temperature at target heights, \(T\) [K].

Returns:

Derived vertical measurements for pressure, \(P\) [Pa].

Return type:

pd.DataFrame

extrapolate_column(dataframe, gradient)

Extrapolates measurements from reference column.

Applies gradient to the first column of a dataframe to produce data for the remaining columns.

Parameters:

• dataframe (pd.DataFrame) – Numeric data with integer column labels.

• gradient (pd.DataFrame or float) – Either a gradient or dataframe of gradients.

Returns:

Extrapolated measurements. The first column remains unchanged.

Return type:

pd.DataFrame

get_air_pressure(pressure, air_temperature, z_target, z_ref=0)

Derive air pressure at specific height.

Uses hypsometric equation. By default, heights are relative to the station elevation, i.e. <z_target> - <z_ref> = <z_target>, <z_ref> = 0.

\[P_{{z}} = P_{{0}} \cdot \exp{{ \left ( \frac{{-g}}{{\mathfrak{{R}}_{{d}}}} \frac{{\Delta z}}{{T_{{z}}}} \right ) }}\]

Parameters:

• pressure (pd.Series) – Air pressure at reference measurement height, \(P_{0}\) [Pa].

• air_temperature (pd.Series) – Air temperatures at target measurement height, \(T_{z}\) [K].

• z_target (int) – Target measurement height, \(z\) [m].

• z_ref (int) – Reference measurement height, \(z_{0}\) [m]. Default 0.

Returns:

Air pressure at target heights, \(P_{z}\) [Pa].

Return type:

pd.Series

get_bulk_richardson(potential_temperature, meteo_data)

Calculate bulk Richardson number.

As there are no vertical wind observations available to calculate \(\Delta\) \(u\), it is assumed mean wind speed vanishes at surface. This severely limits its accuracy for representing dynamic stability.

\[Ri_{{b}} = \frac{{g}}{{\bar{{\theta}}}} \frac{{\Delta \theta \Delta z}}{{(\Delta u)^{{2}}}}\]

Parameters:

• potential_temperature (pd.DataFrame) – Vertical measurements, potential temperature \(\theta\) [K].

• meteo_data (pd.DataFrame) – Meteorological data.

get_environmental_lapse_rate(temperature)

Computes environmental lapse rate.

Lapse rate is inversely proportional to the temperature gradient.

Parameters:

temperature (pd.DataFrame) – Vertical measurements, temperature, \(T\) [K].

Returns:

Derived vertical measurements for environmental lapse rate, \(\Gamma_{e}\) [Km ^-1]. Values for the last column are all NaN.

Return type:

pd.DataFrame

get_gradient(data, method='backward')

Computes spatial gradient of a set of vertical measurements.

Calculates \(\partial y/\partial x\) at each value of independent variable x for each time step t(n): e.g. an input dataframe of temperatures \(T\) for heights \(z\) with time index t, returns a dataframe of \(\partial T/\partial z\) for heights \(z\) with time index t.

By default, the gradient is calculated using a 1-D centred-differencing scheme for non-uniform meshes, since vertical measurements are rarely made at uniform intervals.

Parameters:

• data (pd.DataFrame) – Vertical measurements for a single variable.

• method (str) – Finite differencing method. Supports “uneven” for centred-differencing over a non-uniform mesh, and “backward” for backward-differencing. Default “backward”.

Returns:

Derived spatial gradients \(\partial y/\partial x\) for each value x at each time step.

Return type:

pd.DataFrame

Raises:

NotImplementedError – ‘<method>’ is not an implemented differencing scheme. Use ‘uneven’ or ‘backward’.

get_lapse_rates(temperature, mixing_ratio)

Calculate lapse rates.

Lapse rates are inversely proportional to the temperature gradient:

\[\Gamma = -\frac{{\delta T}}{{\delta z}}\]

Parameters:

• temperature (pd.DataFrame) – Vertical measurements, temperature, \(T\) [K].

• mixing_ratio (pd.DataFrame) – Vertical measurements, mixing ratio, \(r\) [kg \(\cdot\) kg ^-1].

Returns:

Derived vertical measurements for the environmental and moist adiabatic lapse rates, \(\Gamma_{e}\) and \(\Gamma_{w}\) [Km ^-1].

Return type:

dict[str, pd.DataFrame]

get_mixing_ratio(wv_pressure, d_pressure)

Calculate mixing ratio for dry air pressure.

\[r = \frac{{\mathfrak{{R}}_{{d}}}}{{\mathfrak{{R}}_{{v}}}} \frac{{e}}{{P_{{dry}}}}\]

Parameters:

• wv_pressure (pd.DataFrame) – Vertical measurements, water vapour pressure, \(e\) [Pa].

• d_pressure (pd.DataFrame) – Vertical measurements, dry air pressure, \(P_{dry}\) [Pa].

Returns:

Derived vertical measurements for mixing ratio, \(r\) [kg \(\cdot\) kg ^-1].

Return type:

pd.DataFrame

get_moist_adiabatic_lapse_rate(mixing_ratio, temperature)

Computes moist adiabatic lapse rate.

Lapse rate is inversely proportional to the temperature gradient.

\[\Gamma_{{m}} = g \frac{{ \left ( 1 + \frac{{H_{{v}}r}} {{\mathfrak{{R}}_{{d}}T}} \right ) }} {{ \left ( c_{{p}} + \frac{{H_{{v}}^{{2}}r}} {{\mathfrak{{R}}_{{d}}T^{{2}}}} \right) }}\]

Parameters:

• temperature (pd.DataFrame) – Vertical measurements, temperature, \(T\) [K].

• mixing_ratio (pd.DataFrame) – Vertical measurements, mixing ratio, \(r\) [kg \(\cdot\) kg ^-1].

Returns:

Derived vertical measurements for moist adiabatic lapse rate, \(\Gamma_{w}\) [Km ^-1].

Return type:

pd.DataFrame

get_n_squared(potential_temperature, scheme='backward')

Calculates Brunt-Väisälä frequency, squared.

\[N^{{2}} = \frac{{g}}{{\bar{{\theta}}}} \frac{{\Delta \theta}}{{\Delta z}}\]

Parameters:

• potential_temperature (pd.DataFrame) – Vertical measurements, potential temperature \(\theta\) [K].

• scheme (str) – Finite differencing method. Supports “uneven” for centred-differencing over a non-uniform mesh, and “backward” for backward-differencing. Default “backward”.

Returns:

Derived vertical measurements for Brunt-Väisälä frequency squared, \(N^{2}\) [Hz].

Return type:

pd.DataFrame

get_potential_temperature(temperature, pressure)

Calculates potential temperature.

\[\theta = T \left ( \frac{{P_{{b}}}}{{P}} \right ) ^{{(\mathfrak{{R}}_{{d}}/c_{{p}})}}\]

Parameters:

• temperature (pd.DataFrame) – Vertical measurements, temperature, \(T\) [K].

• pressure (pd.DataFrame) – Vertical measurements, mean sea-level pressure, \(P_{MSLP}\) [Pa].

Returns:

Derived vertical measurements for potential temperature, \(\theta\) [K].

Return type:

pd.DataFrame

get_reduced_pressure(station_pressure, virtual_temperature, elevation)

Reduce station pressure to mean sea-level pressure.

\[P_{{MSL}} = P_{{z}} \cdot \exp \left ( \frac{{|g|}}{{\mathfrak{{R}}_{{d}}}} \frac{{z_{{stn}}}}{{T_{{v}}}} \right )\]

Parameters:

• station_pressure (pd.DataFrame) – Vertical measurements, pressure relative to station elevation, \(P_{z}\) [Pa].

• virtual_temperature (pd.DataFrame) – Vertical measurements, virtual temperature, \(T_{v}\) [K].

• elevation (float) – Station elevation, \(z_{stn}\) [m].

Returns:

Derived vertical measurements for mean sea-level pressure, \(P_{MSLP}\) [Pa].

Return type:

pd.DataFrame

get_static_stability(potential_temperature, scheme='backward')

Determines static stability of atmosphere.

Parameters:

• potential_temperature (pd.DataFrame) – Contains vertical measurements for potential temperature.

• scheme (str) – Finite differencing method. Supports “uneven” for centred-differencing over a non-uniform mesh, and “backward” for backward-differencing. Default “backward”.

Returns:

Derived vertical measurements for static stability.

Return type:

pd.DataFrame

get_vertical_variables(vertical_data, meteo_data, station_elevation=None)

Derives data from vertical measurements.

For several days or more of data, the returned dictionary may be quite large.

Parameters:

• vertical_data (dict) – Contains vertical measurements for absolute humidity and temperature.

• meteo_data (pd.DataFrame) – Meteorological data from surface measurements.

• station_elevation (float) – Weather station elevation, \(z_{stn}\) [m]. This is the station taking vertical measurements, not the scintillometer. If None, the elevation is detected from stored dataframe attributes.

Returns:

Derived vertical data for water vapour pressure, air pressure, mixing ratio, virtual temperature, mean sea-level pressure, and potential temperature.

Return type:

dict

get_virtual_temperature(temperature, mixing_ratio)

Derive virtual temperature from vertical measurements.

\[T_{{v}} = T(1 + 0.61r)\]

Parameters:

• temperature (pd.DataFrame) – Vertical measurements, air temperature, \(T\) [K].

• mixing_ratio (pd.DataFrame) – Vertical measurements, mixing ratio, \(r\) [kg \(\cdot\) kg ^-1].

Returns:

Derived vertical measurements for virtual temperature, \(T_{v}\) [K].

Return type:

pd.DataFrame

get_water_vapour_pressure(abs_humidity, temperature)

Derive water vapour pressure from vertical measurements.

\[e = \mathfrak{{R}}_{{v}} \cdot \rho_{{v}} T\]

Parameters:

• abs_humidity (pd.DataFrame) – Vertical measurements, absolute humidity, \(\rho_{v}\) [kg \(\cdot\) m ^-3].

• temperature (pd.DataFrame) – Vertical measurements, temperature, \(T\) [K].

Returns:

Derived vertical measurements for water vapour pressure, \(e\) [Pa].

Return type:

pd.DataFrame

non_uniform_differencing(dataframe)

Computes gradient of data from a non-uniform mesh.

The gradient is calculated using a 1-D centred-differencing scheme for a non-uniform mesh. For the boundary conditions: \(y_{{(x=0)}} = 0\), and \(y_{{(x=\max(x))}}\) is calculated by backwards-differencing - i.e. no open boundaries.

If the size of \(\Delta x_{{i}}\) is very different to \(\Delta x_{{i\pm 1}}\), then accuracy deteriorates from \(O((\Delta x)^{{2}})\) to \(O(\Delta x)\).

The scheme is as follows:

\[\begin{split}\left.\frac{{dy}}{{dx}} \right |_{{0}} = 0 \\\end{split}\]

\[\left.\frac{{dy}}{{dx}} \right |_{{i=\max(i)}} = \frac{{ y_{{i}} - y_{{i-1}} }}{{ \Delta x_{{i}} }}\]

\[\left.\frac{{dy}}{{dx}} \right |_{{i>0, i <\max(i)}} = \frac{{ y_{{i+1}} (\Delta x_{{i-1}})^{{2}} - y_{{i-1}} (\Delta x_{{i}})^{{2}} + y_{{i}} \left [ (\Delta x_{{i-1}})^{{2}} - (\Delta x_{{i}})^{{2}} \right ] }}{{ (\Delta x_{{i-1}}) (\Delta x_{{i}}) (\Delta x_{{i-1}} + \Delta x_{{i}}) + O(\Delta x_{{i}})^{{2}} }}\]

Parameters:

dataframe (pd.DataFrame) – Non-uniformly spaced measurements for single variable.

Returns:

Derivative of variable with respect to non-uniform intervals.

Return type:

pd.DataFrame

Iterations module

In: scintillometry.backend.iterations.py

Iterative methods to calculate heat fluxes.

IterationMost is descended from an old Python port of a method initially written in R by Dr. Helen Ward (2019), but has been completely rewritten - the implementations and features available are fundamentally different so the results from one should not be assumed identical to the other.

The current method used by IterationMost is based on mathematical theory available in:

• Scintec AG (2022). Scintec Scintillometers Theory Manual, Version 1.05. Scintec AG, Rottenburg, Germany.[11]

• Scintec AG (2008). Scintec Boundary Layer Scintillometer User Manual, Version 1.49. Scintec AG, Rottenburg, Germany.[12]

This method has been updated to resolve some inconsistencies between the manuals, and has additional modifications to enhance performance and broaden its use with different scintillometer models. Results may therefore differ slightly between this and other iterative methods.

class scintillometry.backend.iterations.IterationMost

Bases: object

Classic MOST Iteration.

A detailed description of the iterative scheme is available in the Scintec Scintillometers Theory Manual, Version 1.05.[11]

This iterative method resolves some inconsistencies between different scintillometer manuals. Results may therefore differ slightly with other third-party implementations.

constants

Inherited atmospheric constants.

Type:

AtmosConstants

calc_obukhov_length(temp, u_star, theta_star)

Calculate Obukhov length.

Parameters:

• temp (np.floating) – Air temperature in Kelvin, \(T\) [K].

• u_star (mpmath.mpf) – Friction velocity \(u^{*}\).

• theta_star (mpmath.mpf) – Temperature scale, \(\theta^{*}\).

Returns:

Obukhov Length, \(L_{Ob}\) [m].

Return type:

mpmath.mpf

calc_theta_star(ct2, f_ct2, z, stable)

Calculate temperature scale.

Parameters:

• ct2 (float) – Structure parameter of temperature, \(C_{T}^{2}\) [K \(^{2}\cdot\) m \(^{-2/3}\)].

• f_ct2 (float) – MOST function of \(C_{T}^{2}\), \(f_{C_{T}^{2}}\).

• z (float) – Effective height, \(z\) [m].

• stable (bool) – True for stable conditions, otherwise False.

Returns:

Temperature scale, \(\theta^{*}\).

Return type:

mpmath.mpf

calc_u_star(u, z_u, r_length, o_length)

Calculates friction velocity.

Parameters:

• u (float) – Wind speed, \(u\) [ms ^-1].

• z_u (float) – Height of wind speed measurement including displacement (z-d), \(z_{u}\) [m].

• r_length (float) – Roughness length, \(z_{0}\) [m].

• o_length (float) – Obukhov length \(L_{Ob}\) [m].

Returns:

Friction velocity \(u^{*}\).

Return type:

mpmath.mpf

check_signs(stable_flag, dataframe)

Warns if sign of variable doesn’t match expected sign.

Parameters:

• stable_flag (bool) – True for stable conditions, otherwise False.

• dataframe (pd.DataFrame) – Dataframe with sensible heat flux and Obukhov lengths.

Warns:

• UserWarning – Sign of Obukhov lengths should be opposite of SHFs.

• UserWarning – SHFs should never be positive for stable conditions.

• UserWarning – Obukhov lengths should never be negative for stable conditions.

get_most_coefficients(most_id='an1988', most_type='ct2')

Returns MOST coefficients for similarity functions.

Implemented MOST coefficients:

• an1988: E.L. Andreas (1988)[1]

• li2012: D. Li et al. (2012)[6]

• wy1971: Wyngaard et al. (1971)[15]

• wy1973: Wyngaard et al. (1973) in Kooijmans and Hartogensis (2016)[5]

• ma2014: Maronga et al. (2014)[7]

• br2014: Braam et al. (2014)[2]

Braam et al. (2014) and Maronga et al. (2014) do not provide coefficients for stable conditions, so gradient functions will evaluate to zero for stable conditions.

Parameters:

• most_id (str) – MOST coefficients for unstable and stable conditions. Default “an1988”.

• most_type (str) – MOST function. Default “ct2”.

Returns:

MOST coefficients formatted as [(unstable, unstable), (stable, stable)]

Return type:

list

Raises:

• NotImplementedError – MOST coefficients are not implemented for <most_id>.

• NotImplementedError – MOST coefficients are not implemented for functions of <most_type>.

momentum_stability(obukhov, z)

Integrated stability function for momentum.

Calculates integrated stability function for momentum under stable or unstable conditions. No implementation for neutral stability.

Parameters:

• obukhov (float) – Obukhov length, \(L_{Ob}\) [m].

• z (float) – Height, \(z\) [m].

Returns:

Integrated stability function for momentum, \(\Psi_{m}\) [0-Dim].

Return type:

mpmath.mpf

momentum_stability_stable(obukhov, z)

Integrated stability function for momentum, stable.

Apply when \(L_{Ob}\) > 0.

Parameters:

• obukhov (float) – Obukhov length, \(L_{Ob}\) [m].

• z (float) – Height, \(z\) [m].

Returns:

Integrated stability function for momentum, \(\Psi_{m}\) [0-Dim].

Return type:

mpmath.mpf

momentum_stability_unstable(obukhov, z)

Integrated stability function for momentum, unstable.

Uses formula from Paulson (1970)[10]. Apply when \(L_{Ob}\) < 0.

Parameters:

• obukhov (float) – Obukhov length, \(L_{Ob}\) [m].

• z (float) – Height, \(z\) [m].

Returns:

Integrated stability function for momentum, \(\Psi_{m}\) [0-Dim].

Return type:

mpmath.mpf

most_iteration(dataframe, zm_bls, stable_flag, most_coeffs)

Iterative MOST method.

A detailed description of the iterative method is available in:

• Scintec AG (2022). Scintec Scintillometers Theory Manual, Version 1.05. Scintec AG, Rottenburg, Germany.[11]

Iteration until convergence is slower than vectorisation, but more accurate. If a value never converges, the iteration stops after ten runs.

Parameters:

• dataframe (pd.DataFrame) – Parsed, localised dataframe row containing at least \(C_{T}^{2}\), wind speed, air density, and temperature.

• zm_bls (float) – Effective height of scintillometer.

• stable_flag (bool) – Stability conditions. If true, assumes stable conditions, otherwise assumes unstable conditions.

• most_coeffs (list) – MOST coefficients for unstable and stable conditions.

Returns:

Dataframe with additional columns for Obukhov lengths, sensible heat fluxes, frictional velocity, and temperature scale.

Return type:

pd.DataFrame

most_method(dataframe, eff_h, stability, coeff_id='an1988')

Calculate Obukhov length and sensible heat fluxes with MOST.

Iteration is more accurate but slower than vectorisation.

Implemented MOST coefficients:

• an1988: E.L. Andreas (1988)[1]

• li2012: D. Li et al. (2012)[6]

• wy1971: Wyngaard et al. (1971)[15]

• wy1973: Wyngaard et al. (1973) in Kooijmans and Hartogensis (2016)[5]

• ma2014: Maronga et al. (2014)[7]

• br2014: Braam et al. (2014)[2]

Braam et al. (2014) and Maronga et al. (2014) do not provide coefficients for stable conditions, so gradient functions will evaluate to zero for stable conditions.

Parameters:

• dataframe (pd.DataFrame) – Parsed, localised dataframe containing at least \(C_{T}^{2}\), wind speed, air density, and temperature.

• eff_h (float) – Effective path height.

• stability (str) – Stability conditions. Either “stable” or “unstable”.

• coeff_id (str) – ID of MOST coefficients for unstable and stable conditions. Default “an1988”.

Returns:

Dataframe with additional columns for Obukhov lengths, sensible heat fluxes, frictional velocity, and temperature scale.

Return type:

pd.DataFrame

similarity_function(obukhov, z, coeffs, stable)

Similarity function of \(C_{T}^{2}\).

Adapted from Wyngaard et al. (1971)[15]; Thiermann and Grassl (1992)[13]; Kooijmans and Hartogensis (2016)[5].

Parameters:

• obukhov (float) – Obukhov length, \(L_{Ob}\) [m].

• z (float) – Effective height, \(z\) [m].

• stable (bool) – True for stable conditions, otherwise False.

• coeffs (list) – MOST coefficients for unstable and stable conditions.

Returns:

Similarity function of \(C_{T}^{2}\), \(f_{C_{T}^{2}}\).

Return type:

float

Deprecations module

In: scintillometry.backend.deprecations.py

Handles deprecating, deprecated, and defunct code. The deprecation process takes one patch release cycle, the removal process takes two major release cycles.

EOL Cycle

Import the decorator deprecated() from this module. Mark deprecating functions like so:

@deprecated(stage="deprecated", reason="Some reason", version="1.1.1")
def foobar(...)
    ...

Where stage is the stage in the function’s deprecation cycle, reason is an optional message, and version is the release number when stage was last updated.

Update stage by following this schedule:

1. A function pending deprecation is marked as pending and issues a PendingDeprecationWarning during patch development.

2. The function is marked as deprecated and issues a DeprecationWarning from the next patch release. It must still work as intended.

3. The function is marked as eol and issues a FutureWarning during the next minor release cycle. It must still work as intended.

4. The function is marked as defunct and throws an error during the next major release cycle, but is not removed.

5. The defunct function is entirely removed from release candidates in preparation for the subsequent major release.

class scintillometry.backend.deprecations.Decorators

Bases: object

static deprecated(stage='deprecated', **details)

Decorator for deprecated function and method arguments.

Example:

@deprecated(stage="pending", reason="Foobar", version="1.3.2")
def some_function(foo):
    ...

Parameters:

stage (str) –

Stage of deprecation cycle. Valid values are:

• pending

• deprecated

• eol

• defunct

Default “deprecated”.

Keyword Arguments:

• reason (str) – Reason for deprecation.

• version (str) – Release number of latest stage in deprecation.

Returns:

Decorator for deprecated argument.

Return type:

Callable

static deprecated_argument(stage='deprecated', reason=None, version=None, **aliases)

Decorator for deprecated function and method arguments.

Use as follows:

@deprecated_argument(old_argument="new_argument")
def myfunc(new_arg):
    ...

Parameters:

• stage (str) –

  Stage of deprecation cycle. Valid values are:

  • pending

  • deprecated

  • eol

  • defunct

  Default “deprecated”.

• reason (str) – Reason for deprecation. Default None.

• version (str) – Release number of latest stage in deprecation. Default None.

• aliases (dict[str, str]) – Deprecated argument and its alternative.

Returns:

Decorator for deprecated argument.

Return type:

Callable

class scintillometry.backend.deprecations.DeprecationHandler

Bases: object

Methods for marking and handling deprecation cycles.

string_types

Supported string types (str and byte literals).

Type:

tuple

get_reason(**kwargs)

Gets reason for deprecation.

Keyword Arguments:

reason (str) – Reason for deprecation.

Returns:

The reason for deprecation if available, otherwise returns an empty string.

Return type:

str

get_stage(name)

Gets stage in deprecation cycle.

Parameters:

name (str) –

Stage of deprecation cycle. Valid values are:

• pending

• deprecated

• eol

• defunct

Returns:

The description of the deprecation stage, and the Exception subclass matching this stage.

Return type:

tuple[str, Exception]

Raises:

• TypeError – <type(name)> is an invalid type. Use str instead.

• ValueError – <name> is not a valid deprecation stage.

get_version(**kwargs)

Gets release number of latest stage in deprecation.

Keyword Arguments:

version (str) – Release number of latest stage in deprecation.

Returns:

Formatted version number of latest stage in deprecation if provided, otherwise returns an empty string.

Return type:

str

raise_warning(obj, stage, details)

Raises warning or error with informative message.

Raises a warning or error stating the function or class’ stage in its deprecation cycle. Optionally, lists a release number and reason.

Parameters:

• obj (Callable) – The function or class being deprecated.

• stage (str) – The current stage in the deprecation cycle.

• details (dict) –

  A dictionary map optionally containing the keys:

  • reason: the reason for deprecation.

  • version: the release number of the latest change in the deprecation cycle.

Raises:

RuntimeError – The function <obj.__name__> is <stage>.

rename_arguments(obj, stage, kwargs, alias, reason=None, version=None)

Marks argument as deprecated and redirects to alias.

The wrapped function’s arguments are wrapped into kwargs and are safe from being overwritten by arguments in alias.

Parameters:

• obj (Callable) – The function or class being deprecated.

• stage (str) – The current stage in the deprecation cycle.

• kwargs (dict) – Keyword arguments.

• alias (dict) – A dictionary map optionally containing the keys:

• reason (str) – The reason for deprecation. Default None.

• version (str) – The release number of the latest change in the deprecation cycle. Default None.

References

[1] (1,2)

E.L. Andreas (1988). Estimating Cn2 Over Snow and Sea Ice from Meteorological Data. J. Opt. Soc. Am. A., Vol. 5:4, [481-495]. DOI: https://doi.org/10.1364/JOSAA.5.000481

[2] (1,2)

M. Braam, A.F. Moene, F. Beyrich, et al. (2014). Similarity Relations for CT2 in the Unstable Atmospheric Surface Layer: Dependence on Regression Approach, Observation Height and Stability Range. Boundary-Layer Meteorology Vol. 153, [63-87]. DOI: https://doi.org/10.1007/s10546-014-9938-y

[3]

O.K. Hartogensis, C.J. Watts, J. Rodriguez, and H.A.R. De Bruin (2003). Derivation of an Effective Height for Scintillometers: La Poza Experiment in Northwest Mexico. J. Hydrometeor., Vol. 4, [915-928]. DOI: https://doi.org/10.1175/1525-7541(2003)004<0915:DOAEHF>2.0.CO;2

[4]

J. Kleissl, J. Gomez, S.H. Hong, et al. (2008). Large Aperture Scintillometer Intercomparison Study. Boundary-Layer Meteorology, Vol. 128, [133-150] (2008). DOI: https://doi.org/10.1007/s10546-008-9274-1

[5] (1,2,3)

L.M.J. Kooijmans, O.K. Hartogensis (2014). Surface-Layer Similarity Functions for Dissipation Rate and Structure Parameters of Temperature and Humidity Based on Eleven Field Experiments. Boundary-Layer Meteorol Vol. 160, [501-527]. DOI: https://doi.org/10.1007/s10546-016-0152-y

[6] (1,2)

D. Li, E. Bou-Zeid & H.A.R. De Bruin (2012). Monin-Obukhov Similarity Functions for the Structure Parameters of Temperature and Humidity. Boundary-Layer Meteorology Vol. 145, [45-67]. DOI: https://doi.org/10.1007/s10546-011-9660-y

[7] (1,2)

B. Maronga, O.K. Hartogensis, S. Raasch et al. (2014). The Effect of Surface Heterogeneity on the Structure Parameters of Temperature and Specific Humidity: A Large-Eddy Simulation Case Study for the LITFASS-2003 Experiment. Boundary-Layer Meteorology, Vol. 153, [441-470]. DOI: https://doi.org/10.1007/s10546-014-9955-x

[8]

A.F. Moene (2003). Effects of Water Vapour on the Structure Parameter of the Refractive Index for Near-Infrared Radiation. Boundary-Layer Meteorology, Vol. 107, [635-653]. DOI: https://doi.org/10.1023/A:1022807617073

[9]

J.C. Owens (1967). Optical Refractive Index of Air: Dependence on Pressure, Temperature and Composition. Appl. Opt., 6:1 [51-9]. PMID: 20057695. DOI: https://doi.org/10.1364/AO.6.000051

[10]

C.A. Paulson (1970). The Mathematical Representation of Wind Speed and Temperature Profiles in the Unstable Atmospheric Surface Layer. J. Appl. Meteorology, Vol. 9:6 [857-861]. DOI: https://doi.org/10.1175/1520-0450(1970)009<0857:TMROWS>2.0.CO;2

[11] (1,2,3,4)

Scintec AG (2022). Scintec Scintillometers Theory Manual (SLS/BLS). Version 1.05. Scintec AG, Rottenburg, Germany.

[12] (1,2)

Scintec AG (2008). Scintec Boundary Layer Scintillometer User Manual. Version 1.49. Scintec AG, Rottenburg, Germany.

[13]

V. Thiermann, H. Grassl (1992). The Measurement of Turbulent Surface-Layer Fluxes by Use of Bichromatic Scintillation. Boundary-Layer Meteorology, Vol. 58, [367-389]. DOI: https://doi.org/10.1007/BF00120238

[14] (1,2)

H.C. Ward, J.G. Evans, O.K. Hartogensis, A.F. Moene, H.A.R. De Bruin, C.S.B. Grimmond (2013). A Critical Revision of the Estimation of the Latent Heat Flux from Two-Wavelength Scintillometry. Q.J.R. Meteorology Soc., Vol. 139 [1912-1922]. DOI: https://doi.org/10.1002/qj.2076

[15] (1,2,3)

J. C. Wyngaard, Y. Izumi, and S. A. Collins (1971). Behavior of the Refractive-Index-Structure Parameter near the Ground. J. Opt. Soc. Am., Vol. 61:12, [1646-1650]. DOI: https://doi.org/10.1364/JOSA.61.001646

Module contents