mapc_optimal

Submodules

Classes

Solver

The solver class coordinating the overall process of finding the optimal solution.

OptimizationType

Create a collection of name/value pairs.

Functions

positions_to_path_loss(pos, walls[, path_loss_fn])

Calculates the path loss for all nodes based on their positions and the wall positions.

Package Contents

class mapc_optimal.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.

Examples

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:

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 \(0\) to \(n - 1\) (where \(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.

Parameters:

  • stations (list) – Lists of numbers representing the stations.

  • access_points (list) – Lists of numbers representing the access points (APs) in the network.

  • channel_width (int, default 20) – The channel width used in the network (MHz).

  • mcs_data_rates (NDArray, default mapc_optimal.constants.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.

  • min_snr (NDArray, default mapc_optimal.constants.MIN_SNRS) – The minimum SNR required for a successful transmission (dB) for each MCS value. Empirically determined in ns-3 simulations by default.

  • max_tx_power (float, default 20.0) – The maximum transmission power (dBm) available.

  • min_tx_power (float, default 10.0) – The minimum transmission power (dBm) that can be used.

  • noise_floor (float, default -93.97) – The level of noise in the environment (dBm).

  • opt_type (OptimizationType, default OptimizationType.MAX_MIN) – The type of optimization problem to solve. The max min problem is solved by default.

  • max_iterations (int, default 100) – The maximum number of iterations of the solver.

  • log_segments (int, default 10) – The number of linear function segments used to approximate the logarithm function in proportional fairness setting.

  • epsilon (float, default 1e-5) – The minimum value of the pricing objective function to continue the iterations.

  • solver (pulp.LpSolver, default pulp.PULP_CBC_CMD(msg=False)) – The solver used to solve the optimization problems.

stations
access_points
mcs_values
mcs_data_rates = None
min_sinr
max_tx_power
min_tx_power
noise_floor
opt_type
max_iterations = 100
log_approx
epsilon = 1e-05
solver
M
main
pricing
__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.

Parameters:

  • path_loss (NDArray) – Matrix containing the path loss between each pair of nodes.

  • associations (dict) – The dictionary of associations between APs and stations.

  • baseline (dict, default None) – Dictionary containing the baseline rates of the links (only used for the max-min optimization with baseline).

  • return_objectives (bool, default False) – Flag indicating whether to return the pricing objective values.

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.

Return type:

tuple[dict, float] or tuple[dict, float, list[float]]

class mapc_optimal.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.

SUM
MAX_MIN
MAX_MIN_BASELINE
PROPORTIONAL
mapc_optimal.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.

Parameters:

  • pos (array_like) – Two dimensional array of node positions. Each row corresponds to X and Y coordinates of a node.

  • walls (array_like) – Adjacency matrix describing walls between nodes (1 if there is a wall, 0 otherwise).

  • path_loss_fn (Callable) – 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.

Returns:

Two-dimensional array of path losses (dB) between all nodes.

Return type:

NDArray