smrt.emmodel package 

This package contains the different electromagnetic (EM) models that compute the scattering and absorption coefficients and the phase function in a given layer. The computation of the inter-layer propagation is done by the smrt.rtsolver package.

The EM models differ in many aspects, one of which is the constraint on the microstructure model they can be used with. The:py:mod:smrt.emmodel.iba model can use any microstructure model that defines autocorrelation functions (or its FT). In contrast, others such as smrt.emmodel.dmrt_shortrange are bound to the:py:mod:smrt.microstructuremodel.sticky_hard_spheres microstructure for theoretical reasons.

The selection of the EM model is done with the smrt.core.model.make_model function.

For developers

To implement a new scattering formulation / phase function, we recommend to start from an existing module, probably rayleigh.py is the simplest. Copy this file to myscatteringtheory.py or any meaningful name. It can be directly used with smrt.core.model.make_model() function as follows:

m = make_model("myscatteringtheory", "dort")

Note that if the file is not in the emmodels directory, you must explicitly import the module and pass it to make_model as a module object (instead of a string).

An emmodel model must define:

ks and ka attributes/properties
ke() and effective_permittivity() methods
at least one of the phase and ft_even_phase methods (both is better).

For the details it is recommended to contact the authors as the calling arguments and required methods may change from time to time.

smrt.emmodel.iba module 

Compute scattering from Improved Born Approximation theory as described in Mätzler 1998 and Mätzler and Wiesman 1999, except the absorption coefficient which is computed with Polden von Staten formulation instead of the Eq 24 in Mätzler 1998. See iba_original.py for a fully conforming IBA version. This model allows for different microstructural models provided that the Fourier transform of the correlation function may be performed. All properties relate to a single layer.

References

Mätzler, C. (1998). Improved Born approximation for scattering of radiation in a granular medium. Journal of Applied Physics, 83(11), 6111–6117. https://doi.org/10.1063/1.367496
Mätzler, C., & Wiesmann, A. (1999). Extension of the Microwave Emission Model of Layered Snowpacks to Coarse-Grained Snow. Remote Sensing of Environment, 70(3), 317–325. https://doi.org/10.1016/s0034-4257(99)00047-4

derived_IBA(effective_permittivity_model=<function polder_van_santen>)

return a new IBA model with variant from the default IBA.

Parameters:: effective_permittivity_model – permittivity mixing formula.
Returns:: a new class inheriting from IBA but with patched methods

class IBA(sensor, layer, dense_snow_correction=None)

Bases: AdjustableEffectivePermittivityMixin, IsotropicScatteringMixin, GenericFTPhaseMixin

Improved Born Approximation electromagnetic model class.

As with all electromagnetic modules, this class is used to create an electromagnetic object that holds information about the effective permittivity, extinction coefficient and phase function for a particular snow layer. Due to the frequency dependence, information about the sensor is required. Passive and active sensors also have different requirements on the size of the phase matrix as redundant information is not calculated for the passive case.

Parameters:

sensor – Object containing sensor characteristics.
layer – Object containing snow layer characteristics (single layer).
dense_snow_correction – Set how snow denser than half the ice density (i.e. fractional volume larger than 0.5) is handled. “auto” means that snow is modeled as air bubble in ice instead of ice spheres in air. The default is None.

Example

This class is not normally accessed directly by the user, but forms part of the smrt model, together with the radiative solver (in this example, dort) i.e.:

from smrt import make_model
model = make_model("iba", "dort")

iba does not need to be imported by the user due to autoimport of electromagnetic model modules.

static effective_permittivity_model(frac_volume: float, e0: complex = 1, eps: complex = 3.185, depolarization_factors=None, length_ratio: float | None = None, inclusion_shape: str | Sequence | Mapping | None = None, mixing_ratio: int | None = None)

Calculate the effective permittivity of snow by solution of quadratic Polder Van Santen equation for spherical or random needle inclusions only, potentially a mixing of these shapes (Sihvola, 1999).

Note

See general_polder_van_santen() for an alternative function (more generic, but slower).

Parameters:

frac_volume – Fractional volume of inclusions.
e0 – Permittivity of background (default is 1).
eps – Permittivity of scattering material (default is 3.185 to compare with MEMLS)
depolarization_factors – [Optional] Depolarization factors, spherical isotropy is default. It is not taken into account here.
length_ratio – Length_ratio. Used to estimate depolarization factors when they are not given.
inclusion_shape – Assumption for shape(s) of brine inclusions. Can be a string for single shape, or a list/tuple/dict of strings for mixture of shapes. So far, we have the following shapes: “spheres” and “random_needles” (i.e. randomly-oriented elongated ellipsoidal inclusions). If the argument is a dict, the keys are the shapes and the values are the mixing ratio. If it is a list, the mixing_ratio argument is required.
mixing_ratio – The mixing ratio of the shapes. This is only relevant when inclusion_shape is a list/tuple. Mixing ratio must be a sequence with length len(inclusion_shape)-1. The mixing ratio of the last shapes is deduced as the sum of the ratios must equal to 1.

Returns:

Effective permittivity

Usage:

>>> from smrt.permittivity.generic_mixing_formula import polder_van_santen
>>> effective_permittivity = polder_van_santen(frac_volume, e0, eps)

for a mixture of 30% spheres and 70% needles >>> effective_permittivity = polder_van_santen(frac_volume, e0, eps, inclusion_shape={“spheres”: 0.3, “random_needles”: 0.7})

or >>> effective_permittivity = polder_van_santen(frac_volume, e0, eps, inclusion_shape=(“spheres”, “random_needles”), mixing_ratio=0.3)

Todo

Extend Polder Van Santen model to account for ellipsoidal inclusions

References

Sihvola, A.: Electromagnetic Mixing Formulas and Applications, 1999, INSTITUTION OF ENGINEERING & T http://www.ebook.de/de/product/21470462/a_sihvola_electromagnetic_mixing_formulas_and_applications.html

compute_iba_coeff(): Calculate angular independent IBA coefficient: used in both scattering coefficient and phase function calculations

Note

Requires mean squared field ratio (uses mean_sq_field_ratio method)

mean_sq_field_ratio()

Mean squared field ratio calculation.

Uses layer effective permittivity.

compute_ks()

Calculate scattering coefficient.

Integrates p11+p12 over mu.

Returns:: Scattering coefficient.
Return type:: float

ks_integrand(mu)

Scattering function for the IBA model.

It uses the phase matrix in the 1-2 frame. With incident angle chosen to be 0, the scattering angle becomes the scattering zenith angle:

$\Theta= \theta$

Scattering coefficient is determined by integration over the scattering angle(0 to pi): param mu: cosine of the scattering angle(single angle)

$ks\_int=p11 + p22$

The integration is performed outside this method.

phase(mu_s, mu_i, dphi, npol=2): IBA Phase function (not decomposed).

compute_ka()

IBA absorption coefficient calculated from the low-loss assumption of a general lossy medium.

Calculates ka from wavenumber in free space (determined from sensor), and effective permittivity of the medium (snow layer property).

Returns:: Absorption coefficient [m^-1].
Return type:: float

Note

This may not be suitable for high density material.

class IBA_MM(sensor, layer): Bases: IBA

smrt.emmodel.dmrt_qca_shortrange module 

Compute scattering with DMRT QCA Short range. Short range means that it is accurate only for small and weakly sticky spheres (high stickiness value). It diverges (increasing scattering coefficient) if these conditions are not met. Numerically the size conditions can be evaluated with the ratio radius/wavelength as for Rayleigh scatterers. For the stickiness, it is more difficult as this depends on the size of the scatterers and the fractional volume. In any case, it is dangerous to use too small a stickiness value, especially if the grains are big.

This model is only compatible with the SHS microstructure model.

Examples:

from smrt import make_snowpack, make_sensor

density = [345.0]
temperature = [260.0]
thickness = [70]
radius = [750e-6]
stickiness = [0.1]

snowpack = make_snowpack(thickness, "sticky_hard_spheres",
                    density=density, temperature=temperature, radius=radius, stickiness=stickiness)


# create the EM Model - Equivalent DMRTML
m = make_model("dmrt_shortrange", "dort")

# create the sensor
theta = np.arange(5.0, 80.0, 5.0)
radiometer = sensor.amsre()

class DMRT_QCA_ShortRange(sensor, layer, dense_snow_correction='auto')

Bases: Rayleigh

DMRT electromagnetic model in the short range limit (grains AND aggregates are small) as implemented in DMRTML

Parameters:

sensor – sensor instance
layer – layer instance
dense_snow_correction – set how snow denser than half the ice density (ie. fractional volume larger than 0.5 is handled). “auto” means that snow is modeled as air bubble in ice instead of ice spheres in air. “bridging” should be developed in the future.

smrt.emmodel.dmrt_qcacp_shortrange module 

Compute scattering with DMRT QCACP Short range like in DMRT-ML. Short range means that it is accurate only for small and weakly sticky spheres (high stickiness value). It diverges (increasing scattering coefficient) if these conditions are not met. Numerically the size conditions can be evaluated with the ratio radius/wavelength as for Rayleigh scatterers. For the stickiness, it is more difficult as this depends on the size of the scatterers and the fractional volume. In any case, it is dangerous to use too small a stickiness value, especially if the grains are big.

This model is only compatible with the SHS microstructure model.

Examples:

from smrt import make_snowpack, make_sensor

density = [345.0]
temperature = [260.0]
thickness = [70]
radius = [750e-6]
stickiness = [0.1]

snowpack = make_snowpack(thickness, "sticky_hard_spheres",
                    density=density, temperature=temperature, radius=radius, stickiness=stickiness)


# create the EM Model - Equivalent DMRTML
m = make_model("dmrt_shortrange", "dort")

# create the sensor
theta = np.arange(5.0, 80.0, 5.0)
radiometer = sensor.amsre()

class DMRT_QCACP_ShortRange(sensor, layer, dense_snow_correction='auto')

Bases: Rayleigh

DMRT electromagnetic model in the short range limit (grains AND aggregates are small) as implemented in DMRTML

Parameters:

sensor – sensor instance
layer – layer instance

Dense_snow_correction:

set how snow denser than half the ice density (ie. fractional volume larger than 0.5 is handled). “auto” means that snow is modeled as air bubble in ice instead of ice spheres in air. “bridging” should be developed in the future.

smrt.emmodel.symsce_torquato21 module 

Computes scattering with the symmetrized version of the Strong-Contrast Expansion (SCE) from Torquato and Kom 2021 under the non-local approximation, a.k.a long range in Tsang’s books. The truncation of the series is at second order.

References

Torquato, S., & Kim, J. (2021). Nonlocal Effective Electromagnetic Wave Characteristics of
Composite Media: Beyond the Quasistatic Regime. Physical Review X, 11(2). doi:10.1103/physrevx.11.021002
1. Picard, H. Löwe, C. Mätzler, A continuous formulation of microwave scattering from fresh snow to bubbly ice from first principles, The Cryosphere, 16, 3861–3866,doi:10.5194/tc-16-3861-2022, 2022

derived_SymSCETK21(effective_permittivity_model)

Returns a new SymSCE model with variant from the default SymSCE.

Parameters:: effective_permittivity_model – Permittivity mixing formula.
Returns:: A new class inheriting from SymSCE but with patched methods.
Return type:: class

class SymSCETK21(sensor, layer, scaled=True)

Bases: AdjustableEffectivePermittivityMixin, SCEBase

static effective_permittivity_model(frac_volume: float, e0: complex = 1, eps: complex = 3.185, depolarization_factors=None, length_ratio: float | None = None, inclusion_shape: str | Sequence | Mapping | None = None, mixing_ratio: int | None = None)

Calculate the effective permittivity of snow by solution of quadratic Polder Van Santen equation for spherical or random needle inclusions only, potentially a mixing of these shapes (Sihvola, 1999).

Note

See general_polder_van_santen() for an alternative function (more generic, but slower).

Parameters:

frac_volume – Fractional volume of inclusions.
e0 – Permittivity of background (default is 1).
eps – Permittivity of scattering material (default is 3.185 to compare with MEMLS)
depolarization_factors – [Optional] Depolarization factors, spherical isotropy is default. It is not taken into account here.
length_ratio – Length_ratio. Used to estimate depolarization factors when they are not given.
inclusion_shape – Assumption for shape(s) of brine inclusions. Can be a string for single shape, or a list/tuple/dict of strings for mixture of shapes. So far, we have the following shapes: “spheres” and “random_needles” (i.e. randomly-oriented elongated ellipsoidal inclusions). If the argument is a dict, the keys are the shapes and the values are the mixing ratio. If it is a list, the mixing_ratio argument is required.
mixing_ratio – The mixing ratio of the shapes. This is only relevant when inclusion_shape is a list/tuple. Mixing ratio must be a sequence with length len(inclusion_shape)-1. The mixing ratio of the last shapes is deduced as the sum of the ratios must equal to 1.

Returns:

Effective permittivity

Usage:

>>> from smrt.permittivity.generic_mixing_formula import polder_van_santen
>>> effective_permittivity = polder_van_santen(frac_volume, e0, eps)

for a mixture of 30% spheres and 70% needles >>> effective_permittivity = polder_van_santen(frac_volume, e0, eps, inclusion_shape={“spheres”: 0.3, “random_needles”: 0.7})

or >>> effective_permittivity = polder_van_santen(frac_volume, e0, eps, inclusion_shape=(“spheres”, “random_needles”), mixing_ratio=0.3)

Todo

Extend Polder Van Santen model to account for ellipsoidal inclusions

References

Sihvola, A.: Electromagnetic Mixing Formulas and Applications, 1999, INSTITUTION OF ENGINEERING & T http://www.ebook.de/de/product/21470462/a_sihvola_electromagnetic_mixing_formulas_and_applications.html

smrt.emmodel.nonscattering module 

Non-scattering medium can be applied to medium without heterogeneity (like water or pure ice layer).

smrt.emmodel.prescribed_kskaeps module 

Use prescribed scattering ks and absorption ka coefficients and effective permittivity in the layer. The phase matrix has the Rayleigh form with prescribed scattering coefficient.

This model is compatible with any microstructure but requires that ks, ka, and optionally effective permittivity to be set in the layer.

Example:

m = make_model("prescribed_kskaeps", "dort")
snowpack.layers[0].ks = ks
snowpack.layers[0].ka = ka
snowpack.layers[0].effective_permittivity = eff_eps

smrt.emmodel.rayleigh module 

Compute Rayleigh scattering. This theory requires the scatterers to be smaller than the wavelength and the medium to be sparsely populated (eq. very low density in the case of snow).

This model is only compatible with the Independent Sphere microstructure model

smrt.emmodel.sft_rayleigh module 

Compute Strong Fluctuation Theory scattering. This theory requires the scatterers to be smaller than the wavelength

This model is only compatible with the Exponential autocorrelation function only

smrt.emmodel.iba_original module 

Compute scattering from Improved Born Approximation theory. This model allows for different microstructural models provided that the Fourier transform of the correlation function may be performed. All properties relate to a single layer. The absorption is calculated with the original formula in Mätzler 1998

class IBA_original(sensor, layer, dense_snow_correction=None)

Bases: IBA

Original Improved Born Approximation electromagnetic model class.

As with all electromagnetic modules, this class is used to create an electromagnetic object that holds information about the effective permittivity, extinction coefficient and phase function for a particular snow layer. Due to the frequency dependence, information about the sensor is required. Passive and active sensors also have different requirements on the size of the phase matrix as redundant information is not calculated for the passive case.

Parameters:

sensor – Object containing sensor characteristics.
layer – Object containing snow layer characteristics (single layer).

compute_ka()

IBA absorption coefficient calculated from the low-loss assumption of a general lossy medium.

Calculates ka from wavenumber in free space (determined from sensor), and effective permittivity of the medium (snow layer property).

Returns:: Absorption coefficient [m^-1].
Return type:: float

Note

This may not be suitable for high density material.

smrt.emmodel.sce_torquato21 module 

Computes scattering with the Strong-Contrast Expansion (SCE) from Torquato and Kom 2021. This SCE is the “non-local approximation” in Torquato, also called “long range” in Tsang’s books. It applies to scatterer size up to 1 wavelength.

References

Torquato, S., & Kim, J. (2021). Nonlocal Effective Electromagnetic Wave Characteristics of
Composite Media: Beyond the Quasistatic Regime. Physical Review X, 11(2). doi:10.1103/physrevx.11.021002

derived_SCETK21(effective_permittivity_model)

Return a new SCE_ShortRange model with variant from the default SCE_ShortRange.

Parameters:: effective_permittivity_model – Permittivity mixing formula.
Returns:: A new class inheriting from SCE_ShortRange but with patched methods.
Return type:: class

class SCETK21(sensor, layer, scaled=True)

Bases: AdjustableEffectivePermittivityMixin, SCEBase

To be documented.

static effective_permittivity_model(frac_volume, e0, eps)

Calculate effective permittivity using Maxwell-Garnett equation assuming spherical inclusion.

Note

This function is essentially an optimized version of py:func:maxwell_garnett.

Parameters:

frac_volume – Fractional volume of snow.
e0 – Permittivity of background (no default, must be provided).
eps – Permittivity of scattering material (no default, must be provided).

Returns:

Effective permittivity.

smrt.emmodel.sce_torquato21_shortrange module 

Computes scattering with the Strong-Contrast Expansion (SCE) from Torquato and Kom 2021. This SCE is the quasi-static version, called “local approximation” in Torquato and “short range” in Tsang’s books. It applies to low frequency or small scatterers. Because of this assumption, local and non-local are undistinguishable, so that Rechtmans and Torquato, 2008 also provides a good reference for this implementation.

derived_SCETK21_ShortRange(effective_permittivity_model)

Return a new SCE_ShortRange model with variant from the default SCE_ShortRange.

Parameters:: effective_permittivity_model – Permittivity mixing formula.
Returns:: A new class inheriting from SCE_ShortRange but with patched methods.
Return type:: class

class SCETK21_ShortRange(sensor, layer, scaled=True)

Bases: AdjustableEffectivePermittivityMixin, SCEBase

To be documented.

static effective_permittivity_model(frac_volume, e0, eps)

Calculate effective permittivity using Maxwell-Garnett equation assuming spherical inclusion.

Note

This function is essentially an optimized version of py:func:maxwell_garnett.

Parameters:

frac_volume – Fractional volume of snow.
e0 – Permittivity of background (no default, must be provided).
eps – Permittivity of scattering material (no default, must be provided).

Returns:

Effective permittivity.

smrt.emmodel.sce_rechtsman08 module 

Compute scattering with the Strong-Contrast Expansion (SCE) from Rechtsman and Torquato, 2008 adapted by Ghislain Picard (unpublished at time of writing). This SCE is the local version valid for quasi-static frequency (i.e. low frequency or small scatterers). A non-local version has been devised recently.

class SCER08(sensor, layer)

Bases: SCEBase

To be documented.

compute_A2(Q, microstructure): Compute A2 using equation 26

effective_permittivity()

Calculation of complex effective permittivity of the medium, which is given by Maxwell Garnet in the case of Rechtsman and Torquato, 2008

Returns:: Effective permittivity.
Return type:: float