pyphysim.comm package¶

Submodules¶

pyphysim.comm.blockdiagonalization module¶

Module implementing the block diagonalization algorithm.

There are two ways to use this module. You can either use the BlockDiagonalizer class, or you can use the block_diagonalize() and the calc_receive_filter() functions (which use the BlockDiagonalizer class in their implementation).

class pyphysim.comm.blockdiagonalization.BDWithExtIntBase(num_users: int, iPu: float, noise_var: float, pe: float)[source]¶

Bases: pyphysim.comm.blockdiagonalization.BlockDiagonalizer

Class to perform the block diagonalization algorithm in a joint transmission scenario taking into account the external interference.

This is the base class for any block diagonalization class that takes into account the external interference.

Parameters

num_users (int) – Number of users.
iPu (float) – Power available for EACH user (in linear scale).
noise_var (float) – Noise variance (power in linear scale).
pe (float) – Power of the external interference source (in linear scale)

calc_whitening_matrices(mu_channel: pyphysim.channels.multiuser.MultiUserChannelMatrixExtInt) → List[numpy.ndarray][source]¶

Calculates the whitening receive filters for each user.

Note that to consider the noise variance it must be set in the provided mu_channel object.

Parameters: mu_channel (MultiUserChannelMatrixExtInt) – A MultiUserChannelMatrixExtInt object, which has the channel from all the transmitters to all the receivers, as well as th external interference.
Returns: W_all_k – The whitening matrices that each receiver should use to whiten the external interference. Each element in W_all_k is the whitening filter (with the conjugate transpose already applied) for a receiver.
Return type: list[np.ndarray]

class pyphysim.comm.blockdiagonalization.BlockDiagonalizer(num_users: int, iPu: float, noise_var: float)[source]¶

Bases: object

Class to perform the block diagonalization algorithm in a joint transmission scenario.

In the block diagonalization algorithm either a single base station with more antennas transmits for multiple users at the same time or a group of base stations acts as a single transmitter to send data to the multiple users at the same time. In both cases the block diagonalization algorithm assures that each receiver does not see interference from the other receivers.

The water-filling algorithm is also applied to optimally distribute the power. However, in the case with multiple base stations, the power restriction in each base station must be respected. Therefore, after the power is optimally allocated at each base station all powers will be normalized to respect the power restriction of the base transmitting the highest energy. This is what is done in the block_diagonalize() method.

If the power should not be optimally allocated with the water-filling algorithm, use the block_diagonalize_no_waterfilling() method instead. The power restriction in each base station will still be respected, but the base station will equally divide its power among the available dimensions. Note that the result will be similar to block_diagonalize() in the high SNR regime.

Parameters

num_users (int) – Number of users.
iPu (float) – Power available for EACH user.
noise_var (float) – Noise variance (power in linear scale).

Examples

Consider the case where we have 3 base station (BSs) jointly transmitting to 3 users, where each base station has a power of 1.5, the number of antennas (at each BS and at each receiver) is 2, and the noise variance is 1e-4. The channel can be block diagonalized for this scenario with

>>> bs_power = 1.5
>>> noise_var = 1e-4
>>> num_users = 2
>>> Ntx = 2  # Number of transmit antennas (per BS)
>>> Nrx = 2  # Number of receive antennas (per user)
>>> # Create the BlockDiagonalizer object
>>> bd = BlockDiagonalizer(num_users, bs_power, noise_var)
>>> channel = np.array([[-0.9834-0.0123j,  0.6503-0.3189j,      0.5484+1.7049j, -1.0891-0.1025j], [-0.5911-0.3055j, -0.6205+0.3375j,     -0.7995+0.3723j,  0.7412-1.2537j], [-0.2732+0.475j , -0.4191+0.4019j,     0.1047-0.5592j,  0.7548-1.0214j], [ 0.5377-0.208j , -0.1480-1.0527j,     -0.6373+0.4081j, -0.5854-0.8135j]])
>>> (newH, Ms) = bd.block_diagonalize(channel)

We can see that the equivalent channel (after applying the Ms modulation matrix) is really block diagonalized.

>>> print(np.round(newH + 1e-10 + 1e-10j, 4))
[[ 0.0916+0.0135j -1.7449-0.4328j  0.    +0.j      0.    +0.j    ]
 [-0.0114-0.146j   0.0213-1.1366j  0.    +0.j      0.    +0.j    ]
 [ 0.    +0.j      0.    +0.j      0.0868+0.1565j -0.3673+0.2289j]
 [ 0.    +0.j      0.    +0.j     -0.0396+0.0407j  1.024 +0.8997j]]

Notice how the power restriction of each BS is respected (although only one BS will transmit with its maximum power).

>>> print(np.round(np.linalg.norm(Ms[:,0:Ntx])**2, 4))
1.4997
>>> print(np.round(np.linalg.norm(Ms[:,Ntx:])**2, 4))
1.5

Notes

The block diagonalization algorithm is described in [Spencer2004], where different power allocations are illustrated. The BlockDiagonalizer class implement two power allocation methods, a global power allocation, and a ‘per transmitter’ power allocation.

_calc_BD_matrix_no_power_scaling(mtChannel: numpy.ndarray) → Tuple[numpy.ndarray, numpy.ndarray][source]¶

Calculates the modulation matrix “M” that block diagonalizes the channel mtChannel, but without any king of power scaling.

The “modulation matrix” is a matrix that changes the channel to a block diagonal structure and it is the first part in the Block Diagonalization algorithm. The returned modulation matrix is equivalent to Equation (12) of [Spencer2004] but without the power scaling matrix $\Lambda$. Therefore, for the complete BD algorithm it is still necessary to perform this power scaling in the output of _calc_BD_matrix_no_power_scaling.

Parameters: mtChannel (np.ndarray) – Channel from the transmitter to all users.
Returns: (Ms_bad, Sigma) – The modulation matrix “Ms_bad” is a precoder that block diagonalizes the channel. The singular values of the equivalent channel when the modulation matrix is applied correspond to Sigma. Therefore, Sigma can be used latter in the power allocation process.
Return type: (np.ndarray,np.ndarray)

Notes

The reason why the Block Diagonalization algorithm was broken down into the code here and the power scaling code is because the power scaling may changing depending on the scenario. For instance, if the transmitter corresponds to a single base station the the power may be distributed into all the dimensions of the Modulation matrix. On the other hand, if the transmitter corresponds to multiple base stations jointly transmitting to multiple users then the power of each base station must be distributed only into the dimensions corresponding to that base station.

_get_sub_channel(mt_channel: numpy.ndarray, desired_users: Union[int, Iterable[int]]) → numpy.ndarray [source]¶

Get a subchannel according to the desired_users vector.

Parameters

mt_channel (np.ndarray) – Channel of all users (2D numpy array).
desired_users (list[int]) – An iterable with the indexes of the desired users or an integer.

Returns

mtSubmatrix – Submatrix of the desired users (2D numpy array)

Return type

np.ndarray

Notes

As an example, let’s consider the case with a channel for 3 receivers, each with 2 receive antennas, where the transmitter has 6 transmit antennas.

>>> BD = BlockDiagonalizer(3, 0, 0)
>>> channel = np.vstack([np.ones([2, 6]), 2 * np.ones([2, 6]),                                 3 * np.ones([2, 6])])
>>> BD._get_sub_channel(channel, [0,2])
array([[1., 1., 1., 1., 1., 1.],
       [1., 1., 1., 1., 1., 1.],
       [3., 3., 3., 3., 3., 3.],
       [3., 3., 3., 3., 3., 3.]])
>>> BD._get_sub_channel(channel, 0)
array([[1., 1., 1., 1., 1., 1.],
       [1., 1., 1., 1., 1., 1.]])

_get_tilde_channel(mtChannel: numpy.ndarray, user: int) → numpy.ndarray [source]¶

Return the combined channel of all users except user.

Let $k$ be the index for user. If the channel from all transmitters to receiver $k$ is $mtH_k$, then this method returns $tilde{mtH_k} = [mtH_1^T, ldots, mtH_{k-1}^T, mtH_{k+1}^T, ldots, mtH_K]^T$.

Parameters

mtChannel (np.ndarray) – Channel of all users (2D numpy array).
user (int) – Index of the user.

Returns

The combined channel of all users except user.

Return type

np.ndarray

_perform_global_waterfilling_power_scaling(Ms_bad: numpy.ndarray, Sigma: numpy.ndarray) → numpy.ndarray [source]¶

Perform the power scaling based on the water-filling algorithm for all the parallel channel gains in Sigma.

This power scaling method corresponds to maximizing the sum rate when the transmitter is a single base station transmitting to all users. Note that this approach may result in one or two “strong users” taking a dominant share of the available power.

Parameters

Ms_bad (np.ndarray) – The previously calculated modulation matrix (without any power scaling). This should be a 2D numpy array.
Sigma (np.ndarray) – The singular values of the effective channel when Ms_bad is applied. This should be a 1D numpy array of positive floats.

Returns

Ms_good – The modulation matrix (2D numpy array) with the global power scaling applied.

Return type

np.ndarray

_perform_normalized_waterfilling_power_scaling(Ms_bad: numpy.ndarray, Sigma: numpy.ndarray) → numpy.ndarray [source]¶

Perform the power scaling based on the water-filling algorithm for all the parallel channel gains in Sigma, but normalize the result by the power of the base station transmitting with the highest power.

When we have a joint transmission where multiple base stations act as a single base station, then performing the water-filling on all the channels for the total available power may result in some base station transmitting with a higher power then it actually can. Therefore, we normalize the power of the strongest BS so that the power restriction at each BS is satisfied. This is sub-optimal since the other BSs will use less power then available, but it is simple and it works.

Parameters

Ms_bad (np.ndarray) – The previously calculated modulation matrix (without any power scaling)
Sigma (np.ndarray) – The singular values of the effective channel when Ms_bad is applied. This should be a 1D numpy array with positive values.

Returns

Ms_good – The modulation matrix with the normalized power scaling applied. This is a 2D numpy array.

Return type

np.ndarray

block_diagonalize(mtChannel: numpy.ndarray) → Tuple[numpy.ndarray, numpy.ndarray][source]¶

Perform the block diagonalization.

mtChannel is a matrix with the channel from the transmitter to all users, where each iNUsers rows correspond to one user.

For an example, see the documentation of the BlockDiagonalizer class.

Parameters: mtChannel (np.ndarray) – Channel from (all) the transmitter(s) to all users. This should be a 2D numpy array.
Returns: newH is a 2D numpy array corresponding to the Block diagonalized channel, while Ms_good is a 2D numpy array corresponding to the precoder matrix used to block diagonalize the channel.
Return type: np.ndarray, np.ndarray

pyphysim.comm.waterfilling module¶

Implements a waterfilling method.

The doWF method performs the waterfilling algorithm.

pyphysim.comm.waterfilling.doWF(vtChannels: numpy.ndarray, dPt: float, noiseVar: float = 1.0, Es: float = 1.0) → Tuple[numpy.ndarray, float][source]¶

Performs the Waterfilling algorithm and returns the optimum power and water level.

Parameters

vtChannels (np.ndarray) – Numpy array with the channel POWER gains (power of the parallel AWGN channels).
dPt (float) – Total available power.
noiseVar (float) – Noise variance (power in linear scale).
Es (float) – Symbol energy (in linear scale).

Returns

(vtOptP, mu) – A tuple with vtOptP and mu, where vtOptP are the optimum powers, while mu is the water level.

Return type

(np.ndarray, float)

Module contents¶

Package with communication related modules such as modulators, channels, etc.

summary
extended summary
routine listings
see also
notes
references
examples