mapc_optimal ============ .. py:module:: mapc_optimal Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/mapc_optimal/constants/index /autoapi/mapc_optimal/main/index /autoapi/mapc_optimal/pricing/index /autoapi/mapc_optimal/solver/index /autoapi/mapc_optimal/utils/index Classes ------- .. autoapisummary:: mapc_optimal.Solver mapc_optimal.OptimizationType Functions --------- .. autoapisummary:: mapc_optimal.positions_to_path_loss Package Contents ---------------- .. py:class:: Solver(stations, access_points, channel_width = 20, mcs_data_rates = None, min_snr = None, max_tx_power = MAX_TX_POWER, min_tx_power = MIN_TX_POWER, noise_floor = NOISE_FLOOR, opt_type = OptimizationType.MAX_MIN, max_iterations = 100, log_segments = 10, epsilon = 1e-05, solver = None) The solver class coordinating the overall process of finding the optimal solution. It initializes the solver, sets up the network configuration, and manages the iterations. The optimization problem can be formulated in two ways: - the total throughput of the network is maximized, - the worst throughput of each node is maximized. .. rubric:: Examples .. code-block:: python from mapc_optimal import Solver # Define your network # ... solver = Solver(stations, access_points) configurations, rate = solver(path_loss) .. note:: The solver requires the path loss between each pair of nodes in the network. The reason for this is that the solver should be independent of the channel model used. Therefore, the path loss must be calculated beforehand. Note that if you do not require a specific channel model, you can use the provided function to calculate the path loss using the TGax channel model based on the positions of the nodes: .. code:: python import numpy as np from mapc_optimal import position_to_path_loss # Positions of the nodes as an array of `x` and `y` coordinates. `i`-th row represents the position # of the node with identifier `i` in the `stations` and `access_points` lists. pos = np.array([ [x_0, y_0], [x_1, y_1], ... [x_n-1, y_n-1] ]) # A matrix representing the walls in the environment (1 - wall, 0 - no wall between nodes `i` and `j`). walls = np.zeros((n, n)) walls[i_0, j_0] = 1 walls[i_1, j_1] = 1 ... walls[i_m, j_m] = 1 # n x n matrix representing the path loss between each pair of nodes. path_loss = position_to_path_loss(pos, walls) .. note:: Identifiers of the stations and APs should be unique and cover the range from :math:`0` to :math:`n - 1` (where :math:`n` is the total number of nodes in the network). .. note:: The performance of the solver can significantly depend on the underlying mixed-integer linear programming solver. The default one is PULP_CBC, which is a free and open-source solver provided by the PuLP library. However, we recommend using a better solver, such as CPLEX. :param stations: Lists of numbers representing the stations. :type stations: :py:class:`list` :param access_points: Lists of numbers representing the access points (APs) in the network. :type access_points: :py:class:`list` :param channel_width: The channel width used in the network (MHz). :type channel_width: :py:class:`int`, *default* ``20`` :param mcs_data_rates: A list of data rates corresponding to the MCS values (Mb/s). IEEE 802.11be with 1 SS and 800 ns GI data rates are used by default. :type mcs_data_rates: :py:class:`NDArray`, *default* :py:class:`mapc_optimal.constants.DATA_RATES` :param min_snr: The minimum SNR required for a successful transmission (dB) for each MCS value. Empirically determined in ns-3 simulations by default. :type min_snr: :py:class:`NDArray`, *default* :py:class:`mapc_optimal.constants.MIN_SNRS` :param max_tx_power: The maximum transmission power (dBm) available. :type max_tx_power: :py:class:`float`, *default* ``20.0`` :param min_tx_power: The minimum transmission power (dBm) that can be used. :type min_tx_power: :py:class:`float`, *default* ``10.0`` :param noise_floor: The level of noise in the environment (dBm). :type noise_floor: :py:class:`float`, *default* ``-93.97`` :param opt_type: The type of optimization problem to solve. The max min problem is solved by default. :type opt_type: :py:class:`OptimizationType`, *default* :py:class:`OptimizationType.MAX_MIN` :param max_iterations: The maximum number of iterations of the solver. :type max_iterations: :py:class:`int`, *default* ``100`` :param log_segments: The number of linear function segments used to approximate the logarithm function in proportional fairness setting. :type log_segments: :py:class:`int`, *default* ``10`` :param epsilon: The minimum value of the pricing objective function to continue the iterations. :type epsilon: :py:class:`float`, *default* ``1e-5`` :param solver: The solver used to solve the optimization problems. :type solver: :py:class:`pulp.LpSolver`, *default* :py:class:`pulp.PULP_CBC_CMD(msg=False)` .. py:attribute:: stations .. py:attribute:: access_points .. py:attribute:: mcs_values .. py:attribute:: mcs_data_rates :value: None .. py:attribute:: min_sinr .. py:attribute:: max_tx_power .. py:attribute:: min_tx_power .. py:attribute:: noise_floor .. py:attribute:: opt_type .. py:attribute:: max_iterations :value: 100 .. py:attribute:: log_approx .. py:attribute:: epsilon :value: 1e-05 .. py:attribute:: solver .. py:attribute:: M .. py:attribute:: main .. py:attribute:: pricing .. py:method:: __call__(path_loss, associations = None, baseline = None, return_objectives = False) Solves the MAPC C-SR problem given the path loss between each pair of nodes in the network. Returns the final configurations, the time shares, and the total throughput. :param path_loss: Matrix containing the path loss between each pair of nodes. :type path_loss: :py:class:`NDArray` :param associations: The dictionary of associations between APs and stations. :type associations: :py:class:`dict` :param baseline: Dictionary containing the baseline rates of the links (only used for the max-min optimization with baseline). :type baseline: :py:class:`dict`, *default* :py:obj:`None` :param return_objectives: Flag indicating whether to return the pricing objective values. :type return_objectives: :py:class:`bool`, *default* :py:obj:`False` :returns: **result** -- Tuple containing the final configurations and the total throughput. Additionally, the solver can return a list of the pricing objective values for each iteration. It can be useful to check if the solver has converged. :rtype: :py:class:`tuple[dict`, :py:class:`float]` or :py:class:`tuple[dict`, :py:class:`float`, :py:class:`list[float]]` .. 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 - value lookup: >>> Color(1) - name lookup: >>> Color['RED'] Enumerations can be iterated over, and know how many members they have: >>> len(Color) 3 >>> list(Color) [, , ] 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:: 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`