Technical documentation

RT1-module

Core module for implementation of 1st order scattering model using arbitrary BRDF and phase functions

References

Quast & Wagner (2016): doi:10.1364/AO.55.005379

class rt1.rt1.RT1(I0, t_0, t_ex, p_0, p_ex, V=None, SRF=None, fn_input=None, _fnevals_input=None, geometry='mono', bsf=0.0, param_dict={}, lambda_backend='symengine', int_Q=True, verbosity=1)

Bases: object

Main class to perform RT-simulations

Parameters

  • I0 (scalar(float)) – incidence intensity

  • t_0 (array_like(float)) – array of incident zenith-angles in radians

  • p_0 (array_like(float)) – array of incident azimuth-angles in radians

  • t_ex (array_like(float)) – array of exit zenith-angles in radians (if geometry is ‘mono’, theta_ex is automatically set to t_0)

  • p_ex (array_like(float)) – array of exit azimuth-angles in radians (if geometry is ‘mono’, phi_ex is automatically set to p_0 + np.pi)

  • V (rt1.volume) – random object from rt1.volume class

  • SRF (surface) – random object from rt1.surface class

  • fn_input (array_like(sympy expression), optional (default = None)) – optional input of pre-calculated array of sympy-expressions to speedup calculations where the same fn-coefficients can be used. if None, the coefficients will be calculated automatically at the initialization of the RT1-object

  • _fnevals_input (callable, optional (default = None)) – optional input of pre-compiled function to numerically evaluate the fn_coefficients. if None, the function will be compiled using the fn-coefficients provided. Note that once the _fnevals function is provided, the fn-coefficients are no longer needed and have no effect on the calculated results!

  • geometry (str (default = 'vvvv')) –

    4 character string specifying which components of the angles should be fixed or variable. This is done to significantly speed up the evaluation-process of the fn-coefficient generation

    The 4 characters represent in order the properties of:

    t_0, t_ex, p_0, p_ex

    • ’f’ indicates that the angle is treated ‘fixed’ (i.e. as a numerical constant)

    • ’v’ indicates that the angle is treated ‘variable’ (i.e. as a sympy-variable)

    • Passing geometry = ‘mono’ indicates a monstatic geometry (i.e.: t_ex = t_0, p_ex = p_0 + pi) If monostatic geometry is used, the input-values of t_ex and p_ex have no effect on the calculations!

    For detailed information on the specification of the geometry-parameter, please have a look at the “Evaluation Geometries” section of the documentation: (http://rt1.readthedocs.io/en/latest/model_specification.html#evaluation-geometries)

  • bsf (float (default = 0.)) – fraction of bare-soil contribution (no attenuation due to vegetation)

  • param_dict (dict (default = {})) – a dictionary to assign numerical values to sympy.Symbols appearing in the definitions of V and SRF.

  • lambda_backend (str (default = 'symengine' if possible, else 'sympy')) –

    indicator to select the module that shall be used to compile a function for numerical evaluation of the fn-coefficients.

    possible values are:

    • ’sympy’ : sympy.lambdify is used to compile the _fnevals function

    • ’symengine’ : symengine.LambdifyCSE is used to compile the _fnevals function. This results in considerable speedup for long fn-coefficients

  • int_Q (bool (default = True)) – indicator whether the interaction-term should be calculated or not

  • verbosity (int) –

    select the verbosity level of the module to get status-reports

    • 0 : print nothing

    • 1 : print some infos during runtime

    • 2 : print more

    • >=3 : print all

calc()

Perform actual calculation of bistatic scattering at top of the random volume (z=0) for the specified geometry. For details please have a look at the documentation: (http://rt1.readthedocs.io/en/latest/theory.html#first-order-solution-to-the-rte)

Returns

  • Itot (array_like(float)) – Total scattered intensity (Itot = Isurf + Ivol + Iint)

  • Isurf (array_like(float)) – Surface contribution

  • Ivol (array_like(float)) – Volume contribution

  • Iint (array_like(float)) – Interaction contribution

property fn
interaction()

Numerical evaluation of the interaction-contribution (http://rt1.readthedocs.io/en/latest/theory.html#interaction_contribution)

Returns

- – Numerical value of the interaction-contribution for the given set of parameters

Return type

array_like(float)

jacobian(dB=False, sig0=False, param_list=['omega', 'tau', 'NormBRDF'])

Returns the jacobian of the total backscatter with respect to the parameters provided in param_list. (default: param_list = [‘omega’, ‘tau’, ‘NormBRDF’])

The jacobian can be evaluated for measurements in linear or dB units, and for either intensity- or sigma_0 values.

Note

The contribution of the interaction-term is currently not considered in the calculation of the jacobian!

Parameters

  • dB (boolean (default = False)) –

    Indicator whether linear or dB units are used. The applied relation is given by:

    dI_dB(x)/dx = 10 / [log(10) * I_linear(x)] * dI_linear(x)/dx

  • sig0 (boolean (default = False)) –

    Indicator wheather intensity- or sigma_0-values are used The applied relation is given by:

    sig_0 = 4 * pi * cos(inc) * I

    where inc denotes the incident zenith-angle and I is the corresponding intensity

  • param_list (list) –

    a list of strings that correspond to the parameters for which the jacobian should be evaluated.

    possible values are: ‘omega’, ‘tau’ ‘NormBRDF’ and any string corresponding to a sympy.Symbol used in the definition of V or SRF

Returns

jac – The jacobian of the total backscatter with respect to omega, tau and NormBRDF

Return type

array-like(float)

property p_0
property p_ex
prv(v, msg)

function to set print output based on verbosity level v. possible values for v:

  • 0 : print nothing

  • 1 : print some infos during runtime

  • 2 : print more

  • >=3 : print all

Parameters

  • v (int) – the verbosity.

  • msg (str) – the message to be printed.

surface()

Numerical evaluation of the surface-contribution (http://rt1.readthedocs.io/en/latest/theory.html#surface_contribution)

Returns

- – Numerical value of the surface-contribution for the given set of parameters

Return type

array_like(float)

surface_curv(dB=False, sig0=False)

Numerical evaluation of the curvature (d^2I_s/dt_0^2) of the (!monostatic!) surface-contribution

Parameters

  • dB (bool (default = False)) – indicator if the derivative is calculated for the dB values or for the linear values

  • sig0 (bool (default = False)) – indicator if the derivative is calculated for the intensity (False) or for sigma_0 = 4 * pi * cos(t_0) * intensity (True)

Returns

- – Numerical value of the monostatic curvature of the surface-contribution

Return type

array_like(float)

surface_slope(dB=False, sig0=False)

Numerical evaluation of the slope (dI_s/dt_0) of the (!monostatic!) surface-contribution

Parameters

  • dB (bool (default = False)) – indicator if the derivative is calculated for the dB values or for the linear values

  • sig0 (bool (default = False)) – indicator if the derivative is calculated for the intensity (False) or for sigma_0 = 4 * pi * cos(t_0) * intensity (True)

Returns

- – Numerical value of the monostatic slope of the surface-contribution

Return type

array_like(float)

property t_0
property t_ex
tot_curv(sig0=False, dB=False)

numerical value of the (!monostatic!) curvature of total contribution (surface + volume)

Parameters

  • dB (bool (default = False)) – indicator if the derivative is calculated for the dB values or for the linear values

  • sig0 (bool (default = False)) – indicator if the derivative is calculated for the intensity (False) or for sigma_0 = 4 * pi * cos(t_0) * intensity (True)

Returns

- – Numerical value of the monostatic curvature of the total-contribution

Return type

array_like(float)

tot_slope(sig0=False, dB=False)

numerical value of the (!monostatic!) slope of total contribution (surface + volume)

Parameters

  • dB (bool (default = False)) – indicator if the derivative is calculated for the dB values or for the linear values

  • sig0 (bool (default = False)) – indicator if the derivative is calculated for the intensity (False) or for sigma_0 = 4 * pi * cos(t_0) * intensity (True)

Returns

- – Numerical value of the monostatic slope of the total-contribution

Return type

array_like(float)

volume()

Numerical evaluation of the volume-contribution (http://rt1.readthedocs.io/en/latest/theory.html#volume_contribution)

Returns

- – Numerical value of the volume-contribution for the given set of parameters

Return type

array_like(float)

volume_curv(dB=False, sig0=False)

Numerical evaluation of the curvature (d^2I_s/dt_0^2) of the (!monostatic!) volume-contribution

Parameters

  • dB (bool (default = False)) – indicator if the derivative is calculated for the dB values or for the linear values

  • sig0 (bool (default = False)) – indicator if the derivative is calculated for the intensity (False) or for sigma_0 = 4 * pi * cos(t_0) * intensity (True)

Returns

- – Numerical value of the monostatic curvature of the volume-contribution

Return type

array_like(float)

volume_slope(dB=False, sig0=False)

Numerical evaluation of the slope (dI_v/dt_0) of the (!monostatic!) volume-contribution

Parameters

  • dB (bool (default = False)) – indicator if the derivative is calculated for the dB values or for the linear values

  • sig0 (bool (default = False)) – indicator if the derivative is calculated for the intensity (False) or for sigma_0 = 4 * pi * cos(t_0) * intensity (True)

Returns

- – Numerical value of the monostatic slope of the volume-contribution

Return type

array_like(float)

rtplots-module

rtfits-module

rtparse-module

Scatter-module

Define general object for scattering calculations

class rt1.scatter.Scatter

Bases: object

The basis object for any Surface and Volume objects

scat_angle(t_0, t_ex, p_0, p_ex, a)

Function to return the generalized scattering angle with respect to the given zenith-angles (http://rt1.readthedocs.io/en/latest/theory.html#equation-general_scat_angle)

Standard-choices assigned in the volume- and surface class:

  • Surface: a=[ 1,1,1] … pi-shifted scattering angle cos[t_0]*cos[t_ex] + sin[t_0]*sin[t_ex]*cos[p_0 - p_ex]

  • Volume: a=[-1,1,1] … ordinary scattering angle -cos[t_0]*cos[t_ex] + sin[t_0]*sin[t_ex]*cos[p_0 - p_ex]

Note

The scattering angle is defined with respect to the incident zenith-angle t_0, and not with respect to the incidence-angle in a spherical coordinate system (t_i)! The two definitions are related via t_i = pi - t_0

Parameters

  • t_0 (array_like(float)) – incident zenith-angle

  • p_0 (array_like(float)) – incident azimuth-angle

  • t_ex (array_like(float)) – exit zenith-angle

  • p_ex (array_like(float)) – exit azimuth-angle

  • a ([ float , float , float ]) – generalized scattering angle parameters

Returns

the generalized scattering angle

Return type

float

Surface-module

Volume-module

processing_config