isofit.surface.surface_multicomp
================================

.. py:module:: isofit.surface.surface_multicomp


Classes
-------

.. autoapisummary::

   isofit.surface.surface_multicomp.MultiComponentSurface


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

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

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


   A model of the surface based on a collection of multivariate
   Gaussians, with one or more equiprobable components and full
   covariance matrices.

   To evaluate the probability of a new spectrum, we calculate the
   Mahalanobis distance to each component cluster, and use that as our
   Multivariate Gaussian surface model.


   .. py:attribute:: components


   .. py:attribute:: n_comp


   .. py:attribute:: wl


   .. py:attribute:: n_wl


   .. py:attribute:: normalize


   .. py:attribute:: selection_metric


   .. py:attribute:: select_on_init


   .. py:attribute:: refwl


   .. py:attribute:: idx_ref


   .. py:attribute:: statevec_names


   .. py:attribute:: idx_surface


   .. py:attribute:: analytical_iv_idx


   .. py:attribute:: bounds


   .. py:attribute:: scale


   .. py:attribute:: init


   .. py:attribute:: idx_lamb


   .. py:attribute:: n_state


   .. py:attribute:: full_glint
      :value: False



   .. py:method:: component(x, geom)

      We pick a surface model component using the Mahalanobis distance.

      This always uses the Lambertian (non-specular) version of the
      surface reflectance. If the forward model initialize via heuristic
      (i.e. algebraic inversion), the component is only calculated once
      based on that first solution. That state is preserved in the
      geometry object.



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

      Mean of prior distribution, calculated at state x. We find
      the covariance in a normalized space (normalizing by z) and then un-
      normalize the result for the calling function. This always uses the
      Lambertian (non-specular) version of the surface reflectance.



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

      Covariance of prior distribution, calculated at state x. We find
      the covariance in a normalized space (normalizing by z) and then un-
      normalize the result for the calling function.



   .. 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.



   .. 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.



   .. 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



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

      Summary of state vector.