smrt.interface package¶
Submodules¶
smrt.interface.coherent_flat module¶
Implement the coherent flat pseudo-interface, as in MEMLS. This interface is obtained by collapsing one layer and two interfaces into a single interface. Scattering in the layer is neglected.
-
process_coherent_layers
(snowpack, emmodel_list, sensor)¶
-
class
CoherentFlat
(interfaces, layer, permittivity)¶ Bases:
object
A flat surface. The reflection is in the specular direction and the coefficient is calculated with the Fresnel coefficients
-
args
= []¶
-
optional_args
= {}¶
-
__init__
(interfaces, layer, permittivity)¶ Initialize self. See help(type(self)) for accurate signature.
-
specular_reflection_matrix
(frequency, eps_1, eps_2, mu1, npol)¶ - compute the reflection coefficients for an array of incidence angles (given by their cosine)
- in medium 1. Medium 2 is where the beam is transmitted.
Parameters: - eps_1 – permittivity of the medium where the incident beam is propagating.
- eps_2 – permittivity of the other medium.
- mu1 – array of cosine of incident angles.
- npol – number of polarization.
Returns: the reflection matrix
-
diffuse_reflection_matrix
(frequency, eps_1, eps_2, mu_s, mu_i, dphi, npol)¶
-
coherent_transmission_matrix
(frequency, eps_1, eps_2, mu1, npol)¶ - compute the transmission coefficients for the azimuthal mode m
- and for an array of incidence angles (given by their cosine) in medium 1. Medium 2 is where the beam is transmitted.
Parameters: - eps_1 – permittivity of the medium where the incident beam is propagating.
- eps_2 – permittivity of the other medium.
- mu1 – array of cosine of incident angles.
- npol – number of polarization.
Returns: the transmission matrix
-
_prepare_computation
(frequency, eps_1, eps_2, mu1)¶
-
diffuse_transmission_matrix
(frequency, eps_1, eps_2, mu_s, mu_i, dphi, npol)¶
-
__dict__
= mappingproxy({'__module__': 'smrt.interface.coherent_flat', '__doc__': 'A flat surface. The reflection is in the specular direction and the coefficient is calculated with the Fresnel coefficients\n\n', 'args': [], 'optional_args': {}, '__init__': <function CoherentFlat.__init__>, 'specular_reflection_matrix': <function CoherentFlat.specular_reflection_matrix>, 'diffuse_reflection_matrix': <function CoherentFlat.diffuse_reflection_matrix>, 'coherent_transmission_matrix': <function CoherentFlat.coherent_transmission_matrix>, '_prepare_computation': <function CoherentFlat._prepare_computation>, 'diffuse_transmission_matrix': <function CoherentFlat.diffuse_transmission_matrix>, '__dict__': <attribute '__dict__' of 'CoherentFlat' objects>, '__weakref__': <attribute '__weakref__' of 'CoherentFlat' objects>})¶
-
__doc__
= 'A flat surface. The reflection is in the specular direction and the coefficient is calculated with the Fresnel coefficients\n\n'¶
-
__module__
= 'smrt.interface.coherent_flat'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
smrt.interface.flat module¶
Implement the flat interface boundary condition between layers charcterized by their effective permittivities. The reflection and transmission are computed using the Fresnel coefficient.
-
class
Flat
(**kwargs)¶ Bases:
smrt.core.interface.Interface
A flat surface. The reflection is in the specular direction and the coefficient is calculated with the Fresnel coefficients
Build the interface
Parameters: **kwargs – parameters such as roughness_rms, corr_length, Q, N, etc are required or optional depending on the model.
See the document of the model.
-
args
= []¶
-
optional_args
= {}¶
-
specular_reflection_matrix
(frequency, eps_1, eps_2, mu1, npol)¶ - compute the reflection coefficients for an array of incidence angles (given by their cosine)
- in medium 1. Medium 2 is where the beam is transmitted.
Parameters: - eps_1 – permittivity of the medium where the incident beam is propagating.
- eps_2 – permittivity of the other medium.
- mu1 – array of cosine of incident angles.
- npol – number of polarization.
Returns: the reflection matrix
-
diffuse_reflection_matrix
(frequency, eps_1, eps_2, mu_s, mu_i, dphi, npol)¶
-
coherent_transmission_matrix
(frequency, eps_1, eps_2, mu1, npol)¶ - compute the transmission coefficients for an array of incidence angles (given by their cosine)
- in medium 1. Medium 2 is where the beam is transmitted.
Parameters: - eps_1 – permittivity of the medium where the incident beam is propagating.
- eps_2 – permittivity of the other medium.
- mu1 – array of cosine of incident angles.
- npol – number of polarization.
Returns: the transmission matrix
-
diffuse_transmission_matrix
(frequency, eps_1, eps_2, mu_s, mu_i, dphi, npol)¶
-
__doc__
= 'A flat surface. The reflection is in the specular direction and the coefficient is calculated with the Fresnel coefficients\n\n'¶
-
__module__
= 'smrt.interface.flat'¶
-
smrt.interface.geometrical_optics module¶
Implement the interface boundary condition under the Geometrical Approximation between layers charcterized by their effective permittivities. This approximation is suitable for surface with roughness much larger than the roughness scales, typically k*s >> 1 and k*l >> 1, where s the rms heigth and l the correlation length. The precise validity range must be investigated by the user, this code does not raise any warning. An important charcateristic of this approximation is that the scattering do not directly depend on frequency, the only (probably weak) dependence is through the permittivities of the media.
The model is parameterized by the mean_square_slope which can be calculated as mean_square_slope = 2*s**2/l**2 for surface with a Gaussian autocorrelation function. Other equations may exist for other autocorrelation function.
This implementation is largely based on Tsang and Kong, Scattering of Electromagnetic Waves: Advanced Topics, 2001 (Tsang_tomeIII in the following)
-
class
GeometricalOptics
(**kwargs)¶ Bases:
smrt.core.interface.Interface
A very rough surface.
Build the interface
Parameters: **kwargs – parameters such as roughness_rms, corr_length, Q, N, etc are required or optional depending on the model.
See the document of the model.
-
args
= ['mean_square_slope']¶
-
optional_args
= {'shadow_correction': True}¶
-
clip_mu
(mu)¶
-
specular_reflection_matrix
(frequency, eps_1, eps_2, mu1, npol)¶ - compute the reflection coefficients for an array of incidence angles (given by their cosine)
- in medium 1. Medium 2 is where the beam is transmitted.
Parameters: - eps_1 – permittivity of the medium where the incident beam is propagating.
- eps_2 – permittivity of the other medium
- mu1 – array of cosine of incident angles
- npol – number of polarization
Returns: the reflection matrix
-
diffuse_reflection_matrix
(frequency, eps_1, eps_2, mu_s, mu_i, dphi, npol)¶ - compute the reflection coefficients for an array of incident, scattered and azimuth angles
- in medium 1. Medium 2 is where the beam is transmitted.
Parameters: - eps_1 – permittivity of the medium where the incident beam is propagating.
- eps_2 – permittivity of the other medium
- mu1 – array of cosine of incident angles
- npol – number of polarization
Returns: the reflection matrix
-
ft_even_diffuse_reflection_matrix
(frequency, eps_1, eps_2, mu_s, mu_i, m_max, npol)¶
-
ft_even_diffuse_transmission_matrix
(frequency, eps_1, eps_2, mu_s, mu_i, m_max, npol)¶
-
coherent_transmission_matrix
(frequency, eps_1, eps_2, mu1, npol)¶ - compute the transmission coefficients for the azimuthal mode m
- and for an array of incidence angles (given by their cosine) in medium 1. Medium 2 is where the beam is transmitted.
Parameters: - eps_1 – permittivity of the medium where the incident beam is propagating.
- eps_2 – permittivity of the other medium
- mu1 – array of cosine of incident angles
- npol – number of polarization
Returns: the transmission matrix
-
diffuse_transmission_matrix
(frequency, eps_1, eps_2, mu_t, mu_i, dphi, npol)¶ - compute the transmission coefficients for an array of incident, scattered and azimuth angles
- in medium 1. Medium 2 is where the beam is transmitted.
Parameters: - eps_1 – permittivity of the medium where the incident beam is propagating.
- eps_2 – permittivity of the other medium
- mu_i – array of cosine of incident angles
- mu_t – array of cosine of transmitted wave angles
- npol – number of polarization
Returns: the transmission matrix
-
reflection_coefficients
(frequency, eps_1, eps_2, mu_i)¶
-
transmission_coefficients
(frequency, eps_1, eps_2, mu_i)¶
-
_integrate_coefficients
(mu, dphi, x)¶
-
__doc__
= 'A very rough surface.\n\n'¶
-
__module__
= 'smrt.interface.geometrical_optics'¶
-
-
shadow_function
(mean_square_slope, cotan)¶
smrt.interface.geometrical_optics_backscatter module¶
Implement the interface boundary condition under the Geometrical Approximation between layers charcterized by their effective permittivities. This code is
for backscatter only, that is, to use as a substrate and at low frequency when the backscatter is the main mecahnism, and conversely when mulitple scattering
and double bounce between snow and substrate are negligible. In any other case, it is recommended to use GeometricalOptics
.
The transmitted energy is also computed in an approximate way suitable for 1st order scattering. We use energy conservation to compute the total transmitted energy and consider that all this energy is transmitted in the refraction (specular) direction.
-
class
GeometricalOpticsBackscatter
(**kwargs)¶ Bases:
smrt.core.interface.Interface
A very rough surface.
Build the interface
Parameters: **kwargs – parameters such as roughness_rms, corr_length, Q, N, etc are required or optional depending on the model.
See the document of the model.
-
args
= ['mean_square_slope']¶
-
optional_args
= {'shadow_correction': True}¶
-
specular_reflection_matrix
(frequency, eps_1, eps_2, mu1, npol)¶ - compute the reflection coefficients for an array of incidence angles (given by their cosine)
- in medium 1. Medium 2 is where the beam is transmitted.
Parameters: - eps_1 – permittivity of the medium where the incident beam is propagating.
- eps_2 – permittivity of the other medium
- mu1 – array of cosine of incident angles
- npol – number of polarization
Returns: the reflection matrix
-
diffuse_reflection_matrix
(frequency, eps_1, eps_2, mu_s, mu_i, dphi, npol)¶ - compute the reflection coefficients for an array of incident, scattered and azimuth angles
- in medium 1. Medium 2 is where the beam is transmitted.
Parameters: - eps_1 – permittivity of the medium where the incident beam is propagating.
- eps_2 – permittivity of the other medium
- mu1 – array of cosine of incident angles
- npol – number of polarization
Returns: the reflection matrix
-
ft_even_diffuse_reflection_matrix
(frequency, eps_1, eps_2, mu_s, mu_i, m_max, npol)¶
-
coherent_transmission_matrix
(frequency, eps_1, eps_2, mu1, npol)¶ - compute the transmission coefficients for an array of incidence angles (given by their cosine)
- in medium 1. Medium 2 is where the beam is transmitted. While Geometrical Optics, we here consider that power not reflected is scattered in the specular transmitted direction. This is an approximation which is reasonable in the context of a “1st order” geometrical optics.
Parameters: - eps_1 – permittivity of the medium where the incident beam is propagating.
- eps_2 – permittivity of the other medium
- mu1 – array of cosine of incident angles
- npol – number of polarization
Returns: the transmission matrix
-
__doc__
= 'A very rough surface.\n\n'¶
-
__module__
= 'smrt.interface.geometrical_optics_backscatter'¶
-
smrt.interface.iem_fung92 module¶
Implement the interface boundary condition under IEM formulation provided by Fung et al. 1992. in IEEE TGRS. Use of this code requires special attention because of two issues:
1) it only computes the backscatter diffuse reflection as described in Fung et al. 1992, the specular reflection and the coherent transmission. It does not compute the full bi-static diffuse reflection and transmission. As a consequence it is only suitable when single scattering is dominant, usually at low frequency when the medium is weakly scattering. This happends when the main mechanism is the backscatter from the interface attenuated by the medium. Another case is when the rough surface is relatively smooth, the specular reflection is relatively strong and the energy can be scattered back by the medium (double bounce). For other situations, this code is not recommended.
2) Additionaly, IEM is known to work for a limited range of roughness. Usually it is considered valid for ks < 3 and ks*kw < sqrt(eps) where k is the wavenumber, s the rms height and l the correlation length. The code print a warning when out of this range. There is also limitation for smooth surfaces but no warning is printed.
Usage example:
- ::
# rms height and corr_length values work at 10 GHz substrate = make_soil(“iem_fung92”, “dobson85”, temperature=260,
roughness_rms=1e-3, corr_length=5e-2, autocorrelation_function=”exponential”, moisture=moisture, clay=clay, sand=sand, drymatter=drymatter)
-
class
IEM_Fung92
(**kwargs)¶ Bases:
smrt.core.interface.Interface
A moderate rough surface model with backscatter, specular reflection and transmission only. Use with care!
Build the interface
Parameters: **kwargs – parameters such as roughness_rms, corr_length, Q, N, etc are required or optional depending on the model.
See the document of the model.
-
args
= ['roughness_rms', 'corr_length']¶
-
optional_args
= {'autocorrelation_function': 'exponential', 'series_truncation': 10, 'warning_handling': 'print'}¶
-
specular_reflection_matrix
(frequency, eps_1, eps_2, mu1, npol)¶ - compute the reflection coefficients for an array of incidence angles (given by their cosine)
- in medium 1. Medium 2 is where the beam is transmitted.
Parameters: - eps_1 – permittivity of the medium where the incident beam is propagating.
- eps_2 – permittivity of the other medium
- mu1 – array of cosine of incident angles
- npol – number of polarization
Returns: the reflection matrix
-
check_validity
(ks, kl, eps_r)¶
-
fresnel_coefficients
(eps_1, eps_2, mu_i, ks, kl)¶ calculate the fresnel coefficients at the angle mu_i whatever is ks and kl according to the original formulation of Fung 1992
-
diffuse_reflection_matrix
(frequency, eps_1, eps_2, mu_s, mu_i, dphi, npol, debug=False)¶ - compute the reflection coefficients for an array of incident, scattered and azimuth angles
- in medium 1. Medium 2 is where the beam is transmitted.
Parameters: - eps_1 – permittivity of the medium where the incident beam is propagating.
- eps_2 – permittivity of the other medium
- mu1 – array of cosine of incident angles
- npol – number of polarization
Returns: the reflection matrix
-
W_n
(n, k)¶
-
ft_even_diffuse_reflection_matrix
(frequency, eps_1, eps_2, mu_s, mu_i, m_max, npol)¶
-
coherent_transmission_matrix
(frequency, eps_1, eps_2, mu1, npol)¶ - compute the transmission coefficients for the azimuthal mode m
- and for an array of incidence angles (given by their cosine) in medium 1. Medium 2 is where the beam is transmitted.
Parameters: - eps_1 – permittivity of the medium where the incident beam is propagating.
- eps_2 – permittivity of the other medium
- mu1 – array of cosine of incident angles
- npol – number of polarization
Returns: the transmission matrix
-
__doc__
= 'A moderate rough surface model with backscatter, specular reflection and transmission only. Use with care!\n\n'¶
-
__module__
= 'smrt.interface.iem_fung92'¶
-
smrt.interface.iem_fung92_brogioni10 module¶
Implement the interface boundary condition under IEM formulation provided by Fung et al. 1992. in IEEE TGRS with an extended domain of validity (for large roughness or correlation length) by switching the Fresnel coefficients according to Brogioni et al. 2010, IJRS (doi: 10.1080/01431160903232808). A better but more complex approach is given by Wu et al. 2003 (to be implemented).
Use of this code requires special attention.
-
class
IEM_Fung92_Briogoni10
(**kwargs)¶ Bases:
smrt.interface.iem_fung92.IEM_Fung92
A moderate rough surface model with backscatter, specular reflection and transmission only. Use with care!
Build the interface
Parameters: **kwargs – parameters such as roughness_rms, corr_length, Q, N, etc are required or optional depending on the model.
See the document of the model.
-
check_validity
(ks, kl, eps_r)¶
-
fresnel_coefficients
(eps_1, eps_2, mu_i, ks, kl)¶ calculate the fresnel coefficients at the angle mu_i or 0° depending on ks*kl. The transition is abrupt.
-
__doc__
= 'A moderate rough surface model with backscatter, specular reflection and transmission only. Use with care!\n\n'¶
-
__module__
= 'smrt.interface.iem_fung92_brogioni10'¶
-
smrt.interface.radar_calibration_sphere module¶
Surface with a backscatter of 4pi.
-
class
RadarCalibrationSphere
(**kwargs)¶ Bases:
smrt.core.interface.Interface
Build the interface
Parameters: **kwargs – parameters such as roughness_rms, corr_length, Q, N, etc are required or optional depending on the model.
See the document of the model.
-
args
= []¶
-
optional_args
= {}¶
-
specular_reflection_matrix
(frequency, eps_1, eps_2, mu1, npol)¶
-
diffuse_reflection_matrix
(frequency, eps_1, eps_2, mu_s, mu_i, dphi, npol)¶
-
ft_even_diffuse_reflection_matrix
(frequency, eps_1, eps_2, mu_s, mu_i, m_max, npol)¶
-
coherent_transmission_matrix
(frequency, eps_1, eps_2, mu1, npol)¶
-
__doc__
= None¶
-
__module__
= 'smrt.interface.radar_calibration_sphere'¶
-
smrt.interface.test_geometrical_optics module¶
smrt.interface.test_iem_fung92 module¶
smrt.interface.test_iem_fung92_brogioni10 module¶
smrt.interface.transparent module¶
A transparent interface (no reflection). Useful for the unit-test mainly.
-
class
Transparent
¶ Bases:
object
-
args
= []¶
-
optional_args
= {}¶
-
specular_reflection_matrix
(frequency, eps_1, eps_2, mu1, npol)¶ - compute the reflection coefficients for the azimuthal mode m
- and for an array of incidence angles (given by their cosine) in medium 1. Medium 2 is where the beam is transmitted.
Parameters: - eps_1 – permittivity of the medium where the incident beam is propagating.
- eps_2 – permittivity of the other medium
- mhu1 – array of cosine of incident angles
- npol – number of polarization
-
diffuse_reflection_matrix
(frequency, eps_1, eps_2, mu_s, mu_i, dphi, npol)¶
-
coherent_transmission_matrix
(frequency, eps_1, eps_2, mu1, npol)¶ - compute the transmission coefficients for the azimuthal mode m
- and for an array of incidence angles (given by their cosine) in medium 1. Medium 2 is where the beam is transmitted.
Parameters: - eps_1 – permittivity of the medium where the incident beam is propagating.
- eps_2 – permittivity of the other medium
- mu1 – array of cosine of incident angles
- npol – number of polarization
Returns: the transmission matrix
-
diffuse_transmission_matrix
(frequency, eps_1, eps_2, mu_s, mu_i, dphi, npol)¶
-
__dict__
= mappingproxy({'__module__': 'smrt.interface.transparent', 'args': [], 'optional_args': {}, 'specular_reflection_matrix': <function Transparent.specular_reflection_matrix>, 'diffuse_reflection_matrix': <function Transparent.diffuse_reflection_matrix>, 'coherent_transmission_matrix': <function Transparent.coherent_transmission_matrix>, 'diffuse_transmission_matrix': <function Transparent.diffuse_transmission_matrix>, '__dict__': <attribute '__dict__' of 'Transparent' objects>, '__weakref__': <attribute '__weakref__' of 'Transparent' objects>, '__doc__': None})¶
-
__doc__
= None¶
-
__module__
= 'smrt.interface.transparent'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
smrt.interface.vector3 module¶
-
class
vector3
¶ Bases:
object
-
__slot__
= ['x', 'y', 'z', 'norm', 'norm2']¶
-
static
from_xyz
(x, y, z)¶
-
static
from_angles
(norm, mu, phi)¶
-
__add__
(other)¶
-
__sub__
(other)¶
-
__mul__
(other)¶
-
__rmul__
(other)¶
-
__truediv__
(other)¶
-
cross
(other)¶
-
dot
(other)¶
-
__repr__
()¶ Return repr(self).
-
__dict__
= mappingproxy({'__module__': 'smrt.interface.vector3', '__slot__': ['x', 'y', 'z', 'norm', 'norm2'], 'from_xyz': <staticmethod object>, 'from_angles': <staticmethod object>, '__add__': <function vector3.__add__>, '__sub__': <function vector3.__sub__>, '__mul__': <function vector3.__mul__>, '__rmul__': <function vector3.__rmul__>, '__truediv__': <function vector3.__truediv__>, 'cross': <function vector3.cross>, 'dot': <function vector3.dot>, '__repr__': <function vector3.__repr__>, '__dict__': <attribute '__dict__' of 'vector3' objects>, '__weakref__': <attribute '__weakref__' of 'vector3' objects>, '__doc__': None})¶
-
__doc__
= None¶
-
__module__
= 'smrt.interface.vector3'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
Module contents¶
This module contains different type of boundary conditions between the layers. Currently only flat interfaces are implemented.
For developers
All the different type of interface must defined the methods: specular_reflection_matrix and coherent_transmission_matrix.
It is currently not possible to implement rough interface, a (small) change is needed in DORT. Please contact the authors.