mapc_optimal.utils
==================

.. py:module:: mapc_optimal.utils

.. autoapi-nested-parse::

   Utility functions, including the function for calculation of the path loss from node positions using
   the TGax channel model.



Attributes
----------

.. autoapisummary::

   mapc_optimal.utils.CENTRAL_FREQUENCY
   mapc_optimal.utils.WALL_LOSS
   mapc_optimal.utils.BREAKING_POINT
   mapc_optimal.utils.REFERENCE_DISTANCE


Classes
-------

.. autoapisummary::

   mapc_optimal.utils.OptimizationType


Functions
---------

.. autoapisummary::

   mapc_optimal.utils.dbm_to_lin
   mapc_optimal.utils.lin_to_dbm
   mapc_optimal.utils.tgax_path_loss
   mapc_optimal.utils.positions_to_path_loss


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

.. py:class:: OptimizationType(*args, **kwds)



   Create a collection of name/value pairs.

   Example enumeration:

   >>> class Color(Enum):
   ...     RED = 1
   ...     BLUE = 2
   ...     GREEN = 3

   Access them by:

   - attribute access:

     >>> Color.RED
     <Color.RED: 1>

   - value lookup:

     >>> Color(1)
     <Color.RED: 1>

   - name lookup:

     >>> Color['RED']
     <Color.RED: 1>

   Enumerations can be iterated over, and know how many members they have:

   >>> len(Color)
   3

   >>> list(Color)
   [<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

   Methods can be added to enumerations, and members can have their own
   attributes -- see the documentation for details.


   .. py:attribute:: SUM


   .. py:attribute:: MAX_MIN


   .. py:attribute:: MAX_MIN_BASELINE


   .. py:attribute:: PROPORTIONAL


.. py:function:: dbm_to_lin(x)

   Converts dBm to a linear scale.

   :param x: Input in dBm.
   :type x: :py:class:`array_like`

   :returns: Output in a linear scale.
   :rtype: :py:class:`NDArray`


.. py:function:: lin_to_dbm(x)

   Converts linear scale to dBm.

   :param x: Input in a linear scale.
   :type x: :py:class:`array_like`

   :returns: Output in dBm.
   :rtype: :py:class:`NDArray`


.. py:data:: CENTRAL_FREQUENCY
   :value: 5.16


.. py:data:: WALL_LOSS
   :value: 7.0


.. py:data:: BREAKING_POINT
   :value: 10.0


.. py:data:: REFERENCE_DISTANCE
   :value: 1.0


.. py:function:: tgax_path_loss(distance, walls)

   Calculates the path loss according to the TGax channel model [1]_.

   :param distance: Distance between nodes.
   :type distance: :py:class:`array_like`
   :param walls: Adjacency matrix describing walls between nodes (1 if there is a wall, 0 otherwise).
   :type walls: :py:class:`array_like`

   :returns: Two dimensional array of path losses (dB) between all nodes.
   :rtype: :py:class:`array_like`

   .. rubric:: References

   .. [1] https://www.ieee802.org/11/Reports/tgax_update.htm#:~:text=TGax%20Selection%20Procedure-,11%2D14%2D0980,-TGax%20Simulation%20Scenarios


.. py:function:: positions_to_path_loss(pos, walls, path_loss_fn = tgax_path_loss)

   Calculates the path loss for all nodes based on their positions and the wall positions.
   Channel is modeled using the TGax path loss model.

   :param pos: Two dimensional array of node positions. Each row corresponds to X and Y coordinates of a node.
   :type pos: :py:class:`array_like`
   :param walls: Adjacency matrix describing walls between nodes (1 if there is a wall, 0 otherwise).
   :type walls: :py:class:`array_like`
   :param path_loss_fn: A function that calculates the path loss between two nodes. The function signature should be
                        `path_loss_fn(distance: Array, walls: Array) -> Array`, where `distance` is the matrix of distances
                        between nodes and `walls` is the adjacency matrix of walls. By default, the simulator uses the
                        residential TGax path loss model.
   :type path_loss_fn: :py:class:`Callable`

   :returns: Two-dimensional array of path losses (dB) between all nodes.
   :rtype: :py:class:`NDArray`