windwhisper.noisepropagation
============================

.. py:module:: windwhisper.noisepropagation


Attributes
----------

.. autoapisummary::

   windwhisper.noisepropagation.NOISE_MAP_RESOLUTION
   windwhisper.noisepropagation.NOISE_MAP_MARGIN


Classes
-------

.. autoapisummary::

   windwhisper.noisepropagation.NoisePropagation


Functions
---------

.. autoapisummary::

   windwhisper.noisepropagation.define_bounding_box


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

.. py:data:: NOISE_MAP_RESOLUTION

.. py:data:: NOISE_MAP_MARGIN

.. py:function:: define_bounding_box(wind_turbines)

   Derive latitude and longitude axes for the simulation grid.

   :param wind_turbines: Turbine specifications including ``position`` tuples.
   :type wind_turbines: dict
   :returns: Tuple ``(latitudes, longitudes)`` defining the rectangular grid.
   :rtype: tuple[numpy.ndarray, numpy.ndarray]


.. py:class:: NoisePropagation(wind_turbines, humidity = 70, temperature = 20, elevation_data = None)

   Model sound propagation and attenuation for wind turbine layouts.


   .. py:attribute:: incr_noise_att
      :value: None



   .. py:attribute:: noise_attenuation
      :value: None



   .. py:attribute:: elevation_grid
      :value: None



   .. py:attribute:: haversine_distances
      :value: None



   .. py:attribute:: listeners
      :value: 70



   .. py:attribute:: wind_turbines


   .. py:attribute:: elevation_data
      :value: None



   .. py:attribute:: noise_level_at_wind_speeds


   .. py:attribute:: hourly_noise_levels


   .. py:attribute:: l_den


   .. py:attribute:: l_night


   .. py:attribute:: incr_noise_att_night


   .. py:method:: calculate_hourly_noise_levels()

      Interpolate hourly emission levels for each turbine.



   .. py:method:: compute_lden()

      Calculate the day-evening-night noise level from hourly levels.

      :returns: Lden noise level raster.
      :rtype: xarray.DataArray



   .. py:method:: compute_lnight()

      Calculate the night noise level from hourly levels.

      :returns: Lnight noise level raster.
      :rtype: xarray.DataArray



   .. py:method:: calculate_incremental_noise_attenuation(noise)

      Apply successive attenuation terms to the emission raster.

      :param noise: Base noise level raster to which attenuations are applied.
      :type noise: xarray.DataArray
      :returns: Dataset containing intermediate attenuation stages.
      :rtype: xarray.Dataset



   .. py:method:: get_noise_emissions_vs_time_or_speed(noise, coord_name, coord_value)

      Aggregate turbine emissions along the requested dimension.

      :param noise: Noise levels per turbine for each coordinate value.
      :type noise: numpy.ndarray
      :param coord_name: Name of the output coordinate (``"wind_speed"`` or
          ``"hour"``).
      :type coord_name: str
      :param coord_value: Coordinate values associated with the emissions.
      :type coord_value: numpy.ndarray
      :returns: Noise levels summed over all turbines for each grid cell.
      :rtype: xarray.DataArray



   .. py:method:: noise_map_at_wind_speeds(noise)

      Backward compatible alias for :meth:`get_noise_emissions_vs_time_or_speed`.

      :param noise: Noise levels per turbine for each wind speed.
      :type noise: numpy.ndarray
      :returns: Noise map aggregated across turbines for each wind speed.
      :rtype: xarray.DataArray



   .. py:method:: calculate_sound_level_at_distance(*args, **kwargs)
      :abstractmethod:


      Deprecated compatibility wrapper for legacy APIs.

      :raises NotImplementedError: Always raised to direct users to
          :meth:`get_noise_emissions_vs_time_or_speed`.



   .. py:method:: superimpose_wind_turbines_noise()

      Deprecated alias returning the aggregated wind speed noise map.



   .. py:method:: calculate_noise_attenuation_terms()

      Compute distance, atmospheric, ground and obstacle attenuation.



   .. py:method:: plot_noise_map(dimension = 'wind_speed')

      Display interactive contour plots of turbine noise levels.

      :param dimension: Dimension to explore (``"wind_speed"`` or ``"hour"``).
      :type dimension: str