reskit.weather.MerraSource.MerraSource
======================================

.. py:module:: reskit.weather.MerraSource.MerraSource


Classes
-------

.. autoapisummary::

   reskit.weather.MerraSource.MerraSource.MerraSource


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

.. py:class:: MerraSource(source, bounds=None, index_pad=5, **kwargs)

   Bases: :py:obj:`reskit.weather.NCSource`


   The MerraSource object manages weather data (as netCDF4 files) coming from the
   `MERRA2 climate data products<https://gmao.gsfc.nasa.gov/reanalysis/MERRA-2/>`

   If furthermore allows access a number of common functionalities and constants which are
   often encountered when simulating renewable energy technologies

   Note:
   -----
   Various constants can have been set for this weather source which can impact later simulation workflows.

   These constants include:
       MAX_LON_DIFFERENCE = 0.625
           The maximum longitude difference to accept between a grid cell's center and the coordinates
               to extract data for

       MAX_LAT_DIFFERENCE = 0.5
           The maximum latitude difference to accept between a grid cell's center and the coordinates
               to extract data for

       WIND_SPEED_HEIGHT_FOR_WIND_ENERGY = 50
           The suggested altitude of wind speed data to use for wind-energy simulations

       WIND_SPEED_HEIGHT_FOR_SOLAR_ENERGY = 2
           The suggested altitude of wind speed data to use for wind-energy simulations

       LONG_RUN_AVERAGE_WINDSPEED :
           <RESKit path>/weather/MerraSource/data/merra_average_windspeed_50m-shifted.tif

           A path to a raster file with the long-time average wind speed in each grid cell
           * Can be used in wind energy simulations
           * Calculated at the height specified in `WIND_SPEED_HEIGHT_FOR_WIND_ENERGY`
           * Time range includes 1980 until the end of 2017 (the time of first calculation)
           * Only a few regions have been precomputed, therefore applications which require this
               data will not work outside of these regions. They include:
               - Europe
               - Australia
               - Iceland
               - Parts of south america
               - Parts of north america


       LONG_RUN_AVERAGE_GHI :
           <RESKit path>/weather/MerraSource/data/merra_average_SWGDN_1994-2015_globe.tif

           A path to a raster file with the long-time average global horizontal irradiance in
               each grid cell
           * Can be used in solar energy simulations
           * Calculated at the surface
           * Time range includes 1994 until the end of 2015 (to match the global solar atlas)
           * Only a few regions have been precomputed, therefore applications which require this
               data will not work outside of these regions. They include:
               - Europe
               - Australia
               - Iceland
               - Parts of south america
               - Parts of north america


   .. seealso:: :obj:`reskit.weather.MerraSource`, :obj:`reskit.weather.SarahSource`, :obj:`reskit.weather.Era5Source`, :obj:`Initialize`, :obj:`Compared`, :obj:`the`

   :param path: The path to the main data file(s) to load

                If multiple files are given, or if a directory of netCDF4 files is given, then it is assumed
                that all files ending with the extension '.nc' or '.nc4' should be managed by this object.
                * Be sure that all the netCDF4 files given share the same time and spatial dimensions!
   :type path: str or list of str
   :param bounds:
                  The boundaries of the data which is needed
                    * Usage of this will help with memory management
                    * If None, the full dataset is loaded in memory
                    * The actual extent of the loaded data depends on the source's
                      available data
   :type bounds: Anything acceptable to geokit.Extent.load(), optional
   :param index_pad:
                     The padding to apply to the boundaries
                       * Useful in case of interpolation
                       * Units are in longitudinal degrees
   :type index_pad: int, optional
   :param verbose: If True, then status outputs are printed when searching for and reading weather data
   :type verbose: bool, optional
   :param forward_fill: If True, then missing data in the weather file is forward-filled
                        * Generally, there should be no missing data at all. This option is only intended to
                            catch the rare scenarios where one or two timesteps are missing
   :type forward_fill: bool, optional

   .. seealso:: :obj:`MerraSource`, :obj:`SarahSource`, :obj:`Era5Source`


   .. py:attribute:: ELEVATED_WIND_SPEED_HEIGHT
      :value: 50



   .. py:attribute:: SURFACE_WIND_SPEED_HEIGHT
      :value: 2



   .. py:attribute:: LONG_RUN_AVERAGE_WINDSPEED


   .. py:attribute:: LONG_RUN_AVERAGE_GHI


   .. py:attribute:: MAX_LON_DIFFERENCE
      :value: 0.625



   .. py:attribute:: MAX_LAT_DIFFERENCE
      :value: 0.5



   .. py:attribute:: loc_to_index

      Returns the closest X and Y indexes corresponding to a given location
      or set of locations


      :param loc: The location(s) to search for
                  * A single tuple with (lon, lat) is acceptable, or a list of such tuples
                  * A single point geometry (as long as it has an SRS), or a list
                    of geometries is okay
                  * geokit,Location, or geokit.LocationSet are best!
      :type loc: Anything acceptable by geokit.LocationSet
      :param outside_okay: Determines if points which are outside the source's lat/lon grid
                           are allowed
                           * If True, points outside this space will return as None
                           * If False, an error is raised
      :type outside_okay: bool, optional

      :returns: * **If a single location is given** (*tuple*) --

                  * Format: (yIndex, xIndex)
                  * y index can be accessed with '.yi'
                  * x index can be accessed with '.xi'
                * **If multiple locations are given** (*list*) --

                  * Format: [ (yIndex1, xIndex1), (yIndex2, xIndex2), ...]
                  * Order matches the given order of locations

      Note:
      -----
      The default form of this function (which is the one used here) is not very efficient, ultimately
          leading to much longer look-up than they otherwise need to be. When the weather source has
          grid cells on a regular lat/lon grid then a more efficient form of this function can be
          configured using the function generator "_loc_to_index_rect". In these instances, this is
          the recommended function to use.

      For example, if the weather source uses a latitude spacing of 0.5, and a longitude spacing of
          0.625, then the function generator can be used like:

          > source.loc_to_index = source._loc_to_index_rect(lat_step=0.5, lon_step=0.625)


   .. py:method:: context_area_at_index(latI, lonI)

      Compute the context area surrounding the specified index of the original source



   .. py:method:: _load_uv(height)


   .. py:method:: _load_wind_speed(height)


   .. py:method:: sload_elevated_wind_speed()

      Standard loader function for the variable 'elevated_wind_speed'

      Automatically reads the variables "U<X>M" and "V<X>M" from the given MERRA2 source,
      computes the total windspeed, and saves it as the variable 'elevated_wind_speed' in
      the data library

      Where '<X>' is the height specified by `MerraSource.ELEVATED_WIND_SPEED_HEIGHT`



   .. py:method:: sload_surface_wind_speed()

      Standard loader function for the variable 'surface_wind_speed'

      Automatically reads the variables "U<X>M" and "V<X>M" from the given MERRA2 source,
      computes the total windspeed, and saves it as the variable 'surface_wind_speed' in
      the data library

      Where '<X>' is the height specified by `MerraSource.SURFACE_WIND_SPEED_HEIGHT`



   .. py:method:: sload_wind_speed_at_2m()

      Standard loader function for the variable 'wind_speed_at_2m'

      Automatically reads the variables "U2M" and "V2M" from the given MERRA2 source,
      computes the total windspeed, and saves it as the variable 'wind_speed_at_2m' in
      the data library



   .. py:method:: sload_wind_speed_at_10m()

      Standard loader function for the variable 'wind_speed_at_10m'

      Automatically reads the variables "U10M" and "V10M" from the given MERRA2 source,
      computes the total windspeed, and saves it as the variable 'wind_speed_at_10m' in
      the data library



   .. py:method:: sload_wind_speed_at_50m()

      Standard loader function for the variable 'wind_speed_at_50m'

      Automatically reads the variables "U50M" and "V50M" from the given MERRA2 source,
      computes the total windspeed, and saves it as the variable 'wind_speed_at_50m' in
      the data library



   .. py:method:: _load_wind_dir(height)


   .. py:method:: sload_elevated_wind_direction()

      Standard loader function for the variable 'elevated_wind_direction'

      Automatically reads the variables "U<X>M" and "V<X>M" from the given MERRA2 source,
      computes the total windspeed, and saves it as the variable 'elevated_wind_direction' in
      the data library

      Where '<X>' is the height specified by `MerraSource.ELEVATED_WIND_SPEED_HEIGHT`



   .. py:method:: sload_surface_wind_direction()

      Standard loader function for the variable 'surface_wind_direction'

      Automatically reads the variables "U<X>M" and "V<X>M" from the given MERRA2 source,
      computes the total windspeed, and saves it as the variable 'surface_wind_direction' in
      the data library

      Where '<X>' is the height specified by `MerraSource.SURFACE_WIND_SPEED_HEIGHT`



   .. py:method:: sload_wind_direction_at_2m()

      Standard loader function for the variable 'wind_direction_at_2m'

      Automatically reads the variables "U2M" and "V2M" from the given MERRA2 source,
      computes the total windspeed, and saves it as the variable 'wind_direction_at_2m' in
      the data library



   .. py:method:: sload_wind_direction_at_10m()

      Standard loader function for the variable 'wind_direction_at_10m'

      Automatically reads the variables "U10M" and "V10M" from the given MERRA2 source,
      computes the total windspeed, and saves it as the variable 'wind_direction_at_10m' in
      the data library



   .. py:method:: sload_wind_direction_at_50m()

      Standard loader function for the variable 'wind_direction_at_50m'

      Automatically reads the variables "U50M" and "V50M" from the given MERRA2 source,
      computes the total windspeed, and saves it as the variable 'wind_direction_at_50m' in
      the data library



   .. py:method:: sload_surface_pressure()

      Standard loader function for the variable 'surface_pressure'

      Automatically reads the variable "PS" from the given MERRA2 source and saves it as the
      variable 'surface_pressure' in the data library



   .. py:method:: sload_surface_air_temperature()

      Standard loader function for the variable 'surface_air_temperature'

      Automatically reads the variable "T2M" from the given MERRA2 source and saves it as the
      variable 'surface_air_temperature' in the data library

      Temperature values are also converted from kelvin to degrees celsius



   .. py:method:: sload_surface_dew_temperature()

      Standard loader function for the variable 'surface_dew_temperature'

      Automatically reads the variable "T2MDEW" from the given MERRA2 source and saves it as the
      variable 'surface_dew_temperature' in the data library

      Temperature values are also converted from kelvin to degrees celsius



   .. py:method:: sload_global_horizontal_irradiance()

      Standard loader function for the variable 'global_horizontal_irradiance'

      Automatically reads the variable "SWGDN" from the given MERRA2 source and saves it as the
      variable 'global_horizontal_irradiance' in the data library