Digital Communications Utilities

Digital modulation utilities (`optic.comm.modulation`)

`grayCode`(n)	Gray code generator.
`grayMapping`(M, constType)	Gray Mapping for digital modulations.
`pamConst`(M)	Generate a Pulse Amplitude Modulation (PAM) constellation.
`qamConst`(M)	Generate a Quadrature Amplitude Modulation (QAM) constellation.
`pskConst`(M)	Generate a Phase Shift Keying (PSK) constellation.
`apskConst`(M[, m1, phaseOffset])	Generate an Amplitude-Phase Shift Keying (APSK) constellation.
`minEuclid`(symb, const)	Find minimum Euclidean distance.
`demap`(indSymb, bitMap)	Contellation symbol index to bit sequence demapping.
`modulateGray`(bits, M, constType)	Modulate bit sequences to constellation symbol sequences (w/ Gray mapping).
`demodulateGray`(symb, M, constType)	Demodulate symbol sequences to bit sequences (w/ Gray mapping).

apskConst(M, m1=None, phaseOffset=None)

Generate an Amplitude-Phase Shift Keying (APSK) constellation.

Parameters:

M (int) – Constellation order.
m1 (int) – Number of bits used to index the radii of the constellation.

Returns:

const – APSK constellation

Return type:

np.array

References

[1] Z. Liu, et al “APSK Constellation with Gray Mapping,” IEEE Communications Letters, vol. 15, no. 12, pp. 1271-1273, 2011.

[2] Proakis, J. G., & Salehi, M. Digital Communications (5th Edition). McGraw-Hill Education, 2008.

demap(indSymb, bitMap)

Contellation symbol index to bit sequence demapping.

Parameters:

indSymb (np.array of ints) – Indexes of received symbol sequence.
bitMap ((M, log2(M)) np.array) – bit-to-symbol mapping.

Returns:

decBits – Sequence of demapped bits.

Return type:

np.array

References

[1] Proakis, J. G., & Salehi, M. Digital Communications (5th Edition). McGraw-Hill Education, 2008.

demodulateGray(symb, M, constType)

Demodulate symbol sequences to bit sequences (w/ Gray mapping).

Hard demodulation is based on minimum Euclidean distance.

Parameters:

symb (array of complex constellation symbols) – sequence of constellation symbols to be demodulated.
M (int) – order of the modulation format.
constType (string) – ‘qam’, ‘psk’, ‘apsk’, ‘pam’ or ‘ook’.

Returns:

sequence of demodulated bits.

Return type:

array of ints

References

[1] Proakis, J. G., & Salehi, M. Digital Communications (5th Edition). McGraw-Hill Education, 2008.

detector(r, σ2, constSymb, px=None, rule='MAP')

Perform symbol detection using either the MAP (Maximum A Posteriori) or ML (Maximum Likelihood) rule.

Parameters:

r (np.array) – The received signal.
σ2 (float) – The noise variance.
constSymb (np.array) – The constellation symbols.
px (np.array, optional) – The prior probabilities of each symbol. If None, uniform priors are assumed.
rule (str, optional) – The detection rule to use. Either ‘MAP’ (default) or ‘ML’.

Returns:

tuple –
A tuple containing:
- np.array: The detected symbols.
- np.array: The indices of the detected symbols in the constellation.
Notes
——
If px is None or rule is ‘ML’, uniform priors are assumed.

References

[1] Proakis, J. G., & Salehi, M. Digital Communications (5th Edition). McGraw-Hill Education, 2008.

grayCode(n)

Gray code generator.

Parameters:: n (int) – length of the codeword in bits.
Returns:: code – list of binary strings of the gray code.
Return type:: list

grayMapping(M, constType)

Gray Mapping for digital modulations.

Parameters:

M (int) – modulation order
constType ('qam', 'psk', 'pam' or 'ook'.) – type of constellation.

Returns:

const – constellation symbols (sorted according their corresponding Gray bit sequence as integer decimal).

Return type:

np.array

References

[1] Proakis, J. G., & Salehi, M. Digital Communications (5th Edition). McGraw-Hill Education, 2008.

minEuclid(symb, const)

Find minimum Euclidean distance.

Find closest constellation symbol w.r.t the Euclidean distance in the complex plane.

Parameters:

symb (np.array) – Received constellation symbols.
const (np.array) – Reference constellation.

Returns:

indexes of the closest constellation symbols.

Return type:

np.array of int

References

[1] Proakis, J. G., & Salehi, M. Digital Communications (5th Edition). McGraw-Hill Education, 2008.

modulateGray(bits, M, constType)

Modulate bit sequences to constellation symbol sequences (w/ Gray mapping).

Parameters:

bits (array of ints) – sequence of data bits.
M (int) – order of the modulation format.
constType (string) – ‘qam’, ‘psk’, ‘apsk’, ‘pam’ or ‘ook’.

Returns:

bits modulated to complex constellation symbols.

Return type:

array of complex constellation symbols

References

[1] Proakis, J. G., & Salehi, M. Digital Communications (5th Edition). McGraw-Hill Education, 2008.

pamConst(M)

Generate a Pulse Amplitude Modulation (PAM) constellation.

Parameters:: M (int) – Number of symbols in the constellation. It must be an integer.
Returns:: 1D PAM constellation.
Return type:: np.array

References

[1] Proakis, J. G., & Salehi, M. Digital Communications (5th Edition). McGraw-Hill Education, 2008.

pskConst(M)

Generate a Phase Shift Keying (PSK) constellation.

Parameters:: M (int) – Number of symbols in the constellation. It must be a power of 2 positive integer.
Returns:: Complex M-PSK constellation.
Return type:: np.array

References

[1] Proakis, J. G., & Salehi, M. Digital Communications (5th Edition). McGraw-Hill Education, 2008.

qamConst(M)

Generate a Quadrature Amplitude Modulation (QAM) constellation.

Parameters:: M (int) – Number of symbols in the constellation. It must be a perfect square.
Returns:: const – Complex square M-QAM constellation.
Return type:: np.array

References

[1] Proakis, J. G., & Salehi, M. Digital Communications (5th Edition). McGraw-Hill Education, 2008.

Metrics for signal and performance characterization (`optic.comm.metrics`)

`bert`(Irx[, bitsTx, seed])	Calculate Bit Error Rate (BER) and Q-factor for optical communication using On-Off Keying (OOK).
`fastBERcalc`(rx, tx, M, constType)	Monte Carlo BER/SER/SNR calculation.
`calcLLR`(rxSymb, σ2, constSymb, bitMap, px)	LLR calculation (circular AGWN channel).
`monteCarloGMI`(rx, tx, M, constType[, px])	Monte Carlo based generalized mutual information (GMI) estimation.
`monteCarloMI`(rx, tx, M, constType[, px])	Monte Carlo based mutual information (MI) estimation.
`Qfunc`(x)	Calculate function Q(x).
`calcEVM`(symb, M, constType[, symbTx])	Calculate error vector magnitude (EVM) metrics.
`theoryBER`(M, EbN0, constType)	Theoretical (approx.) bit error probability for PAM/QAM/PSK in AWGN channel.
`theoryMI`(M, constType, SNR[, pX, symetry, ...])	Calculate mutual information for discrete input continuous output the memoryless AWGN channel (DCMC).
`calcLinOSNR`(Ns, Pin, α, Ls, OSNRin[, NF, ...])	Calculate the OSNR evolution in a multi-span fiber transmission system.

Qfunc(x)

Calculate function Q(x).

Parameters:: x (scalar) – function input.
Returns:: value of Q(x).
Return type:: scalar

References

[1] Proakis, J. G., & Salehi, M. Digital Communications (5th Edition). McGraw-Hill Education, 2008.

bert(Irx, bitsTx=None, seed=123)

Calculate Bit Error Rate (BER) and Q-factor for optical communication using On-Off Keying (OOK).

Parameters:

Irx (numpy.np.array) – Received signal intensity values.
bitsTx (numpy.np.array, optional) – Transmitted bit sequence. If not provided, a random bit sequence is generated.
seed (int, optional) – Random seed for bit sequence generation when bitsTx is not provided.

Returns:

BER (float) – Bit Error Rate, a measure of the number of erroneous bits relative to the total bits.
Q (float) – Q-factor, a measure of signal quality in the communication system.

Notes

This function calculates the BER and Q-factor for an optical communication system using On-Off Keying (OOK) modulation. The received signal intensity Irx and an optional transmitted bit sequence bitsTx are required. If bitsTx is not provided, a random bit sequence is generated using the specified seed.

The following statistics are calculated for the received signal: - I1: The average value of the signal when the transmitted bit is 1. - I0: The average value of the signal when the transmitted bit is 0. - std1: The standard deviation of the signal when the transmitted bit is 1. - std0: The standard deviation of the signal when the transmitted bit is 0.

The optimal decision threshold Id and the Q-factor are calculated based on the signal statistics.

The function then applies the optimal decision rule to estimate the received bit sequence bitsRx. The Bit Error Rate (BER) is calculated by comparing bitsRx to bitsTx.

References

[1] Agrawal, Govind P. Fiber-optic communication systems. John Wiley & Sons, 2012.

calcEVM(symb, M, constType, symbTx=None)

Calculate error vector magnitude (EVM) metrics.

Parameters:

symb (np.array) – Sequence of noisy symbols.
M (int) – Constellation order.
constType (TYPE) – DESCRIPTION.
symbTx (np.array, optional) – Sequence of transmitted symbols (noiseless). The default is [].

Returns:

EVM – Error vector magnitude (EVM) per signal dimension.

Return type:

np.array

References

[1] R. A. Shafik, et al, “On the error vector magnitude as a performance metric and comparative analysis”, em 2006 International Conference on Emerging Technologies, 2006, p. 27–31. doi: 10.1109/ICET.2006.335992.

[2] H. A. Mahmoud e H. Arslan, “Error vector magnitude to SNR conversion for nondata-aided receivers”, IEEE Transactions on Wireless Communications, vol. 8, nº 5, p. 2694–2704, 2009, doi: 10.1109/TWC.2009.080862.

calcLLR(rxSymb, σ2, constSymb, bitMap, px)

LLR calculation (circular AGWN channel).

Parameters:

rxSymb (np.array) – Received symbol sequence.
σ2 (scalar) – Noise variance.
constSymb ((M, 1) np.array) – Constellation symbols.
px ((M, 1) np.array) – Prior symbol probabilities.
bitMap ((M, log2(M)) np.array) – Bit-to-symbol mapping.

Returns:

LLRs – sequence of calculated LLRs.

Return type:

np.array

References

[1] A. Alvarado, T. Fehenberger, B. Chen, e F. M. J. Willems, “Achievable Information Rates for Fiber Optics: Applications and Computations”, Journal of Lightwave Technology, vol. 36, nº 2, p. 424–439, jan. 2018, doi: 10.1109/JLT.2017.2786351.

calcLinOSNR(Ns, Pin, α, Ls, OSNRin, NF=4.5, Fc=193100000000000.0, Bref=12500000000.0)

Calculate the OSNR evolution in a multi-span fiber transmission system.

Parameters:

Ns (int) – Number of spans of fiber + EDFA.
Pin (scalar) – Fiber launch power.
α (scalar) – Fiber attenuation coefficient in dB/km.
Ls (scalar) – Length of fiber spans in km.
OSNRin (scalar) – OSNR at the input of the first span.
NF (scalar, optional) – Noise figure of the EDFA amplifiers. The default is 4.5.
Fc (scalar, optional) – Optical central frequency. The default is 193.1e12.
Bref (scalar, optional) – Reference bandwidth for OSNR measurement. The default is 12.5e9.

Returns:

OSNR – OSNR values in dB at the output of each fiber span.

Return type:

np.array

References

[1] J. G. Proakis; M. Salehi, Communication Systems Engineering, 2nd Edition. Pearson, 2002.

[2] R. -J. Essiambre, et al, “Capacity Limits of Optical Fiber Networks,” Journal of Lightwave Technology, vol. 28, no. 4, p. 662-701, 2010, doi: 10.1109/JLT.2009.2039464.

[3] R. Schober, P. Bayvel, e F. D. Pasquale, “Analytical model for the calculation of the optical signal-to-noise ratio (SNR) of WDM EDFA chains”, Optical and Quantum Electronics, vol. 31, no 3, p. 237–241. 1999, doi: 10.1023/A:1006948826091.

calcMI(rx, tx, σ2, constSymb, pX)

Mutual information (MI) calculation (circular AGWN channel).

Parameters:

rx (np.array) – Received symbol sequence.
tx (np.array) – Transmitted symbol sequence.
σ2 (scalar) – Noise variance.
constSymb ((M, 1) np.array) – Constellation symbols.
pX ((M, 1) np.array) – prob. mass function (p.m.f.) of the constellation symbols.

Returns:

Estimated mutual information.

Return type:

scalar

References

[1] A. Alvarado, T. Fehenberger, B. Chen, e F. M. J. Willems, “Achievable Information Rates for Fiber Optics: Applications and Computations”, Journal of Lightwave Technology, vol. 36, nº 2, p. 424–439, jan. 2018, doi: 10.1109/JLT.2017.2786351.

fastBERcalc(rx, tx, M, constType)

Monte Carlo BER/SER/SNR calculation.

Parameters:

rx (np.array) – Received symbol sequence.
tx (np.array) – Transmitted symbol sequence.
M (int) – Modulation order.
constType (string) – Modulation type: ‘qam’, ‘psk’, ‘pam’ or ‘ook’.

Returns:

BER (np.array) – Bit-error-rate.
SER (np.array) – Symbol-error-rate.
SNR (np.array) – Estimated SNR from the received constellation.

References

[1] Proakis, J. G., & Salehi, M. Digital Communications (5th Edition). McGraw-Hill Education, 2008.

monteCarloGMI(rx, tx, M, constType, px=None)

Monte Carlo based generalized mutual information (GMI) estimation.

Parameters:

rx (np.array) – Received symbol sequence.
tx (np.array) – Transmitted symbol sequence.
M (int) – Modulation order.
constType (string) – Modulation type: ‘qam’ or ‘psk’
px ((M, 1) np.array) – Prior symbol probabilities. The default is [].

Returns:

GMI (np.array) – Generalized mutual information values.
NGMI (np.array) – Normalized mutual information.

References

[1] A. Alvarado, T. Fehenberger, B. Chen, e F. M. J. Willems, “Achievable Information Rates for Fiber Optics: Applications and Computations”, Journal of Lightwave Technology, vol. 36, nº 2, p. 424–439, jan. 2018, doi: 10.1109/JLT.2017.2786351.

monteCarloMI(rx, tx, M, constType, px=None)

Monte Carlo based mutual information (MI) estimation.

Parameters:

rx (np.array) – Received symbol sequence.
tx (np.array) – Transmitted symbol sequence.
M (int) – Modulation order.
constType (string) – Modulation type: ‘qam’ or ‘psk’
pX ((M, 1) np.array) – p.m.f. of the constellation symbols. The default is [].

Returns:

MI – Estimated MI values.

Return type:

np.array

References

[1] A. Alvarado, T. Fehenberger, B. Chen, e F. M. J. Willems, “Achievable Information Rates for Fiber Optics: Applications and Computations”, Journal of Lightwave Technology, vol. 36, nº 2, p. 424–439, jan. 2018, doi: 10.1109/JLT.2017.2786351.

theoryBER(M, EbN0, constType)

Theoretical (approx.) bit error probability for PAM/QAM/PSK in AWGN channel.

Parameters:

M (int) – Modulation order.
EbN0 (scalar) – Signal-to-noise ratio (SNR) per bit in dB.
constType (string) – Modulation type: ‘pam’, ‘qam’ or ‘psk’

Returns:

Pb – Theoretical probability of bit error.

Return type:

scalar

Notes

The values of error probability obtained with this function are good approximations for moderate to high SNR regime (see [1]). All cases assume Gray mapped constellations. For low SNR values and high constellation cardinalities (Pb>1e-1), the results should underestimate the real error probability.

References

[1] Proakis, J. G., & Salehi, M. Digital Communications (5th Edition). McGraw-Hill Education, 2008.

theoryMI(M, constType, SNR, pX=None, symetry=True, lim=inf, tol=0.001)

Calculate mutual information for discrete input continuous output the memoryless AWGN channel (DCMC).

Parameters:

M (int) – Number of symbols in the constellation.
constType (str) – Type of constellation (‘qam’, ‘psk’).
SNR (float) – Signal-to-noise ratio in dB.
pX (array_like, optional) – Probability of each transmitted symbol (default is None).
symetry (bool, optional) – Flag to exploit rotational symmetry of the constellation (default is True).
lim (int, optional) – Limit for numerical integration (default is np.inf).
tol (float, optional) – Tolerance for numerical integration error (default is 1e-3).

Returns:

Mutual information for the given parameters.

Return type:

float

References

[1] A. Alvarado, T. Fehenberger, B. Chen, e F. M. J. Willems, “Achievable Information Rates for Fiber Optics: Applications and Computations”, Journal of Lightwave Technology, vol. 36, nº 2, p. 424–439, jan. 2018, doi: 10.1109/JLT.2017.2786351.

OFDM utilities (`optic.comm.ofdm`)

`hermit`(V)	Hermitian simmetry block.
`zeroPad`(x, L)	Pad an input array with zeros on both sides.
`calcSymbolRate`(M, Rb, Nfft, Np, G, hermitSym)	Calculate the symbol rate of a given OFDM configuration.
`modulateOFDM`(symb, param)	Modulate OFDM signal.
`demodulateOFDM`(sig, param)	Demodulate OFDM signal.

calcSymbolRate(M, Rb, Nfft, Np, G, hermitSym)

Calculate the symbol rate of a given OFDM configuration.

Parameters:

M (scalar) – constellation order
Rb (scalar) – bit rate
Nfft (scalar) – size of FFT
Np (scalar) – number of pilot subcarriers
G (scalar) – cyclic prefix length
hermitSym (boolean) – True: Real OFDM symbols / False: Complex OFDM symbols

Returns:

Rs – OFDM symbol rate

Return type:

scalar

demodulateOFDM(sig, param)

Demodulate OFDM signal.

Parameters:

sig (np.np.array) – Complex-valued array representing the OFDM signal sequence received at one sample per symbol.
param (optic.utils.parameters object) –
An object containing the parameters for OFDM demodulation.
- Nfft : scalar, optional. Size of the FFT. Default is 512.
- N : scalar, optional. Number of transmitted subcarriers. Default is calculated based on Nfft.
- G : scalar, optional. Cyclic prefix length. Default is 4.
- hermitSymmetry : bool, optional.If True, indicates real OFDM symbols; if False, indicates complex OFDM symbols. Default is False.
- pilot : complex-valued scalar, optional. Pilot symbol. Default is 1 + 1j.
- pilotCarriers : np.array, optional.Indexes of pilot subcarriers. Default is an empty array.
- returnChannel : bool, optional. If True, return the estimated channel. Default is False.

Returns:

If returnChannel is False, returns a complex-valued array representing the demodulated symbols sequence received. If returnChannel is True, returns a tuple containing the demodulated symbols sequence received and the estimated channel.

Return type:

np.array or tuple

Notes

The input signal must be sampled at one sample per symbol.
This function performs demodulation of the OFDM signal according to the provided parameters, including channel estimation and single tap equalization.

References

[1] Proakis, J. G., & Salehi, M. Digital Communications (5th Edition). McGraw-Hill Education, 2008.

hermit(V)

Hermitian simmetry block.

Parameters:: V (complex-valued np.array) – input array
Returns:: Vh – vector with hermitian simmetry
Return type:: complex-valued np.array

modulateOFDM(symb, param)

Modulate OFDM signal.

Parameters:

symb (np.np.array) – Complex-valued array of modulation symbols representing the symbols sequence to be transmitted.
param (optic.utils.parameters object) –
An object containing the parameters for OFDM modulation. - Nfft : scalar, optional. Size of the FFT. Default is 512.
- G : scalar, optional. Cyclic prefix length. Default is 4.
- hermitSymmetry : bool, optional. If True, indicates real OFDM symbols; if False, indicates complex OFDM symbols. Default is False.
- pilot : complex-valued scalar, optional. Pilot symbol. Default is 1 + 1j.
- pilotCarriers : np.array, optional. Indexes of pilot subcarriers. Default is an empty array.
- SpS : int, optional. Oversampling factor. Default is 2.

Returns:

Complex-valued array representing the OFDM symbols sequence transmitted.

Return type:

np.array

References

[1] Proakis, J. G., & Salehi, M. Digital Communications (5th Edition). McGraw-Hill Education, 2008.

zeroPad(x, L)

Pad an input array with zeros on both sides.

Parameters:

x (array_like) – Input array to be padded.
L (int) – Number of zeros to pad on each side of the array.

Returns:

padded_array – Padded array with zeros added at the beginning and end.

Return type:

np.array

Notes

This function pads the input array x with L zeros on both sides, effectively increasing its length by 2*L.

Digital Communications Utilities

Digital modulation utilities (optic.comm.modulation)

Metrics for signal and performance characterization (optic.comm.metrics)

OFDM utilities (optic.comm.ofdm)

Digital modulation utilities (`optic.comm.modulation`)

Metrics for signal and performance characterization (`optic.comm.metrics`)

OFDM utilities (`optic.comm.ofdm`)