.. raw:: html
Functional
This page describes the :ref:`FunctionalModel ` derived classes. .. _functional-derived-classes: Derived classes *************** .. _hapke-model: Hapke Model ----------- .. class:: HapkeModel (geometries, variant, adapter, theta_bar_scaling, b0, h) The class :class:`HapkeModel` is a representation of the Hapke's photometric model. For more details check the scientific `documentation `_. There are two variants of the Hapke's formulation, the initial 1993 version and the 2002 version. The calculation in the class are initially designed for a 4 parameters model. The class can use a adapter to adapt different variants of the model for example : the model with 3 or 6 parameters. See : Hapke B. 1993 Theory of Reflectance and Emittance Spectroscopy. Topics in Remote Sensing. Cambridge University Press, Cambridge, UK. See : Schmidt F. and Fernando J. 2015 Realistic uncertainties on Hapke model parameters from photometric measurement. Icarus, 260 :73 - 93, 2015. :param ndarray of shape (n_geometries,3) geometries: The matrix of geometries that will be used by the model. The shape of the Numpy array should be (n_geometries,3). The three geometric angles must be this particular order : - At [:,0] the incidence angle (*inc*) also called the solar zenith angle (*sza*) - At [:,1] the emergence angle (*eme*) also called the vertical zenith angle (*vza*) - At [:,2] the phi angle (*phi*) Thus the geometries matrix should look like this >>> geometries array([ [inc_0, eme_0, phi_0], [inc_1, eme_1, phi_1], [inc_2, eme_2, phi_2], ... [inc_n, eme_n, phi_n]]) :param string variant: The variant a the Hapke's model among {'1993', '2002'}. :param string adapter: This argument allows to adapt the Hapke's model parameter number among {'three', 'four', 'six'}. :param float theta_bar_scaling: Value used to transform theta_bar between physical and mathematical spaces. :param float b0: The amplitude of the opposition effect :param float h: The angular width of the opposition effect .. _shkuratov-model: Shkuratov Model --------------- .. class:: ShkuratovModel (geometries, variant, scaling_coeffs, offset) The class :class:`ShkuratovModel` is a representation of the Shkuratov's photometric model. For more details check the scientific `documentation `_. There are two variants of the Shkuratov's formulation, the original model with 5 parameters and a reduced model with 3 parameters. The *scaling_coeffs* and *offset* arguments are to perform affine transformation between the physical space and the mathematical space, such as, :math:`(\text{toPhysic}(x))_{1 \leq i \leq L} = (\text{scaling_coeffs}_i x_i + \text{offset}_i)_{1 \leq i \leq L}`. :param ndarray of shape (n_geometries,3) geometries: The matrix of geometries that will be used by the model. The shape of the Numpy array should be (n_geometries,3). The three geometric angles must be this particular order : - At [:,0] the incidence angle (*inc*) also called the solar zenith angle (*sza*) - At [:,1] the emergence angle (*eme*) also called the vertical zenith angle (*vza*) - At [:,2] the phi angle (*phi*) Thus the geometries matrix should look like this >>> geometries array([ [inc_0, eme_0, phi_0], [inc_1, eme_1, phi_1], [inc_2, eme_2, phi_2], ... [inc_n, eme_n, phi_n]]) :param string variant: The variant a the Hapke's model among {'3p', '5p'}. '3p' refers to the 3-parameters variant- and '5p' refers to the original 5-parameters model. :param ndarray of shape (L,) scaling_coeffs: A set of coefficients used in the transformation between physical and mathematical spaces. :param ndarray of shape (L,) offset: A set of offsets used in the transformation between physical and mathematical spaces .. _external-python-model: External Python Model --------------------- .. class:: ExternalPythonModel (className, fileName, filePath) The PlanetGLLiM software allows you to edit your own physical model. To do so you must provide a Python file (.py) describing your physical model as a Python class. The template of such python module is described below. >>> # IMPORTS >>> import numpy as np >>> >>> class PhysicalModel(object): >>> """ This is a python class defining a functional model. >>> >>> This class is composed of 5 mandatory functions: >>> - F: the functional model F describing the physical model. F takes photometries as arguments and return reflectances >>> - getDimensionY: returns the dimension of Y (reflectances) >>> - getDimensionX: return de dimension of X (photometries) >>> - toPhysic: converts the X data from mathematical framework (0>> - fromPhysic: converts the X data from physical framework to mathematical framework (0>> >>> Note that some class constants, other functions and class constructors can be declared. >>> >>> Geometries : if your physical model requires geometries as with Shkuratov, the structure and the values of the geometries >>> must be declared within this Python file. >>> >>> See the Planet-Gllim documentation for more informations (https://gitlab.inria.fr/xllim/planet-gllim/-/wikis/home) >>> """ >>> >>> ################################################################################################# >>> ## CLASS CONSTANTS (OPTIONAL) ## >>> ################################################################################################# >>> >>> # Geometries of the physical model MUST be declared here - directly in the python file. >>> >>> >>> ################################################################################################# >>> ## CORE FUNCTIONS (MANDATORY) ## >>> ################################################################################################# >>> >>> def F(self): >>> pass >>> >>> def getDimensionY(self): >>> pass >>> >>> def getDimensionX(self): >>> pass >>> >>> def toPhysic(self): >>> pass >>> >>> def fromPhysic(self): >>> pass >>> >>> >>> ################################################################################################# >>> ## OTHER FUNCTIONS (OPTIONAL) ## >>> ################################################################################################# >>> >>> def __init__(self, *args, **kwargs): >>> pass >>> >>> def optional_but_useful_function(): >>> pass If the functional model shows interest it can be added in further development in xLLiM as a built-in class to improve speed performance. :param string className: The exact name of the python class. :param string fileName: The exact name of the python module without the .py extension. :param string filePath: The directory path of the python module. .. _test-model: Test Model ---------- .. class:: TestModel () The class :class:`TestModel` is low-dimensional functional model implemented in order to test the GLLiM method with simple but not trivial example. The functional F is designed so as to exhibit 2 solutions with D=9 and L=4. :math:`F = A ◦ G ◦ H`, where - :math:`A` is a (DxL) injective matrix, .. math:: A = \frac{1}{2} \begin{pmatrix} 1 & 2 & 2 & 1 \\ 0 & 0.5 & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 3 \\ 0.2 & 0 & 0 & 0 \\ 0 & -0.5 & 0 & 0 \\ -0.2 & 0 & -1 & 0 \\ -1 & 0 & 2 & 0 \\ 0 & 0 & 0 & -0.7 \end{pmatrix} - :math:`G(x)` = :math:`(exp(x_1), exp(x_2), exp(x_3), exp(x_4))` and - :math:`H(x)` = :math:`(x_1, x_2, 4(x_3-0.5)^2, x_4)`. The resulting F is therefore non-linear and yields two solutions for each observation, denoted by xobs,1 and xobs,2 = 1 - xobs,1.