General Utilities

General utilities (optic.utils)

parameters()	Basic class to be used as a struct of parameters
lin2dB(x)	Convert linear value to dB (decibels).
dB2lin(x)	Convert dB (decibels) to a linear value.
dBm2W(x)	Convert dBm to Watts.
dec2bitarray(x, bit_width)	Converts a positive integer or an array-like of positive integers to a NumPy array of the specified size containing bits (0 and 1).
decimal2bitarray(x, bit_width)	Converts a positive integer to a NumPy array of the specified size containing bits (0 and 1).
dotNumba(a, b)	Computes the dot product of two 1D arrays in a Numba-compatible way.
bitarray2dec(x_bitarray)	Converts an input NumPy array of bits (0 and 1) to a decimal integer.
ber2Qfactor(ber)	Converts a bit error rate (BER) to a Q factor in dB.
llr2bitProb(llr[, prec])	Convert LLRs to bit probabilities using a numerically stable sigmoid.

ber2Qfactor(ber)

Converts a bit error rate (BER) to a Q factor in dB.

Parameters:

ber (float) – The bit error rate to be converted.

Returns:

The Q factor in dB, \(20\log_{10}Q\), corresponding to the input BER.

Return type:

float

Notes

For a binary signal with Gaussian noise, the bit error rate is related to the Q-factor by \(\mathrm{BER} = \frac{1}{2}\mathrm{erfc}\left(Q/\sqrt{2}\right)\), which is inverted as

\[Q = \sqrt{2}\,\mathrm{erfc}^{-1}(2\,\mathrm{BER}). \tag{1}\]

The value returned is the Q-factor in dB, following the usual convention

\[Q_{dB} = 20\log_{10}Q = 10\log_{10}Q^2, \tag{2}\]

so that, e.g., \(\mathrm{BER} = 10^{-9}\) corresponds to \(Q \approx 6\) and \(Q_{dB} \approx 15.6\) dB.

bitarray2dec(x_bitarray)

Converts an input NumPy array of bits (0 and 1) to a decimal integer.

Parameters:

x_bitarray (1D array of int) – Input NumPy array of bits.

Returns:

number – Integer representation(s) of the input bit array(s).

Return type:

int or array of int

dB2lin(x)

Convert dB (decibels) to a linear value.

Parameters:

x (float) – The value in dB to be converted to a linear value.

Returns:

The linear value.

Return type:

float

Notes

A (power) ratio expressed in decibels is converted to linear units as

\[x = 10^{x_{dB}/10}. \tag{1}\]

dBm2W(x)

Convert dBm to Watts.

Parameters:

x (float) – The power value in dBm to be converted to Watts.

Returns:

The power value in Watts.

Return type:

float

Notes

The dBm is the power level in decibels relative to 1 mW,

\[P_{W} = 10^{-3}\cdot 10^{P_{dBm}/10}, \tag{1}\]

so that 0 dBm corresponds to 1 mW and 30 dBm to 1 W.

dec2bitarray(x, bit_width)

Converts a positive integer or an array-like of positive integers to a NumPy array of the specified size containing bits (0 and 1).

Parameters:

• x (int or array-like of int) – Positive integer(s) to be converted to a bit array.

• bit_width (int) – Size of the output bit array.

Returns:

bitarray – Array containing the binary representation of all the input decimal(s).

Return type:

2D NumPy array of int

decimal2bitarray(x, bit_width)

Converts a positive integer to a NumPy array of the specified size containing bits (0 and 1). This version is slightly quicker but only works for one integer.

Parameters:

• x (int) – Positive integer to be converted to a bit array.

• bit_width (int) – Size of the output bit array.

Returns:

bitarray – Array containing the binary representation of the input decimal.

Return type:

1D NumPy array of int

dotNumba(a, b)

Computes the dot product of two 1D arrays in a Numba-compatible way.

This function is equivalent to np.dot for 1D arrays but can be JIT-compiled with Numba for accelerated execution.

Parameters:

• a (ndarray of shape (N,)) – First input array (complex-valued).

• b (ndarray of shape (N,)) – Second input array (complex-valued).

Returns:

result – The dot product of a and b, computed as the sum of element-wise products.

Return type:

complex

Notes

• Both input arrays must have the same length.

• This function initializes the result as a complex number to support complex-valued operations.

lin2dB(x)

Convert linear value to dB (decibels).

Parameters:

x (float) – The linear value to be converted to dB.

Returns:

The value converted to dB, i.e 10log10(x).

Return type:

float

Notes

The value in decibels of a (power) ratio \(x\) is

\[x_{dB} = 10\log_{10}x. \tag{1}\]

llr2bitProb(llr, prec=<class 'numpy.float32'>)

Convert LLRs to bit probabilities using a numerically stable sigmoid.

Parameters:

llrs (1D numpy array) – Log-likelihood ratios (LLRs) of bits.

Returns:

probs – Bit probabilities P(bit = 1).

Return type:

1D numpy array

Notes

With the log-likelihood ratio defined as \(\Lambda = \ln\left[P(b = 0)/P(b = 1)\right]\), the probability of the bit being equal to one is given by the logistic (sigmoid) function,

\[P(b = 1) = \frac{1}{1 + e^{\Lambda}}. \tag{1}\]

Eq. (1) is evaluated in a numerically stable way, which avoids the overflow of the exponential for LLRs of large magnitude.

class parameters

Basic class to be used as a struct of parameters

copy()

Returns a deep copy of the parameters object.

This method creates a new instance of the parameters class with the same attributes and values.

Returns:

A new instance of the parameters class with copied attributes.

Return type:

parameters

latex_table()

Generates a LaTeX table of the parameters and their values.

Returns:

A LaTeX table representation of the parameters and their values.

Return type:

str

table()

Generates a Markdown table of the parameters and their values.

Returns:

A Markdown table representation of the parameters and their values.

Return type:

str

to_engineering_notation(value)

Converts a numerical value to engineering notation with appropriate prefixes.

Parameters:

value (int or float) – The numerical value to be converted.

Returns:

The value formatted in engineering notation with a prefix, or the original value if it does not meet the criteria.

Return type:

str or value

view()

Prints the attributes and their values in either standard or scientific notation.