isofit.surface.surface_lut
==========================

.. py:module:: isofit.surface.surface_lut


Classes
-------

.. autoapisummary::

   isofit.surface.surface_lut.LUTSurface


Module Contents
---------------

.. py:class:: LUTSurface(full_config: Config)

   Bases: :py:obj:`isofit.surface.surface.Surface`


   A model of the surface based on an N-dimensional lookup table
   indexed by one or more state vector elements.  We calculate the
   reflectance by multilinear interpolation.  This is good for
   surfaces like aquatic ecosystems or snow that can be
   described with just a few degrees of freedom.

   The lookup table must be precalculated based on the wavelengths
   of the instrument.  It is stored with other metadata in a matlab-
   format file. For an n-dimensional lookup table, it contains the
   following fields:
     - grids: an object array containing n lists of gridpoints
     - data: an n+1 dimensional array containing the reflectances
        for each gridpoint
     - bounds: a list of n [min,max] tuples representing the bounds
        for all state vector elements
     - statevec_names: an array of n strings representing state
        vector element names
     - mean: an array of n prior mean values, one for each state
        vector element
     - sigma: an array of n prior standard deviations, one for each
        state vector element
     - scale: an array of n scale values, one for each state vector
        element



   .. py:attribute:: lut_grid


   .. py:attribute:: lut_names


   .. py:attribute:: statevec_names


   .. py:attribute:: data


   .. py:attribute:: wl


   .. py:attribute:: n_wl


   .. py:attribute:: bounds


   .. py:attribute:: scale


   .. py:attribute:: init


   .. py:attribute:: mean


   .. py:attribute:: sigma


   .. py:attribute:: n_state


   .. py:attribute:: n_lut


   .. py:attribute:: idx_lut


   .. py:attribute:: idx_lamb


   .. py:attribute:: itp


   .. py:attribute:: analytical_iv_idx


   .. py:method:: xa(x_surface, geom)

      Mean of prior distribution.



   .. py:method:: Sa(x_surface, geom)

      Covariance of prior distribution, calculated at state x.



   .. py:method:: Sb()

      Uncertainty due to unmodeled variables.



   .. py:method:: fit_params(rfl_meas, geom, *args)

      Given a reflectance estimate, fit a state vector.



   .. py:method:: calc_rfl(x_surface, geom)

      Non-Lambertian reflectance.

      Inputs:
      x_surface : np.ndarray
          Surface portion of the statevector element
      geom : Geometry
          Isofit geometry object

      Outputs:
      rho_dir_dir : np.ndarray
          Reflectance quantity for downward direct photon paths
      rho_dif_dir : np.ndarray
          Reflectance quantity for downward diffuse photon paths

      .. note::

         We do not handle direct and diffuse photon path reflectance
         quantities differently for the multicomponent surface model.
         This is why we return the same quantity for both outputs.



   .. py:method:: calc_lamb(x_surface, geom)

      Lambertian reflectance.  Be sure to incorporate BRDF-related
      LUT dimensions such as solar and view zenith.



   .. py:method:: drfl_dsurface(x_surface, geom)

      Partial derivative of reflectance with respect to state vector,
      calculated at x_surface.



   .. py:method:: dlamb_dsurface(x_surface, geom)

      Partial derivative of Lambertian reflectance with respect to
      state vector, calculated at x_surface.  We calculate the
      reflectance with multilinear interpolation so the finite
      difference derivative is exact.



   .. py:method:: drdn_drfl(L_tot, s_alb, rho_dif_dir)

      Partial derivative of radiance with respect to
      surface reflectance



   .. py:method:: calc_Ls(x_surface, geom)

      Emission of surface, as a radiance.



   .. py:method:: dLs_dsurface(x_surface, geom)

      Partial derivative of surface emission with respect to
      state vector, calculated at x_surface.



   .. py:method:: drdn_dLs(t_total_up)

      Partial derivative of radiance with respect to
      surface emission



   .. py:method:: drdn_dsurface(rho_dif_dir, drfl_dsurface, dLs_dsurface, s_alb, t_total_up, L_tot, L_down_dir)

      Derivative of radiance with respect to
      full surface vector



   .. py:method:: analytical_model(background, L_down_dir, L_down_dif, L_tot, geom, L_dir_dir=None, L_dir_dif=None, L_dif_dir=None, L_dif_dif=None)

      Linearization of the surface reflectance terms to use in the
      AOE inner loop (see Susiluoto, 2025). We set the quadratic
      spherical albedo term to a constant background, which
      simplifies the linearization
      background - s * rho_bg

      NOTE FOR SURFACE_LUT:
      This assumes that the only surface statevector terms are
      surface reflectance terms. Any additional surface state elements
      have to be explicitely handled in this function. How they are
      handled is dependent on the nature of the surface rfl model.
      The n-columns of H is equal to the number of statevector elements.
      Here, set to the number of wavelengths.



   .. py:method:: summarize(x_surface, geom)

      Summary of state vector.