kaira.utils.CapacityAnalyzer

Inheritance diagram for CapacityAnalyzer

class kaira.utils.CapacityAnalyzer(device: device | None = None, num_processes: int = 1, fast_mode: bool = True)

Bases: object

Compute and analyze capacity for various channels and modulation schemes.

This class provides methods to compute the Shannon capacity of continuous channels as well as the capacity and achievable rates of specific modulation schemes over various channel models. It supports both analytical calculations and Monte Carlo simulations for numerical approximations when closed-form solutions are not available.

device

Device to run computations on (CPU or GPU)

Type:

torch.device

num_processes

Number of parallel processes for Monte Carlo simulations

Type:

int

Methods

__init__	Initialize the capacity analyzer.
awgn_capacity	Compute Shannon capacity for an AWGN channel.
awgn_capacity_complex	Compute Shannon capacity for a complex AWGN channel.
bec_capacity	Compute capacity for the Binary Erasure Channel.
bsc_capacity	Compute capacity for the Binary Symmetric Channel.
capacity_cdf	Compute the cumulative distribution function (CDF) of capacity.
capacity_gap_to_shannon	Compute the gap between a modulation scheme's capacity and the Shannon limit.
compare_channels	Compare capacity of a modulation scheme over multiple channels.
compare_modulation_schemes	Compare capacity of multiple modulation schemes over a specified channel.
energy_efficiency	Calculate energy efficiency for a communication system.
ergodic_capacity	Compute ergodic capacity for fading channels.
gaussian_input_capacity	Compute capacity assuming Gaussian input distribution.
mimo_capacity	Compute capacity for MIMO systems.
modulation_capacity	Compute capacity of a modulation scheme over a specified channel.
mutual_information	Compute mutual information for a modulation scheme over a given channel.
outage_capacity	Compute outage capacity for fading channels.
plot_capacity_vs_param	Plot capacity vs.
plot_capacity_vs_snr	Plot capacity vs.
spectral_efficiency	Calculate spectral efficiency for a modulation scheme.

Examples using kaira.utils.CapacityAnalyzer

Channel Capacity Analysis with Kaira

Channel Capacity Analysis with Kaira

__init__(device: device | None = None, num_processes: int = 1, fast_mode: bool = True)

Initialize the capacity analyzer.

Parameters:

• device (torch.device, optional) – Device to run computations on. If None, uses CUDA if available, otherwise CPU.

• num_processes (int, optional) – Number of parallel processes to use for Monte Carlo simulations. Default is 1 (no parallelism). Set to -1 to use all available CPU cores.

• fast_mode (bool, optional) – Whether to use faster approximations

awgn_capacity(snr_db: float | List[float] | ndarray | Tensor) → Tensor

Compute Shannon capacity for an AWGN channel.

Calculates C = log2(1 + SNR) for the additive white Gaussian noise channel.

Parameters:

snr_db – Signal-to-noise ratio in dB, can be a single value or array

Returns:

Capacity in bits per channel use

Return type:

torch.Tensor

awgn_capacity_complex(snr_db: float | List[float] | ndarray | Tensor) → Tensor

Compute Shannon capacity for a complex AWGN channel.

For complex channels, C = log2(1 + SNR) where SNR is defined per complex dimension.

Parameters:

snr_db – Signal-to-noise ratio in dB, can be a single value or array

Returns:

Capacity in bits per complex channel use

Return type:

torch.Tensor

bsc_capacity(p: float | List[float] | ndarray | Tensor) → Tensor

Compute capacity for the Binary Symmetric Channel.

For a BSC with crossover probability p, C = 1 - H(p) where H(p) is the binary entropy function.

Parameters:

p – Crossover probability (0 ≤ p ≤ 0.5), can be a single value or array

Returns:

Capacity in bits per channel use

Return type:

torch.Tensor

bec_capacity(erasure_prob: float | List[float] | ndarray | Tensor) → Tensor

Compute capacity for the Binary Erasure Channel.

For a BEC with erasure probability ε, C = 1 - ε.

Parameters:

erasure_prob – Erasure probability (0 ≤ ε ≤ 1), can be a single value or array

Returns:

Capacity in bits per channel use

Return type:

torch.Tensor

gaussian_input_capacity(channel: BaseChannel, snr_db: float | List[float] | ndarray | Tensor, constrained: bool = True) → Tensor

Compute capacity assuming Gaussian input distribution.

For many channels, the capacity-achieving input distribution is Gaussian. This method computes the capacity assuming a Gaussian input.

Parameters:

• channel – The channel model

• snr_db – Signal-to-noise ratio in dB, can be a single value or array

• constrained – Whether to apply an average power constraint

Returns:

Capacity in bits per channel use

Return type:

torch.Tensor

mutual_information(modulator: BaseModulator, channel: BaseChannel, snr_db: float | List[float] | ndarray | Tensor, num_symbols: int = 10000, num_bins: int = 100, estimation_method: str = 'histogram') → Tensor

Compute mutual information for a modulation scheme over a given channel.

Uses Monte Carlo simulation to estimate the mutual information between channel input and output, which represents the achievable rate for a specific modulation scheme.

Parameters:

• modulator – The modulation scheme

• channel – The channel model

• snr_db – Signal-to-noise ratio in dB, can be a single value or array

• num_symbols – Number of symbols to use in the Monte Carlo simulation

• num_bins – Number of bins to use in histogram estimation

• estimation_method – Method to estimate mutual information (‘histogram’ or ‘knn’)

Returns:

Mutual information in bits per channel use

Return type:

torch.Tensor

modulation_capacity(modulator: BaseModulator, channel: BaseChannel, snr_db_range: List[float] | ndarray | Tensor, num_symbols: int = 10000, monte_carlo: bool = True, estimation_method: str = 'histogram') → Tuple[Tensor, Tensor]

Compute capacity of a modulation scheme over a specified channel.

Either analytically (when possible) or using Monte Carlo simulation.

Parameters:

• modulator – The modulation scheme

• channel – The channel model

• snr_db_range – Range of SNR values in dB to compute capacity for

• num_symbols – Number of symbols for Monte Carlo simulation

• monte_carlo – Whether to force Monte Carlo simulation even if analytical solution is available

• estimation_method – Method to estimate mutual information (‘histogram’ or ‘knn’)

Returns:

(SNR values, capacity values)

Return type:

Tuple[torch.Tensor, torch.Tensor]

plot_capacity_vs_snr(snr_db_range: List[float] | ndarray | Tensor, capacities: List[Tensor] | Dict[str, Tensor], labels: List[str] | None = None, title: str = 'Channel Capacity vs. SNR', xlabel: str = 'SNR (dB)', ylabel: str = 'Capacity (bits/channel use)', legend_loc: str = 'lower right', include_shannon: bool = True, include_shannon_mimo: bool = False, mimo_tx: int = 2, mimo_rx: int = 2, figsize: Tuple[int, int] = (10, 6), grid: bool = True, style: str = 'default') → Figure

Plot capacity vs. SNR for one or more modulation schemes or channels.

Parameters:

• snr_db_range – SNR values in dB

• capacities – List or dict of capacity values corresponding to each SNR point

• labels – Labels for each capacity curve

• title – Plot title

• xlabel – X-axis label

• ylabel – Y-axis label

• legend_loc – Location of the legend

• include_shannon – Whether to include the Shannon capacity limit

• include_shannon_mimo – Whether to include the MIMO Shannon capacity limit

• mimo_tx – Number of transmit antennas for MIMO capacity

• mimo_rx – Number of receive antennas for MIMO capacity

• figsize – Figure size (width, height) in inches

• grid – Whether to show grid

• style – Matplotlib style to use

Returns:

The matplotlib figure object

Return type:

plt.Figure

plot_capacity_vs_param(param_values: List[float] | ndarray | Tensor, capacities: List[Tensor] | Dict[str, Tensor], param_name: str = 'Parameter', labels: List[str] | None = None, title: str = 'Channel Capacity', xlabel: str = 'Parameter Value', ylabel: str = 'Capacity (bits/channel use)', legend_loc: str = 'lower right', figsize: Tuple[int, int] = (10, 6), grid: bool = True, style: str = 'default') → Figure

Plot capacity vs. a parameter for one or more modulation schemes or channels.

Parameters:

• param_values – Parameter values

• capacities – List or dict of capacity values corresponding to each parameter value

• param_name – Name of the parameter

• labels – Labels for each capacity curve

• title – Plot title

• xlabel – X-axis label

• ylabel – Y-axis label

• legend_loc – Location of the legend

• figsize – Figure size (width, height) in inches

• grid – Whether to show grid

• style – Matplotlib style to use

Returns:

The matplotlib figure object

Return type:

plt.Figure

ergodic_capacity(channel: BaseChannel, snr_db_range: List[float] | ndarray | Tensor, num_realizations: int = 1000, num_symbols_per_realization: int = 100) → Tuple[Tensor, Tensor]

Compute ergodic capacity for fading channels.

For fading channels, the ergodic capacity is the expected value of the capacity over all fading realizations.

Parameters:

• channel – The fading channel model

• snr_db_range – Range of SNR values in dB

• num_realizations – Number of channel realizations to average over

• num_symbols_per_realization – Number of symbols per channel realization

Returns:

(SNR values, ergodic capacity values)

Return type:

Tuple[torch.Tensor, torch.Tensor]

outage_capacity(channel: BaseChannel, snr_db_range: List[float] | ndarray | Tensor, outage_probability: float = 0.01, num_realizations: int = 1000, num_symbols_per_realization: int = 100) → Tuple[Tensor, Tensor]

Compute outage capacity for fading channels.

The outage capacity is the highest rate that can be achieved with an outage probability less than the specified value.

Parameters:

• channel – The fading channel model

• snr_db_range – Range of SNR values in dB

• outage_probability – Target outage probability

• num_realizations – Number of channel realizations

• num_symbols_per_realization – Number of symbols per channel realization

Returns:

(SNR values, outage capacity values)

Return type:

Tuple[torch.Tensor, torch.Tensor]

compare_modulation_schemes(modulators: List[BaseModulator], channel: BaseChannel, snr_db_range: List[float] | ndarray | Tensor, labels: List[str] | None = None, num_symbols: int = 10000, plot: bool = True, figsize: Tuple[int, int] = (10, 6), estimation_method: str = 'histogram') → Tuple[Tensor, Dict[str, Tensor], Figure | None]

Compare capacity of multiple modulation schemes over a specified channel.

Parameters:

• modulators – List of modulation schemes to compare

• channel – The channel model

• snr_db_range – Range of SNR values in dB

• labels – Labels for each modulation scheme

• num_symbols – Number of symbols for Monte Carlo simulation

• plot – Whether to generate and return a plot

• figsize – Figure size (width, height) in inches

• estimation_method – Method to estimate mutual information (‘histogram’ or ‘knn’)

Returns:

• SNR values

• Dictionary mapping modulation names to capacity values

• Optional matplotlib figure if plot=True

Return type:

Tuple containing

compare_channels(modulator: BaseModulator, channels: List[BaseChannel], snr_db_range: List[float] | ndarray | Tensor, labels: List[str] | None = None, num_symbols: int = 10000, plot: bool = True, figsize: Tuple[int, int] = (10, 6), estimation_method: str = 'histogram') → Tuple[Tensor, Dict[str, Tensor], Figure | None]

Compare capacity of a modulation scheme over multiple channels.

Parameters:

• modulator – The modulation scheme

• channels – List of channel models to compare

• snr_db_range – Range of SNR values in dB

• labels – Labels for each channel

• num_symbols – Number of symbols for Monte Carlo simulation

• plot – Whether to generate and return a plot

• figsize – Figure size (width, height) in inches

• estimation_method – Method to estimate mutual information (‘histogram’ or ‘knn’)

Returns:

• SNR values

• Dictionary mapping channel names to capacity values

• Optional matplotlib figure if plot=True

Return type:

Tuple containing

mimo_capacity(snr_db_range: float | List[float] | ndarray | Tensor, tx_antennas: int = 2, rx_antennas: int = 2, channel_knowledge: str = 'perfect', num_realizations: int = 1000) → Tensor

Compute capacity for MIMO systems.

For MIMO systems, the capacity varies based on channel knowledge at the transmitter.

Parameters:

• snr_db_range – Range of SNR values in dB

• tx_antennas – Number of transmit antennas

• rx_antennas – Number of receive antennas

• channel_knowledge – Type of channel knowledge (‘perfect’, ‘statistical’, ‘none’)

• num_realizations – Number of channel realizations to average over

Returns:

MIMO capacity in bits per channel use

Return type:

torch.Tensor

capacity_gap_to_shannon(modulator: BaseModulator, channel: BaseChannel, snr_db_range: List[float] | ndarray | Tensor, num_symbols: int = 10000) → Tuple[Tensor, Tensor]

Compute the gap between a modulation scheme’s capacity and the Shannon limit.

This quantifies how close a practical modulation scheme comes to the theoretical limit.

Parameters:

• modulator – The modulation scheme

• channel – The channel model

• snr_db_range – Range of SNR values in dB

• num_symbols – Number of symbols for Monte Carlo simulation

Returns:

(SNR values, capacity gap in dB)

Return type:

Tuple[torch.Tensor, torch.Tensor]

capacity_cdf(channel: BaseChannel, snr_db: float, num_realizations: int = 10000) → Tuple[Tensor, Tensor]

Compute the cumulative distribution function (CDF) of capacity.

For fading channels, this shows the probability that capacity is less than a certain value.

Parameters:

• channel – The channel model (should be a fading channel)

• snr_db – Signal-to-noise ratio in dB

• num_realizations – Number of channel realizations

Returns:

(Capacity values, CDF values)

Return type:

Tuple[torch.Tensor, torch.Tensor]

spectral_efficiency(modulator: BaseModulator, channel: BaseChannel, snr_db_range: List[float] | ndarray | Tensor, bandwidth: float = 1.0, overhead: float = 0.0) → Tuple[Tensor, Tensor]

Calculate spectral efficiency for a modulation scheme.

Takes into account protocol overhead to give a realistic measure of efficiency.

Parameters:

• modulator – The modulation scheme

• channel – The channel model

• snr_db_range – Range of SNR values in dB

• bandwidth – Signal bandwidth in Hz

• overhead – Fraction of overhead (0 to 1) for protocols, pilots, etc.

Returns:

(SNR values, spectral efficiency in bits/s/Hz)

Return type:

Tuple[torch.Tensor, torch.Tensor]

energy_efficiency(modulator: BaseModulator, channel: BaseChannel, snr_db_range: List[float] | ndarray | Tensor, tx_power_watts: float = 1.0, circuit_power_watts: float = 0.1) → Tuple[Tensor, Tensor]

Calculate energy efficiency for a communication system.

Energy efficiency is defined as bits/joule, accounting for both transmission power and circuit power consumption.

Parameters:

• modulator – The modulation scheme

• channel – The channel model

• snr_db_range – Range of SNR values in dB

• tx_power_watts – Transmission power in watts

• circuit_power_watts – Circuit power consumption in watts

Returns:

(SNR values, energy efficiency in bits/joule)

Return type:

Tuple[torch.Tensor, torch.Tensor]