Weighting Functions¶

These classes provide a consistent framework for calculating weighting functions using different methods and engines.

For HR, the finite difference classes should be used, as the built-in methods are approximations not suitable for calculating AMFs. For DO, the finite difference class is not recommended, as the built-in method is exact and more efficient. The MC class is only meant for use by the air mass factor module.

Base Classes¶

WeightingFunctionBase has initialization parameters common to all weighting function classes. Finite difference and variable grid classes add more parameters.

class skdoas.wf.wf.WeightingFunctionBase(geometry: sasktran.geometry.Geometry, atmosphere: sasktran.atmosphere.Atmosphere, wf_species: Union[str, List[str]], **options)¶

Base class for objects which calculate weighting functions using SASKTRAN.

__init__(geometry: sasktran.geometry.Geometry, atmosphere: sasktran.atmosphere.Atmosphere, wf_species: Union[str, List[str]], **options)¶

Parameters

geometry (sk.Geometry) – Geometry object from sasktran containing information about the lines of sight and the sun.
atmosphere (sk.Atmosphere) – Atmosphere object from sasktran containing information about the atmosphere. If atmosphere.wf_species is set, it will be overruled by wf_species.
wf_species (str, List[str]) – List of species corresponding to the names of species in atmosphere for which weighting functions will be calculated.
**options – Options that are passed to the engine.

class skdoas.wf.finite_difference_wf.WeightingFunctionFiniteDifferenceBase(geometry: sasktran.geometry.Geometry, atmosphere: sasktran.atmosphere.Atmosphere, wf_species: Optional[List[str]] = None, method: str = 'forward', step: Union[float, List[float]] = 0.01, relative_step: bool = True, minimum_step: float = 100000000.0, progress_bar: Union[bool, tqdm.std.tqdm] = False, **options)¶

Base class for weighting equation calculation using a finite difference approximation.

__init__(geometry: sasktran.geometry.Geometry, atmosphere: sasktran.atmosphere.Atmosphere, wf_species: Optional[List[str]] = None, method: str = 'forward', step: Union[float, List[float]] = 0.01, relative_step: bool = True, minimum_step: float = 100000000.0, progress_bar: Union[bool, tqdm.std.tqdm] = False, **options)¶

Parameters

geometry (sk.Geometry) – See skdoas.wf.wf.WeightingFunctionBase
atmosphere (sk.Atmosphere) – See skdoas.wf.wf.WeightingFunctionBase
method (str) – Determines which finite difference scheme is used. One of ‘forward’, ‘backward’ or ‘central’
step (Union[float, List[float]], 0.1) – The step used to perturb one layer of the atmosphere. Interpretation depends on relative_step. Should be a float or a list/array with length matching wf_altitudes/wf_widths.
relative_step (bool, True) – If true, step is interpreted as a relative step. If false, it is interpreted as an absolute step.
minimum_step (float, 1e8) – The minimum step when relative_step is True, overriding the relative value.
progress_bar (bool, False) – If true, a progress bar will be displayed.
**options – See skdoas.wf.wf.WeightingFunctionBase

class skdoas.wf.finite_difference_wf.WeightingFunctionFiniteDifferenceVariableGrid(geometry: sasktran.geometry.Geometry, atmosphere: sasktran.atmosphere.Atmosphere, wf_species: Optional[List[str]] = None, method: str = 'forward', step: Union[float, List[float]] = 0.01, relative_step: bool = True, minimum_step: float = 100000000.0, grid_groups: Union[int, List[int]] = 1, progress_bar: Union[bool, tqdm.std.tqdm] = False, **options)¶

Uses a different atmospheric grid for each weighting function (or for groups of weighting functions). The advantage is that a dense grid spanning all the amf layers does not have to be used; the disadvantage is that the unperturbed radiance must be calculated on each new grid to prevent the small grid-related changes from being amplified by the finite difference calculation.

__init__(geometry: sasktran.geometry.Geometry, atmosphere: sasktran.atmosphere.Atmosphere, wf_species: Optional[List[str]] = None, method: str = 'forward', step: Union[float, List[float]] = 0.01, relative_step: bool = True, minimum_step: float = 100000000.0, grid_groups: Union[int, List[int]] = 1, progress_bar: Union[bool, tqdm.std.tqdm] = False, **options)¶

Parameters

geometry (sk.Geometry) – See WeightingFunctionBase.
atmosphere (sk.Atmosphere) – See WeightingFunctionBase.
method (str) – See WeightingFunctionFiniteDifferenceBase.
step (Union[float, List[float]], 0.1) – See WeightingFunctionFiniteDifferenceBase.
relative_step (bool, True) – See WeightingFunctionFiniteDifferenceBase.
minimum_step (float, 1e8) – See WeightingFunctionFiniteDifferenceBase.
grid_groups (Union[int, List[int]], 1) – Choose groups of weighting functions that will have a common grid. If grid_groups is an integer, weighting functions will be placed in groups of the size of that integer, beginning with the lowest altitude. If grid_groups is a list of integers, it will be interpreted as a map, mapping weighting function indices to grid group indices.
progress_bar (bool, False) – See WeightingFunctionFiniteDifferenceBase.
**options – See WeightingFunctionBase.

High Resolution (HR) Classes¶

class skdoas.wf.hr_wf.WeightingFunctionHR(geometry: sasktran.geometry.Geometry, atmosphere: sasktran.atmosphere.Atmosphere, wf_species: Union[str, List[str]], **options)¶: Class to calculate weighting functions using the built-in method from SASKTRAN’s high resolution (HR) engine. Use this class with caution as the built-in method makes approximations which may result in too much error for some applications.

class skdoas.wf.hr_wf.WeightingFunctionFiniteDifferenceHR(geometry: sasktran.geometry.Geometry, atmosphere: sasktran.atmosphere.Atmosphere, wf_species: Union[str, List[str]], method: str = 'forward', step: Union[float, List[float]] = 0.01, relative_step: bool = True, minimum_step: float = 100000000.0, progress_bar: Union[bool, tqdm.std.tqdm] = False, **options)¶: Class to calculate weighting functions with SASKTRAN’s high resolution (HR) engine using finite difference approximations. Calculations are computationally intensive as they require one (or two) full radiative transfer calculation for every weighting equation altitude.

class skdoas.wf.hr_wf.WeightingFunctionFiniteDifferenceVariableGridHR(geometry: sasktran.geometry.Geometry, atmosphere: sasktran.atmosphere.Atmosphere, wf_species: Union[str, List[str]], method: str = 'forward', step: Union[float, List[float]] = 0.01, relative_step: bool = True, minimum_step: float = 100000000.0, grid_groups: Union[int, List[int]] = 1, progress_bar: Union[bool, tqdm.std.tqdm] = False, **options)¶: Class to calculate weighting functions with SASKTRAN’s high resolution (HR) engine using finite difference approximations. Uses a different atmospheric grid for each weighting function (or for groups of weighting functions). The advantage is that a dense grid spanning all the amf layers does not have to be used; the disadvantage is that the unperturbed radiance must be calculated on each new grid to prevent the small grid-related changes from being amplified by the finite difference calculation.

class skdoas.wf.hr_wf.WeightingFunctionFiniteDifferenceMatchShellsHR(geometry: sasktran.geometry.Geometry, atmosphere: sasktran.atmosphere.Atmosphere, wf_species: Union[str, List[str]], method: str = 'forward', step: Union[float, List[float]] = 0.01, relative_step: bool = True, minimum_step: float = 100000000.0, progress_bar: Union[bool, tqdm.std.tqdm] = False, **options)¶: Class to calculate weighting functions with SASKTRAN’s high resolution (HR) engine using finite difference approximations. Calculations are computationally intensive as they require one (or two) full radiative transfer calculation for every weighting equation altitude. This class builds perturbations around the atmospheric ray-tracing shells, rather than adding shells to accommodate the shape of the perturbation.

class skdoas.wf.hr_wf.WeightingFunctionFiniteDifferenceConstantLayersHR(geometry: sasktran.geometry.Geometry, atmosphere: sasktran.atmosphere.Atmosphere, wf_species: Union[str, List[str]], method: str = 'forward', step: Union[float, List[float]] = 0.01, relative_step: bool = True, minimum_step: float = 100000000.0, progress_bar: Union[bool, tqdm.std.tqdm] = False, **options)¶

Similar to WeightingFunctionFiniteDifferenceHR, but perturbations are constructed assuming climatology values represent constant layers.

Use skdoas.utility.convert_linear_to_constant_atmosphere() to prepare the sk.Atmosphere object for this class.

The HR option ‘integrationtechnique’ is automatically set.

class skdoas.wf.hr_wf.WeightingFunctionFiniteDifferenceConstantLayersVariableGridHR(geometry: sasktran.geometry.Geometry, atmosphere: sasktran.atmosphere.Atmosphere, wf_species: Union[str, List[str]], method: str = 'forward', step: Union[float, List[float]] = 0.01, relative_step: bool = True, minimum_step: float = 100000000.0, grid_groups: Union[int, List[int]] = 1, progress_bar: Union[bool, tqdm.std.tqdm] = False, **options)¶

Combines WeightingFunctionFiniteDifferenceVariableGridHR and WeightingFunctionFiniteDifferenceConstantLayersHR.

Use skdoas.utility.convert_linear_to_constant_atmosphere() to prepare the sk.Atmosphere object for this class.

The HR option ‘integrationtechnique’ is automatically set.

Discrete Ordinates (DO) Classes¶

class skdoas.wf.do_wf.WeightingFunctionDO(geometry: sasktran.geometry.Geometry, atmosphere: sasktran.atmosphere.Atmosphere, wf_species: Union[str, List[str]], **options)¶: Class to calculate weighting functions using the built-in method from SASKTRAN’s discrete ordinates (DO) engine.

class skdoas.wf.do_wf.WeightingFunctionFiniteDifferenceDO(geometry: sasktran.geometry.Geometry, atmosphere: sasktran.atmosphere.Atmosphere, wf_species: Union[str, List[str]], method: str = 'forward', step: Union[float, List[float]] = 0.01, relative_step=True, minimum_step=100000000.0, progress_bar: Union[bool, tqdm.std.tqdm] = False, **options)¶: Class to calculate weighting functions with SASKTRAN’s discrete ordinates (DO) engine using finite difference approximations. Use of this class is not recommended, as WeightingFunctionDO produces equivalent results in a fraction of the time.

Monte Carlo (MC) Classes¶

class skdoas.wf.mc_wf.WeightingFunctionNullMC(geometry: sasktran.geometry.Geometry, atmosphere: sasktran.atmosphere.Atmosphere, **options)¶: This class does not actually calculate any weighting functions; using the __call__ method will raise an exception. Its only use is to be passed to AirMassFactor, keeping the structure consistent with HR and DO which require weighting functions while MC does not. This class can calculate radiances and hold various settings, functions which the other weighting equation classes provide in addition to weighting equation calculation.