.. _examples:


Getting Started
===============

To build your an instrument simulation you will need,

    #. An instance of class :ref:`instrument_class`.
    #. An instance of class :ref:`platform_class`.
    #. An instance of class :ref:`forwardmodel_class`.
    #. An instance of sasktran.Atmosphere

These components, once configured, can radiances at the front aperture of the instrument.

Step 1: Make the Instrument
---------------------------

To make the instrument we are going to derive an instrument class from :class:`~skimpy.Instrument`. Within the constructor of the class
we are goint to define 2 fields of view and 3 spectral point spread functions. We will then define 6 spectral windows using various
combinations of the fields of view and spectral point spread functions::

    import math
    from skimpy import FOV_Rectangle, Wavelength_GaussianPSF, SpectralWindow, Instrument

    #------------------------------------------------------------------------------
    #           TestInstrument
    #------------------------------------------------------------------------------

    class TestInstrument( Instrument ):
        """
        A test instrument class to demonstrate usage.
        """

        def __init__(self ):

            super().__init__(  )
            self.configure_front_end_fields_of_view()

        #------------------------------------------------------------------------------
        #           configure_front_end_fields_of_view
        #------------------------------------------------------------------------------

        def configure_front_end_fields_of_view(self):

            aperture_area_cms = 25.0

            fov0 = FOV_Rectangle(Hrange=( 5, math.radians(0.0), math.radians(0.5)),                     # Horizontal field of view is 5 points spanning 0.0 to 0.5 degrees in instrument control frame
                                 Vrange=( 3, math.radians(0.0), math.radians(20.0 / 3600.0)))           # Vertical field of view is 3 points spanning 0.0 to 20 arc seconds in instrument control frame

            fov1 = FOV_Rectangle( Hrange=(5, math.radians(0.2), math.radians(0.5)),                    # Horizontal field of view is 5 points 0.2 to 0.5 degrees in instrument control frame
                                  Vrange=(3, math.radians(0.0), math.radians(20.0 / 3600.0)))           # Vertical field of view is 3 points spanning 0.0 to 20 arc seconds in instrument control frame

            fovidx0 = self.add_field_of_view( fov0 )                                                    # define the different fields of view
            fovidx1 = self.add_field_of_view( fov1 )                                                    # used by this instrument. Define in instrument control frame coordinates

            wavidx0 = self.add_wavelength_range( Wavelength_GaussianPSF( 30, 450.0, 0.3, rtm_processing_scheme='hybrid' ))         # wavelength region 1. 30 wavelengths across 450 nanometers, FWHM = 0.53 nm
            wavidx1 = self.add_wavelength_range( Wavelength_GaussianPSF( 30, 452.0, 0.4, rtm_processing_scheme='preconvolved'))    # The code will spectrally integrate over each wavelength region
            wavidx2 = self.add_wavelength_range( Wavelength_GaussianPSF( 30, 454.0, 0.5, rtm_processing_scheme='hybrid' ))

            self.add_spectral_window( SpectralWindow( self, fovidx0, wavidx0, aperture_area_cms) )                                  # define the spectral windows used in the simulation
            self.add_spectral_window( SpectralWindow( self, fovidx0, wavidx1, aperture_area_cms) )                                  # Each spectral window is a combination of a wavelength range and a field of view
            self.add_spectral_window( SpectralWindow( self, fovidx0, wavidx2, aperture_area_cms) )                                  # The front-end radiance will be integrated over the eavelength range and the field of view
            self.add_spectral_window( SpectralWindow( self, fovidx1, wavidx0, aperture_area_cms) )
            self.add_spectral_window( SpectralWindow( self, fovidx1, wavidx1, aperture_area_cms) )
            self.add_spectral_window( SpectralWindow( self, fovidx1, wavidx2, aperture_area_cms) )

Step 2. Make the platform
--------------------------
We are going to make a simple platform located at 600 km above (50N, 0E). It will look due North
at the tangent heights from 0 to 40 km in steps of 2 km::

    import numpy as np
    from skimpy import Platform

    #------------------------------------------------------------------------------
    #           class TestPlatform
    #------------------------------------------------------------------------------

    class TestPlatform( Platform ):

        def __init__(self):
            super().__init__()
            self.make_observation_set()

        #------------------------------------------------------------------------------
        #           step_to_next_observation
        #------------------------------------------------------------------------------

        def make_observation_set(self):

            self.clear_states()                                                         # Clear the current observation set
            t       = np.datetime64('2018-07-31T12:15:35.023456')                       # Set the time of the observations
            heights = np.arange( 0.0, 40000.0, 2000)                                    # set the required tangent height, 0 to 40 km in 2 km steps
            bearing = 0.0                                                               # Set the geographic bearing
            self.set_nadir_mode( False )                                                # Ensure we are not using nadir mode, ie. limb mode
            self.set_platform_location(latlonheightandt=(50, 0, 600000.0, t))           # Set the location of the platform to (50N, 0E)
            self.add_tangent_heights  ( heights, bearing, clear_states = True)          # Set the location of the platform


Step 3. Create the Forward Model and the Atmosphere
---------------------------------------------------
Next we must create the atmosphere and forward model::


    import sasktran as sk

    #------------------------------------------------------------------------------
    #           create_model_and_atmosphere
    #------------------------------------------------------------------------------

    def create_model_and_atmosphere()

        atmosphere          = sk.Atmosphere()
        atmosphere['air']   = sk.Species(sk.Rayleigh(), sk.MSIS90())
        atmosphere['ozone'] = sk.Species(sk.O3DBM(), sk.Labow())
        model               = ForwardModel('HR')
        return mode, atmosphere

Step 4. Execute and Plot
-------------------------
  And finally we put it all together so we can run it and make some plots::


    import matplotlib.pyplot as plt

    def test_model():

        model, atmosphere = screate_model_and_atmosphere()
        instrument        = TestInstrument()
        platform          = TestPlatform()
        model.calculate_radiance( instrument, platform, atmosphere)

        plt.figure(1)
        for window in instrument.spectral_windows:
            plt.plot(window.radiance.radiance, '.')

        plt.figure(2)
        for window in instrument.spectral_windows:
            plt.plot(window.radiance.toa_albedo, '.')

        plt.figure(3)
        for window in instrument.spectral_windows:
            plt.plot(window.radiance.irradiance, '.')

        plt.figure(4)
        for window in instrument.spectral_windows:
            plt.plot(window.radiance.photon_flux, '.')
        plt.show()

    test_model()