smrt.rtsolver package¶

Submodules¶

smrt.rtsolver.dort module¶

The Discrete Ordinate and Eigenvalue Solver is a multi-stream solver of the radiative transfer model. It is precise but less efficient than 2 or 6 flux solvers. Different flavours of DORT (or DISORT) exist depending on the mode (passive or active), on the density of the medium (sparse media have trivial inter-layer boundary conditions), on the way the streams are connected between the layers and on the way the phase function is prescribed. The actual version is a blend between Picard et al. 2004 (active mode for sparse media) and DMRT-ML (Picard et al. 2013) which works in passive mode only for snow. The DISORT often used in optics (Stamnes et al. 1988) works only for sparse medium and uses a development of the phase function in Legendre polynomia on theta. The version used in DMRT-QMS (L. Tsang’s group) is similar to the present implementation except it uses spline interpolation to connect constant-angle streams between the layers although we use direct connection by varying the angle according to Snell’s law. A practical consequence is that the number of streams vary (due to internal reflection) and the value n_max_stream only applies in the most refringent layer. The number of outgoing streams in the air is usually smaller, sometimes twice smaller (depends on the density profile). It is important not to set too low a value for n_max_streams. E.g. 32 is usually fine, 64 or 128 are better but simulations will be much slower.

class DORT(n_max_stream=32, m_max=2, stream_mode='most_refringent', phase_normalization=True, error_handling='exception', process_coherent_layers=False, prune_deep_snowpack=None)¶

Bases: object

Discrete Ordinate and Eigenvalue Solver

Parameters:

Parameters:	n_max_stream – number of stream in the most refringent layer m_max – number of mode (azimuth) phase_normalization – the integral of the phase matrix should in principe be equal to the scattering coefficient. However, some emmodels do not respect this strictly. In general a small difference is due to numerical rounding and is acceptable, but a large difference rather indicates either a bug in the emmodel or input parameters that breaks the assumption of the emmodel. The most typical case is when the grain size is too big compared to wavelength for emmodels that rely on Rayleigh assumption. If this argument is to True (the default), the phase matrix is normalized to be coherent with the scattering coefficient, but only when the difference is moderate (0.7 to 1.3). If set to “force” the normalization is always performed. This option is dangerous because it may hide bugs or unappropriate input parameters (typically too big grains). If set to False, no normalization is performed. error_handling – If set to “exception” (the default), raise an exception in cause of error, stopping the code. If set to “nan”, return a nan, so the calculation can continue, but the result is of course unusuable and the error message is not accessible. This is only recommended for long simulations that sometimes produce an error. process_coherent_layers – Adapt the layers thiner than the wavelegnth using the MEMLS method. The radiative transfer theory is inadequate layers thiner than the wavelength and using DORT with thin layers is generally not recommended. In some parcticular cases (such as ice lenses) where the thin layer is isolated between large layers, it is possible to replace the thin layer by an equivalent reflective interface. This neglects scattering in the thin layer, which is acceptable in most case, because the layer is thin. To use this option and more generally to investigate ice lenses, it is recommended to read MEMLS documentation on this topic. prune_deep_snowpack – this value is the optical depth from which the layers are discarded in the calculation. It is to be use to accelerate the calculations for deep snowpacks or at high frequencies when the contribution of the lowest layers is neglegible. The optical depth is a good criteria to determine this limit. A value of about 6 is recommended. Use with care, especially values lower than 6.

n_max_stream – number of stream in the most refringent layer
m_max – number of mode (azimuth)
phase_normalization – the integral of the phase matrix should in principe be equal to the scattering coefficient. However, some emmodels do not respect this strictly. In general a small difference is due to numerical rounding and is acceptable, but a large difference rather indicates either a bug in the emmodel or input parameters that breaks the assumption of the emmodel. The most typical case is when the grain size is too big compared to wavelength for emmodels that rely on Rayleigh assumption. If this argument is to True (the default), the phase matrix is normalized to be coherent with the scattering coefficient, but only when the difference is moderate (0.7 to 1.3). If set to “force” the normalization is always performed. This option is dangerous because it may hide bugs or unappropriate input parameters (typically too big grains). If set to False, no normalization is performed.
error_handling – If set to “exception” (the default), raise an exception in cause of error, stopping the code. If set to “nan”, return a nan, so the calculation can continue, but the result is of course unusuable and the error message is not accessible. This is only recommended for long simulations that sometimes produce an error.
process_coherent_layers – Adapt the layers thiner than the wavelegnth using the MEMLS method. The radiative transfer theory is inadequate layers thiner than the wavelength and using DORT with thin layers is generally not recommended. In some parcticular cases (such as ice lenses) where the thin layer is isolated between large layers, it is possible to replace the thin layer by an equivalent reflective interface. This neglects scattering in the thin layer, which is acceptable in most case, because the layer is thin. To use this option and more generally to investigate ice lenses, it is recommended to read MEMLS documentation on this topic.
prune_deep_snowpack – this value is the optical depth from which the layers are discarded in the calculation. It is to be use to accelerate the calculations for deep snowpacks or at high frequencies when the contribution of the lowest layers is neglegible. The optical depth is a good criteria to determine this limit. A value of about 6 is recommended. Use with care, especially values lower than 6.

solve(snowpack, emmodels, sensor, atmosphere=None)¶: solve the radiative transfer equation for a given snowpack, emmodels and sensor configuration.

dort(m_max=0, special_return=False)¶

prepare_intensity_array(streams)¶

dort_modem_banded(m, streams, eigenvalue_solver, interfaces, intensity_down_m, compute_coherent_only=False, special_return=False)¶

muleye(x)¶

matmul(a, b, *args)¶

compiled_todiag¶

todiag(bmat, oi, oj, dmat)¶

extend_2pol_npol(x, npol)¶

class EigenValueSolver(ke, ks, ft_even_phase_function, mu, weight, m_max, normalization)¶

Bases: object

solve(m, compute_coherent_only, debug_A=False)¶

normalize(m, A)¶

class InterfaceProperties(frequency, interfaces, substrate, permittivity, streams, m_max, npol)¶

Bases: object

reflection_top(l, m, compute_coherent_only)¶

reflection_bottom(l, m, compute_coherent_only)¶

transmission_top(l, m, compute_coherent_only)¶

transmission_bottom(l, m, compute_coherent_only)¶

static combine_coherent_diffuse_matrix(coh, diff, m, compute_coherent_only)¶

normalize_diffuse_matrix(mat, mu_st, mu_i, weights)¶

class Streams¶: Bases: object

compute_stream(n_max_stream, permittivity, permittivity_substrate, mode='most_refringent')¶

gaussquad(n)¶

smrt.rtsolver.dort_nonormalization module¶

The Discrete Ordinate and Eigenvalue Solver is a multi-stream solver of the radiative transfer model. It is precise but less efficient than 2 or 6 flux solvers. Different flavours of DORT (or DISORT) exist depending on the mode (passive or active), on the density of the medium (sparse media have trivial inter-layer boundary conditions), on the way the streams are connected between the layers and on the way the phase function is prescribed. The actual version is a blend between Picard et al. 2004 (active mode for sparse media) and DMRT-ML (Picard et al. 2013) which works in passive mode only for snow. The DISORT often used in optics (Stamnes et al. 1988) works only for sparse medium and uses a development of the phase function in Legendre polynomia on theta. The version used in DMRT-QMS (L. Tsang’s group) is similar to the present implementation except it uses spline interpolation to connect constant-angle streams between the layers although we use direct connection by varying the angle according to Snell’s law. A practical consequence is that the number of streams vary (due to internal reflection) and the value n_max_stream only applies in the most refringent layer. The number of outgoing streams in the air is usually smaller, sometimes twice smaller (depends on the density profile). It is important not to set too low a value for n_max_stream. E.g. 32 is usually fine, 64 or 128 are better but simulations will be much slower.

class DORT(n_max_stream=32, m_max=2, stream_mode='most_refringent')¶

Bases: object

Discrete Ordinate and Eigenvalue Solver

Parameters:	n_max_stream – number of stream in the most refringent layer m_max – number of mode (azimuth)

solve(snowpack, emmodels, sensor, atmosphere=None)¶: solve the radiative transfer equation for a given snowpack, emmodels and sensor configuration.

dort(m_max=0, special_return=False)¶

prepare_intensity_array(outmu, outweight)¶

dort_modem_banded(m, n_stream, mu, weight, outmu, n_stream_substrate, intensity_down_m, compute_coherent_only=False, special_return=False)¶

fix_matrix(x)¶

muleye(x)¶

todiag(bmat, ij, dmat)¶

extend_2pol_npol(x, npol)¶

solve_eigenvalue_problem(m, ke, ft_even_phase, mu, weight)¶

compute_stream(n_max_stream, permittivity, permittivity_substrate, mode='most_refringent')¶

gaussquad(n)¶

smrt.rtsolver.nadir_lrm_altimetry module¶

class NadirLRMAltimetry(waveform_model=None, oversampling=10, return_oversampled=False, skip_pfs_convolution=False, return_contributions=False, theta_inc_sampling=1, return_theta_inc_sampling=False, error_handling='exception')¶

Bases: object

Solver based on Adams and Brown 1998 and Lacroix et al. 2008. Both models differ in the specific choices for the scattering and backscatter of the interface, but are similar in the way the waveform is calculated, which concerns the solver here.

Parameters:

Parameters:	oversampling – integer number defining the number of subgates used for the computation in each altimeter gate. This is equivalent to multiply the bandwidth by this number. It is used to perform more accurate computation. return_oversampled – by default the backscatter is returned for each gate. If set to True, the oversampled waveform is returned instead. See the ‘oversampling’ argument. return_contributions – return volume, surface and interface backscatter contributions in addition to the total backscatter.

oversampling – integer number defining the number of subgates used for the computation in each altimeter gate. This is equivalent to multiply the bandwidth by this number. It is used to perform more accurate computation.
return_oversampled – by default the backscatter is returned for each gate. If set to True, the oversampled waveform is returned instead. See the ‘oversampling’ argument.
return_contributions – return volume, surface and interface backscatter contributions in addition to the total backscatter.

solve(snowpack, emmodels, sensor, atmosphere=None)¶: solve the radiative transfer equation for a given snowpack, emmodels and sensor configuration.

convolve_with_PFS_PTR_PDF(t_gate, backscatter, t_inc_sample)¶

gate_depth(eps=None)¶: return gate depth that cover the snowpack for a regular time sampling

combined_depth_grid()¶

vertical_scattering_distribution(return_contributions, mu_i=1.0)¶

Compute the vertical backscattering distribution due to “grain” or volume scattering (symbol pvg in Eq 9 in Lacroix 2008) and

“interfaces” or ‘surface’ scattering (symbol pvl in Eq 9 in Lacroix 2008)

param mu: cosine of the incidence angles. Only the dependence on the surface scattering depend on mu_i

param mu:	cosine of the incidence angles. Only the dependence on the surface scattering depend on mu_i

PFS_numerical(tau)¶

fill_forward(a, where, axis=-1)¶

fill(a, where, novalue=0)¶

smrt.rtsolver.test_dort module¶

setup_snowpack()¶

setup_snowpack_with_DH()¶

setup_2layer_snowpack()¶

test_noabsoprtion()¶

test_returned_theta()¶

test_selectby_theta()¶

test_depth_hoar_stream_numbers()¶

test_2layer_pack()¶

test_shallow_snowpack()¶

smrt.rtsolver.waveform_model module¶

class WaveformModel¶: Bases: object

class Brown1977(sensor, numerical_convolution=False)¶

Bases: smrt.rtsolver.waveform_model.WaveformModel

Antenna Gain formulation used by Brown 1977. The formula is exp(2/gamma * sin(theta)**2) for the perfect nadir case, but is also available with off-nadir angles.

G(theta, phi)¶

PFS(tau, surface_slope=0, shift_nominal_gate=True)¶

PFS_PTR_PDF(tau, sigma_surface=0, surface_slope=0)¶

compute the convolution of the PFS and PTR

Parameters:	sensor – sensor to apply the antenna gain tau – time to which to compute the PFSxPTR sigma_surface – RMS height of the surface topography (meter)

class Newkrik1992(sensor)¶

Bases: smrt.rtsolver.waveform_model.WaveformModel

Antenna Gain formulation proposed by Newkrik and Brown, 1992. Compared to the classical Bronw 1977, it takes into account the asymmetry of the antenna pattern in the co and cross-track direction.

G(theta, phi)¶

PFS(sensor, tau)¶

Module contents¶

This directory contains different solvers of the radiative transfer equation. Based on the electromagnetic properties of each layer computed by the EM model, these RT solvers compute the emission and propagation of energy in the medium up to the surface (the atmosphere is usually dealt with independently in dedicated modules in smrt.atmosphere).

The solvers differ by the approximations and numerical methods. dort is currently the most accurate and recommended in most cases unless the computation time is a constraint.

The selection of the solver is done with the make_model() function.

For Developers

To experiment with DORT, we recommand to copy the file dort.py to e.g. dort_mytest.py so it is immediately available through make_model().

To develop a new solver that will be accessible by the make_model() function, you need to add a file in this directory, give a look at dort.py which is not simple but the only one at the moment. Only the method solve needs to be implemented. It must return a Result instance with the results. Contact the core developers to have more details.