<commit_before>% 
% MODULE : modem
%

\newpage
\section{modem}
\label{module:modem}
The modem module implements a set of (mod)ulation/(dem)odulation schemes
for encoding information into signals.
For the analog modems, samples are encoded according to frequency or
analog modulation.
For the digital modems, data bits are encoded into symbols representing
carrier frequency, phase, amplitude, etc.
This section gives a brief overview of modulation schemes available in
\liquid, and provides a brief description of the interfaces.


%
% ANALOG MODEMS
%

\subsection{Analog modulation schemes}
\label{module:modem:analog}
This section describes the two basic analog modulation schemes available
in \liquid:
frequency modulation and amplitude modulation
implemented with the respective {\tt freqmodem} and {\tt ampmodem}
objects.

\subsubsection{{\tt freqmodem} (analog FM)}
\label{module:modem:analog:freqmodem}
The {\tt freqmodem} object implements an analog frequency modulation
(FM) modulator and demodulator.
Given an input message signal $-1 \le s(t) \le 1$, the transmitted
signal is
%
\begin{equation}
\label{eqn:modem:freqmodem_tx}
    s(t) =  \exp\left\{
                j 2 \pi k f_c
                \int_{0}^{t}{
                    s(\tau)d\tau
                }
            \right\}
\end{equation}
%
where $f_c$ is the carrier frequency, and $k$ is the modulation index.
The modulation index governs the relative bandwidth of the signal.
Two options for demodulation are possible:
observing the instantaneous frequency on the output of a phase-locked
loop,
or computing the instantaneous frequency using the delay-conjugate
method.
%Its digital equivalent is
%\[
%    s(nT_s) =   \exp\left\{
%                    j 2 \pi k f_c
%                    \sum_{k=0}^{n}{
%                        m(kT_s)
%                    }
%                \right\}
%\]
%
An example of the {\tt freqmodem} interface is listed below.
%
\input{listings/freqmodem.example.c.tex}
%
A more detailed example can be found in
{\tt examples/freqmodem\_example.c}
located under the main \liquid\ project source directory.
Listed below is the full interface to the {\tt freqmodem} object for
analog frequency modulation/demodulation.
%
\begin{description}
\item[{\tt freqmodem\_create(k,fc,type)}]
    creates and returns an {\tt freqmodem} object with a modulation
    index $k$, a carrier frequency $-0.5 < f_c < 0.5$, and a
    demodulation type defined by {\tt type}.
    The demodulation type can either be
    {\tt LIQUID\_MODEM\_FM\_PLL} which uses a phased-locked loop or
    {\tt LIQUID\_MODEM\_FM\_DELAY\_CONJ} which uses the delay conjugate
    method.
\item[{\tt freqmodem\_destroy(q)}]
    destroys an {\tt freqmodem} object, freeing all internally-allocated
    memory.
\item[{\tt freqmodem\_reset(q)}]
    resets the state of the {\tt freqmodem} object.
\item[{\tt freqmodem\_print(q)}]
    prints the internal state of the {\tt freqmodem} object.
\item[{\tt freqmodem\_modulate(q,x,*y)}]
    modulates the input sample $x$ storing the output to $y$.
\item[{\tt freqmodem\_demodulate(q,y,*x)}]
    demodulates the input sample $y$ storing the output to $x$.
\end{description}

% TODO : clean up this section!
\subsubsection{{\tt ampmodem} (analog AM)}
\label{module:modem:analog:ampmodem}
The {\tt ampmodem} object implements an analog amplitude modulation (AM)
modulator/demodulator pair.
Two basic transmission schemes are available:
single side-band (SSB), and
double side-band (DSB).
%
For an input message signal $-1 \le s(t) \le 1$, the double side-band
transmitted signal is
%
\begin{equation}
\label{eqn:modem:ampmodem:dsb_tx}
    x_{DSB}(t) = 
    \begin{cases}
        s(t)e^{j 2 \pi f_c t}   &   \text{suppressed carrier} \\
        \frac{1}{2}\bigl(1+ks(t)\bigr)e^{j 2 \pi f_c t}   &   \text{unsuppressed carrier}
    \end{cases}
\end{equation}
%
where $f_c$ is the carrier frequency, and $k$ is the modulation index.
%
For single side-band, only the upper (USB) or lower half (LSB)
of the spectrum is transmitted.
The opposing half of the spectrum is rejected using a Hilbert transform
(see Section~\ref{module:filter:firhilb}).
Let $\dot{s}(t)$ represent the Hilbert transform of the message signal
$s(t)$ such that its Fourier transform is non-zero only for positive
frequency components, viz
%
\begin{equation}
\label{eqn:modem:ampmodem:ssb_hilbert}
    \dot{S}(\omega) = \F\left\{ \dot{s}(t) \right\} =
    \begin{cases}
        S(\omega) = \F\left\{ s(t) \right\} & \omega > 0 \\
        0                                   & \omega \leq 0
    \end{cases}
\end{equation}
%
Consequently the transmitted upper side-band signal is
%
\begin{equation}
\label{eqn:modem:ampmodem:ssb_tx}
    x_{USB}(t) = 
    \begin{cases}
        \dot{s}(t)e^{j 2 \pi f_c t}   &   \text{suppressed carrier} \\
        \frac{1}{2}\bigl(1+k\dot{s}(t)\bigr)e^{j 2 \pi f_c t}   &   \text{unsuppressed carrier}
    \end{cases}
\end{equation}
%
For lower single side-band, $\dot{s}(t)$ is simply conjugated.
%
For suppressed carrier modulation the receiver uses a phase-locked loop for
carrier frequency and phase tracking.
When the carrier is not suppressed the receiver demodulates using a
simple peak detector and IIR bias removal filter.
%
An example of the {\tt freqmodem} interface is listed below.
%
\input{listings/ampmodem.example.c.tex}
%
A more detailed example can be found in
{\tt examples/ampmodem\_example.c}
located under the main \liquid\ project source directory.
Listed below is the full interface to the {\tt ampmodem} object for
analog frequency modulation/demodulation.
%
\begin{description}
\item[{\tt ampmodem\_create(k,type,suppressed\_carrier)}]
    creates and returns an {\tt ampmodem} object with a modulation
    index $k$,
    a modulation scheme defined by {\tt type},
    and a binary flag specifying whether the carrier should be
    suppressed.
    The modulation type can either be
    {\tt LIQUID\_MODEM\_AM\_DSB} (double side-band),
    {\tt LIQUID\_MODEM\_FM\_USB} (single upper side-band), or
    {\tt LIQUID\_MODEM\_FM\_LSB} (single lower side-band).
    method.
\item[{\tt ampmodem\_destroy(q)}]
    destroys an {\tt ampmodem} object, freeing all internally-allocated
    memory.
\item[{\tt ampmodem\_reset(q)}]
    resets the state of the {\tt ampmodem} object.
\item[{\tt ampmodem\_print(q)}]
    prints the internal state of the {\tt ampmodem} object.
\item[{\tt ampmodem\_modulate(q,x,*y)}]
    modulates the input sample $x$ storing the output to $y$.
\item[{\tt ampmodem\_demodulate(q,y,*x)}]
    demodulates the input sample $y$ storing the output to $x$.
\end{description}


%\subsection{Continuous phase digital modulation schemes}
%fsk, msk, etc. [NOTE: not yet implemented]



%
% LINEAR DIGITAL MODEMS
%

\subsection{Linear digital modulation schemes}
\label{module:modem:digital}
The {\tt modem} object realizes the linear digital modulation library in which
the information from a symbol is encoded into the amplitude and phase of a
sample.
The modem structure implements a variety of common modulation schemes,
including (differential) phase-shift keying, and (quadrature) amplitude-shift
keying.
The input/output relationship for modulation/demodulation for the {\tt modem}
object is
strictly one-to-one and is independent of any pulse shaping, or interpolation.
%This differs from {\tt cpmodem} in which the pulse shaping filter is
%integrated into the modem itself.

In general, linear modems demodulate by finding the closest of $M$
symbols in the set $\mathcal{S}_M = \{s_0,s_1,\ldots,s_{M-1}\}$ 
to the received symbol $r$, viz
%
\begin{equation}
\label{eqn:modem:demod}
    \underset{s_k \in \mathcal{S}_M}{\arg\min}
    \bigl\{
        \| r - s_k \|
    \bigr\}
\end{equation}
%
For arbitrary modulation schemes a linear search over all symbols in
$\mathcal{S}_M$ is required which has a complexity of $\ord(M^2)$, however one may
take advantage of symmetries in certain constellations to reduce this.
%For example, $M$-ary PSK distributes its symbols evenly throughout the phase
%of the transmitted signal...

% ------------ TABLE: LINEAR MODULATION SCHEMES ------------
\begin{table*}
\caption{Linear Modulation Schemes Available in \liquid}
\label{tab:modem:schemes}
\centering
{\small
\begin{tabular*}{0.95\textwidth}{l@{\extracolsep{\fill}}ll}
\toprule
{\it scheme} &
{\it depth range (bits/symbol)} &
{\it description}\\\otoprule
%
{\tt LIQUID\_MODEM\_UNKNOWN}    & -     & unknown/unsupported scheme\\
{\tt LIQUID\_MODEM\_PSK}        & 1|8   & phase-shift keying\\
{\tt LIQUID\_MODEM\_DPSK}       & 1|8   & differential phase-shift keying\\
{\tt LIQUID\_MODEM\_ASK}        & 1|8   & amplitude-shift keying\\
{\tt LIQUID\_MODEM\_QAM}        & 2|8   & quadrature amplitude-shift keying\\
{\tt LIQUID\_MODEM\_APSK}       & 2|8   & amplitude/phase-shift keying\\
{\tt LIQUID\_MODEM\_ARB}        & 1|8   & arbitrary signal constellation\\\midrule
%
{\tt LIQUID\_MODEM\_BPSK}       & 1     & binary phase-shift keying\\
{\tt LIQUID\_MODEM\_QPSK}       & 2     & quaternary phase-shift keying\\
{\tt LIQUID\_MODEM\_OOK}        & 1     & on/off keying\\
{\tt LIQUID\_MODEM\_SQAM32}     & 5     & ``square'' 32-QAM\\
{\tt LIQUID\_MODEM\_SQAM128}    & 7     & ``square'' 128-QAM\\
{\tt LIQUID\_MODEM\_V29}        & 4     & V.29 star modem\\
{\tt LIQUID\_MODEM\_ARB16OPT}   & 4     & optimal 16-QAM\\
{\tt LIQUID\_MODEM\_ARB32OPT}   & 5     & optimal 32-QAM\\
{\tt LIQUID\_MODEM\_ARB64OPT}   & 6     & optimal 64-QAM\\
{\tt LIQUID\_MODEM\_ARB128OPT}  & 7     & optimal 128-QAM\\
{\tt LIQUID\_MODEM\_ARB256OPT}  & 8     & optimal 256-QAM\\
{\tt LIQUID\_MODEM\_ARB64VT}    & 6     & Virginia Tech logo\\\bottomrule
% 
\end{tabular*}
}
\end{table*}%
% ------------------------


\subsubsection{Interface}
\label{module:modem:digital:interface}
\begin{description}
\item[{\tt modem\_create(scheme,bps)}]
    creates a linear modulator/demodulator {\tt modem} object with one
    of the schemes defined in Table~\ref{tab:modem:schemes}
    with {\tt bps} bits per symbol.
\item[{\tt modem\_destroy(q)}]
    destroys a {\tt modem} object, freeing all internally-allocated
    memory.
\item[{\tt modem\_print(q)}]
    prints the internal state of the object.
\item[{\tt modem\_reset(q)}]
    resets the internal state of the object.
    This method is really only relevant to {\tt LIQUID\_MODEM\_DPSK}
    (differential phase-shift keying) which retains the phase of the
    previous symbol in memory.
    All other modulation schemes are memoryless.
\item[{\tt modem\_arb\_init(q,*map,n)}]
    initializes an arbitrary modem ({\tt LIQUID\_MODEM\_ARB}) with the $n$-point
    constellation map.
    The resulting constellation is normalized such that it is centered
    at zero and has unity energy.
\item[{\tt modem\_arb\_init\_file(q,*filename)}]
    initializes an arbitrary modem ({\tt LIQUID\_MODEM\_ARB}) with a constellation
    map defined in an external file.
    The file includes one line per symbol with the in-phase and
    quadrature components separated by white space, e.g.
    %
    \begin{Verbatim}[fontsize=\small]
       1.46968   0.13529
       1.69067   0.71802
      -0.85603   0.43542
      -0.56563   1.50369
       0.45232   0.42128
          ...
    \end{Verbatim}
    %
    The resulting constellation is normalized such that it is centered
    at zero and has unity energy.
\item[{\tt modem\_modulate(q,symbol,*x)}]
    modulates the integer symbol storing the result in the output value
    of $x$.
    The input symbol value must be less than the constellation size $M$.
\item[{\tt modem\_demodulate(q,x,*symbol)}]
    finds the closest integer symbol which matches the input sample $x$.
    The exact method by which \liquid\ performs this computation is
    dependent upon the modulation scheme.
    For example, while
    {\tt LIQUID\_MODEM\_QAM} ($M=4$), and
    {\tt LIQUID\_MODEM\_PSK} ($M=4$)
    are effectively equivalent (four points on the unit circle)
    they are demodulated differently.
\item[{\tt modem\_get\_demodulator\_phase\_error(q)}]
    returns an angle proportional to the phase error after demodulation.
    This value can be used in a phase-locked loop
    (see Section~\ref{module:nco:pll})
    to correct for carrier phase recovery.
\item[{\tt modem\_get\_demodulator\_evm(q)}]
    returns a value equal to the error vector magnitude after demodulation.
    The error vector is the difference between the received symbol and the
    estimated transmitted symbol, $e = r - \hat{s}$.
    The magnitude of the error vector is an indication to the
    signal-to-noise/distortion ratio at receiver.
\end{description}

While the same modem structure may be used for both modulation and
demodulation for most schemes, it is important to use separate objects
for differential-mode modems (e.g. {\tt LIQUID\_MODEM\_DPSK}) as the internal state
will change after each symbol.
It is usually good practice to keep separate instances of modulators and
demodulators.
This holds true for most any encoder/decoder pair in \liquid.
%
An example of the {\tt qmodem} interface is listed below.
%
\input{listings/modem.example.c.tex}
%

\subsubsection{Gray coding}
\label{module:modem:digital:gray_coding}
In order to reduce the number of bit errors in a digital modem,
all symbols are automatically Gray encoded such that
adjacent symbols in a constellation differ by only one bit.
%
For example, the binary-coded decimal (BCD) value of 183 is {\tt 10110111}.
It has adjacent symbol 184 ({\tt 10111000}) which differs by 4 bits.
Assume the transmitter sends 183 without encoding.
If noise at the receiver were to cause it to demodulate the nearby
symbol 184, the result would be 4 bit errors.
%
Gray encoding is computed to the binary-coded decimal symbol
by applying an exclusive OR bitmask of itself shifted to the right by a
single bit.
%
\begin{Verbatim}[fontsize=\small]
            10110111    bcd_in (183)        10111000    bcd_in (184)
            .1011011    bcd_in >> 1         .1011100    bcd_in >> 1
    xor :   --------                        --------
            11101100    gray_out (236)      11100100    gray_out (228)
\end{Verbatim}
%
Notice that the two encoded symbols
236 ({\tt 11101100}) and
228 ({\tt 11100100}) differ by only one bit.
Now if noise caused the receiver were to demodulate a symbol error, it would
result in only a single bit error instead of 4 without Gray coding.

Reversing the process (decoding) is similar to encoding but slightly
more involved.
Gray decoding is computed on an encoded input symbol by adding to it
(modulo 2) as many shifted versions of itself as it has bits.
In our previous example the receiver needs to map the received encoded
symbol back to the original symbol before encoding:
%
\begin{Verbatim}[fontsize=\small]
            11101100    gray_in (236)       11100100    gray_in (228)
            .1110110    gray_in >> 1        .1110010    gray_in >> 1
            ..111011    gray_in >> 2        ..111001    gray_in >> 2
            ...11101    gray_in >> 3        ...11100    gray_in >> 3
            ....1110    gray_in >> 4        ....1110    gray_in >> 4
            .....111    gray_in >> 5        .....111    gray_in >> 5
            ......11    gray_in >> 6        ......11    gray_in >> 6
            .......1    gray_in >> 7        .......1    gray_in >> 7
    xor :   --------                        --------
            10110111    gray_out (183)      10111000    gray_out (184)
\end{Verbatim}
%
There are a few interesting characteristics of Gray encoding:
\begin{itemize}
\item the first bit never changes in encoding/decoding
\item there is a unique mapping between input and output symbols
\end{itemize}
It is also interesting to note that in linear modems (e.g. PSK), the
{\tt decoder} is actually applied to the symbol at the transmitter while the
{\tt encoder} is applied to the received symbol at the receiver.
%This is somewhat counterintuitive and is because...
In \liquid, Gray encoding and decoding are computed with the
{\tt gray\_encode()} {\tt gray\_decode()} methods, respectively.

\subsubsection{{\tt LIQUID\_MODEM\_PSK} (phase-shift keying)}
\label{module:modem:digital:PSK}
With phase-shift keying the information is stored in the absolute phase
of the modulated signal.
This means that each of $M=2^m$ symbols in the constellation are equally
spaced around the unit circle.
%
%-------------------- FIGURE: PSK MODEM --------------------
\begin{figure}
\centering
\mbox{
  \subfigure[2-PSK (generic BPSK)]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_psk2}
      \label{fig:modem:psk:2}
    } \quad
  \subfigure[4-PSK (generic QPSK)]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_psk4}
      \label{fig:modem:psk:4}
    } \quad
}
\mbox{
  \subfigure[8-PSK]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_psk8}
      \label{fig:modem:psk:8}
    } \quad
  \subfigure[16-PSK]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_psk16}
      \label{fig:modem:psk:16}
    } \quad
}
\mbox{
  \subfigure[32-PSK]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_psk32}
      \label{fig:modem:psk:32}
    } \quad
  \subfigure[64-PSK]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_psk64}
      \label{fig:modem:psk:64}
    } \quad
}
% trim = left bottom right top
\caption{
    Phase-shift keying (PSK) modem constellation map.
    Note that BPSK and QPSK are customized implementations of 2-PSK and
    4-PSK.
    While only PSK up to $M=64$ are shown, \liquid\ supports up to
    256-PSK.
}
\label{fig:modem:psk}
\end{figure}
%
Figure~\ref{fig:modem:psk} depicts the constellation of PSK up to $M=16$
with the bits gray encoded.
While \liquid\ supports up to $M=256$, values greater than $M=32$
are typically avoided due to error rates for practical signal-to-noise
ratios.
%
For an $M$-symbol constellation, the $k^{th}$ symbol is
%
\begin{equation}
    s_k = e^{j 2 \pi k/M}
\end{equation}
%
where $k \in \{0,1,\ldots,M-1\}$.
Specific schemes include BPSK ($M=2$),
%
\begin{equation}
    s_k = e^{j \pi k} =
    \begin{cases}
        +1 & k=0 \\
        -1 & k=1
    \end{cases}
\end{equation}
%
and QPSK ($M=4$)
%
\begin{equation}
    s_k = e^{j\left(\pi k/4 + \frac{\pi}{4}\right)}
\end{equation}
%
Demodulation is performed independent of the signal amplitude for
coherent PSK.


\subsubsection{{\tt LIQUID\_MODEM\_DPSK} (differential phase-shift keying)}
\label{module:modem:digital:DPSK}
Differential PSK (DPSK) encodes information in the phase change of the
carrier.
Like regular PSK
demodulation is performed independent of the signal amplitude;
however because the data are encoded using phase transitions rather than
absolute phase, the receiver does not have to know the absolute phase of
the transmitter.
This allows the receiver to demodulate incoherently, but at a quality
degradation of 3dB.
%
As such the $n^{th}$ transmitted symbol $k(n)$ depends on the previous
symbol, viz
%
\begin{equation}
    s_k(n) = \exp\left\{
                \frac{
                    j 2 \pi \Bigl(k(n) - k(n-1)\Bigr)
                } {
                    M
                }
            \right\}
\end{equation}

\subsubsection{{\tt LIQUID\_MODEM\_APSK} (amplitude/phase-shift keying}
\label{module:modem:digital:APSK}
Amplitude/phase-shift keying (APSK) is a specific form of quadrature
amplitude modulation where constellation points lie on concentric
circles.
The constellation points are further apart than those of PSK/DPSK,
resulting in an improved error performance.
Furthermore the phase recovery for APSK is improved over regular QAM as
the constellation points are less sensitive to phase noise.
This improvement comes at the cost of an increased computational
complexity at the receiver.
%
Demodulation follows as a two-step process: first, the amplitude of the
received signal is evaluated to determine in which level (``ring'') the
transmitted symbol lies.
Once the level is determined, the appropriate symbol is chosen based on
its phase, similar to PSK demodulation.
Demodulation of APSK consumes slightly more clock cycles than the PSK
and QAM demodulators.
%
%-------------------- FIGURE: APSK MODEM --------------------
\begin{figure}
\centering
\mbox{
  \subfigure[4-APSK (1,3)]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_apsk4}
      \label{fig:modem:apsk:4}
    } \quad
  \subfigure[8-PSK (1,7)]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_apsk8}
      \label{fig:modem:apsk:8}
    } \quad
}
\mbox{
  \subfigure[16-APSK (4,12)]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_apsk16}
      \label{fig:modem:apsk:16}
    } \quad
  \subfigure[32-APSK (4,12,16)]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_apsk32}
      \label{fig:modem:apsk:32}
    } \quad
}
\mbox{
  \subfigure[64-APSK (4,14,20,26)]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_apsk64}
      \label{fig:modem:apsk:64}
    } \quad
  \subfigure[128-APSK (8,18,24,36,42)]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_apsk128}
      \label{fig:modem:apsk:128}
    } \quad
}
% trim = left bottom right top
\caption{
    Amplitude/phase-shift keying (APSK) modem demonstrating
    constellation points lying on concentric circles.
    Not shown is 256-APSK~(6,18,32,36,46,54,64).
}
\label{fig:modem:apsk}
\end{figure}
%
Figure~\ref{fig:modem:apsk} depicts the available APSK signal
constellations for $M$ up to 128.
The constellation points and bit mappings have been optimized to
minimize the bit error rate in 10~dB SNR.


\subsubsection{{\tt LIQUID\_MODEM\_ASK} (amplitude-shift keying)}
\label{module:modem:digital:ASK}
Amplitude-shift keying (ASK) is a simple form of amplitude modulation by
which the information is encoded entirely in the in-phase component of
the baseband signal.
The encoded symbol is simply
%
\begin{equation}
    s_k = \alpha \bigl( 2 k - M - 1 \bigr)
\end{equation}
%
where $\alpha$ is a scaling factor to ensure $E\{s_k^2\}=1$,
%
\begin{equation}
    \alpha = 
    \begin{cases}
    1               &   M=2     \\
    1/\sqrt{5}      &   M=4     \\
    1/\sqrt{21}     &   M=8     \\
    1/\sqrt{85}     &   M=16    \\
    1/\sqrt{341}    &   M=32    \\
    \sqrt{3}/M      &   M > 32
    \end{cases}
\end{equation}
%
%-------------------- FIGURE: ASK MODEM --------------------
\begin{figure}
\centering
\mbox{
  \subfigure[2-ASK]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_ask2}
      \label{fig:modem:ask:2}
    } \quad
  \subfigure[4-ASK]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_ask4}
      \label{fig:modem:ask:4}
    } \quad
}
\mbox{
  \subfigure[8-ASK]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_ask8}
      \label{fig:modem:ask:8}
    } \quad
  \subfigure[16-ASK]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_ask16}
      \label{fig:modem:ask:16}
    } \quad
}
% trim = left bottom right top
\caption{Pulse-amplitude modulation (ASK) modem}
\label{fig:modem:ask}
\end{figure}
%
Figure~\ref{fig:modem:ask} depicts the ASK constellation map for $M$ up
to 16.
Due to the poor error rate performance of ASK values of $M$ greater than
16 are not recommended.


\subsubsection{{\tt LIQUID\_MODEM\_QAM} (quadrature amplitude modulation)}
\label{module:modem:digital:QAM}
Also known as quadrature amplitude-shift keying, QAM modems encode data using
both the in-phase and quadrature components of a signal amplitude.
In fact, the symbol is split into independent in-phase and quadrature symbols
which are encoded separately as {\tt LIQUID\_MODEM\_ASK} symbols.
Gray encoding is applited to both the I and Q symbols separately to help
ensure minimal bit changes between adjacent samples across both in-phase and
quadrature-phase dimensions.
This is made evident in Figure~\ref{fig:modem:qam:64} where one can see that
the first three bits of the symbol encode the in-phase component of the
sample, and the last thre bits encode the quadrature component of the sample.
%
We may formally describe the encoded sample is
%
\begin{equation}
    s_k = \alpha \Bigl\{ ( 2 k_i - M_i - 1 ) + j(2 k_q - M_q - 1) \Bigr\}
\end{equation}
%
where
$k_i$ is the in-phase symbol,
$k_q$ is the quadrature symbol,
$M_i = 2^{m_i}$ and $M_q = 2^{m_q}$, are the number of respective in-phase and
quadrature symbols,
$m_i=\lceil \log_2(M) \rceil$ and $m_q=\lfloor \log_2(M) \rfloor$ are the
number of respective in-phase and quadrature bits, and
$\alpha$ is a scaling factor to ensure $E\{s_k^2\}=1$,
%
\begin{equation}
    \alpha = 
    \begin{cases}
    1/\sqrt{2}      &   M=4     \\
    1/\sqrt{6}      &   M=8     \\
    1/\sqrt{10}     &   M=16    \\
    1/\sqrt{26}     &   M=32    \\
    1/\sqrt{42}     &   M=64    \\
    1/\sqrt{106}    &   M=128   \\
    1/\sqrt{170}    &   M=256   \\
    1/\sqrt{426}    &   M=512   \\
    1/\sqrt{682}    &   M=1024  \\
    1/\sqrt{1706}   &   M=2048  \\
    1/\sqrt{2730}   &   M=4096  \\
    \sqrt{2/M}      &   \text{else}
    \end{cases}
\end{equation}
%
%-------------------- FIGURE: QAM MODEM --------------------
\begin{figure}
\centering
\mbox{
  \subfigure[8-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_qam8}
      \label{fig:modem:qam:8}
    } \quad
  \subfigure[16-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_qam16}
      \label{fig:modem:qam:16}
    } \quad
}
\mbox{
  \subfigure[32-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_qam32}
      \label{fig:modem:qam:32}
    } \quad
  \subfigure[64-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_qam64}
      \label{fig:modem:qam:64}
    } \quad
}
\mbox{
  \subfigure[128-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_qam128}
      \label{fig:modem:qam:128}
    } \quad
  \subfigure[256-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_qam256}
      \label{fig:modem:qam:256}
    } \quad
}
% trim = left bottom right top
\caption{Rectangular quaternary-amplitude modulation (QAM) modem}
\label{fig:modem:qam}
\end{figure}
%
Figure~\ref{fig:modem:qam} depicts the arbitrary rectangular QAM modem
constellation maps for $M$ up to 256.
Notice that all the symbol points are gray encoded to minimize bit
errors between adjacent symbols.


\subsubsection{{\tt LIQUID\_MODEM\_ARB} (arbitrary modem)}
\label{module:modem:digital:ARB}
\liquid\ also allows the user to create their own modulation schemes by
designating the number of bits per symbol, and the full signal constellation.
Several pre-loaded arbitrary signal constellations are available.
%
%-------------------- FIGURE: OPTIMAL QAM --------------------
\begin{figure}
\centering
\mbox{
  \subfigure[optimal 16-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_arb16opt}
      \label{fig:modem:optqam:16opt}
    } \quad
  \subfigure[optimal 32-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_arb32opt}
      \label{fig:modem:optqam:32opt}
    } \quad
}
\mbox{
  \subfigure[optimal 64-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_arb64opt}
      \label{fig:modem:optqam:64opt}
    } \quad
  \subfigure[optimal 128-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_arb128opt}
      \label{fig:modem:optqam:128opt}
    } \quad
}
  \subfigure[optimal 256-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_arb256opt}
      \label{fig:modem:optqam:256opt}
    } \quad
% trim = left bottom right top
\caption{Optimal $M$-QAM constellation maps.}
\label{fig:modem:optqam}
\end{figure}
%
Figure~\ref{fig:modem:optqam} shows the constellation maps for the
optimal QAM schemes.
Notice that the constellations approximate a circle with each point
falling on the lattice of equalateral triangles.
Furthermore, adjacent constellation points differ by typically only a
single bit to reduce the resulting bit error rate at the output of the
demodulator.
These constellation marginally out-perform regular square QAM
(see Table~\ref{tab:modem:performance}) at the expense of a significaly
increased computational complexity.

%
%-------------------- FIGURE: ARB MODEM --------------------
\begin{figure}
\centering
\mbox{
  \subfigure[``square'' 32-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_sqam32}
      \label{fig:modem:arb:sqam32}
    } \quad
  \subfigure[``square'' 128-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_sqam128}
      \label{fig:modem:arb:sqam128}
    } \quad
}
\mbox{
  \subfigure[V.29]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_V29}
      \label{fig:modem:arb:V29}
    } \quad
  \subfigure[64-VT]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_arb64vt}
      \label{fig:modem:arb:64vt}
    } \quad
}
% trim = left bottom right top
\caption{Arbitrary constellation (ARB) modem}
\label{fig:modem:arb}
\end{figure}
%
Figure~\ref{fig:modem:arb} depicts several available arbitrary
constellation maps;
however the user can create any arbitrary constellation map so long as
no two points overlap
(see {\tt modem\_arb\_init()} and {\tt modem\_arb\_init\_file()} in
Section~\ref{module:modem:digital:interface}).

\subsubsection{Performance}
\label{module:modem:digital:performance}

% ------------ TABLE: LINEAR MODULATION SCHEMES ------------
\begin{table*}
\caption{Performance of linear modulation schemes, $\hat{P}_b=10^{-5}$}
\label{tab:modem:performance}
\centering
{\footnotesize
\begin{tabular*}{0.65\textwidth}{l@{\extracolsep{\fill}}lr}
\toprule
{\it schemes} &
{\it $E_s/N_0$} &
{\it $E_b/N_0$}\\\otoprule
%
\multicolumn{3}{c}{$M=2$}\\
\midrule
BPSK, 2-ASK         &  9.59 &  9.59 \\
DBPSK               & 10.46 & 10.46 \\
OOK                 & 12.61 & 12.61 \\
%
\midrule
\multicolumn{3}{c}{$M=4$} \\
\midrule
QPSK, 4-QAM         & 12.59 &  9.59 \\
4-APSK              & 14.76 & 11.75 \\
DQPSK               & 14.93 & 11.92 \\
4-ASK               & 16.59 & 13.58 \\
%
\midrule
\multicolumn{3}{c}{$M=8$} \\\midrule
8-APSK              & 16.12 & 11.35 \\
8-QAM               & 17.28 & 12.51 \\
8-PSK               & 17.84 & 13.07 \\
8-DPSK              & 20.62 & 15.85 \\
8-ASK               & 22.61 & 17.84 \\
%
\midrule
\multicolumn{3}{c}{$M=16$} \\\midrule
ARB-16-OPT          & 19.15 & 13.13 \\
16-QAM              & 19.57 & 13.55 \\
16-APSK             & 19.92 & 13.90 \\
V.29                & 20.48 & 14.45 \\
16-PSK              & 23.43 & 17.41 \\
16-DPSK             & 26.43 & 20.41 \\
16-ASK              & 28.54 & 22.52 \\
%
\midrule
\multicolumn{3}{c}{$M=32$} \\\midrule
ARB-32-OPT          & 22.11 & 15.12 \\
32-SQAM             & 22.56 & 15.57 \\
32-APSK             & 23.43 & 16.44 \\
32-QAM              & 23.59 & 16.60 \\
32-PSK              & 29.38 & 22.38 \\
32-DPSK             & 32.38 & 25.39 \\
%
\midrule
\multicolumn{3}{c}{$M=64$} \\\midrule
ARB-64-OPT          & 25.22 & 17.44 \\
64-QAM              & 25.50 & 17.71 \\
64-APSK             & 27.06 & 19.28 \\
ARB-64-VT           & 31.67 & 23.89 \\
64-PSK              & 35.32 & 27.38 \\
64-DPSK             & 38.28 & 30.50 \\
%
\midrule
\multicolumn{3}{c}{$M=128$} \\\midrule
ARB-128-OPT         & 28.19 & 19.74 \\
128-SQAM            & 28.42 & 19.97 \\
128-QAM             & 29.60 & 21.15 \\
128-APSK            & 30.55 & 22.10 \\
%
\midrule
\multicolumn{3}{c}{$M=256$} \\\midrule
ARB-256-OPT         & 31.09 & 22.06 \\
256-QAM             & 31.56 & 22.53 \\
256-APSK            & 33.10 & 24.06 \\\bottomrule
%
\end{tabular*}
}
\end{table*}%
% ------------------------


\subsubsection{Soft Demodulation}
\label{module:modem:digital:soft}
Unlike hard demodulation which seeks the most likely transmitted
{\em symbol} for a given received sample,
the goal of soft demodulation is to derive a probability metric for each
{\em bit} for the received sample.
When using the output of the demodulator in conjuction with forward
error-correction coding, the soft bit information can improve the error
detection and correction capabilities of most decoders,
usually by about 1.5~dB.
This soft bit information provides a clue to the decoder as to the
confidence that each bit was received correctly.
For turbo-product codes \cite{Berrou:1993} and
low-density parity check (LDPC) codes \cite{Gallager:1962},
this soft bit information is nearly a requirement.

% ...
Before we continue, let us define some nomenclature:
%
\begin{itemize}
\item $M=2^m$ are the number of points in the constellation
      (constellation size).
\item $m=\log_2(M)$ are the number of bits per symbol in the
      constellation (modulation depth).
\item $s_k$ is the symbol at index $k$ on the complex plane;
      $k \in \{0,1,2,\ldots,M-1\}$.
\item $\{b_0,b_1,\ldots,b_{m-1}\}$ is the encoded bit string of $s_k$
      and is simply the value of $k$ in binary-coded decimal.
\item $b_j$ is the bit at index $j$;
      $b_j \in \{0,1\}$ and $j \in \{0,1,\ldots,m-1\}$.
\item $\mathcal{S}_M = \{s_0,s_1,\ldots,s_{M-1}\}$ is the set of all
      symbols in the constellation where
      $1/M \sum_k \|s_k\|_2^2 = 1$.
\item $\mathcal{S}_{b_j=t}$ is the subset of $\mathcal{S}_M$
      where the bit at index $j$ is equal to $t \in \{0,1\}$.
\end{itemize}
%
For example, let the modulation scheme be
the generic 4-PSK with the constellation map defined in Figure~\ref{fig:modem:psk:4}
which has $m=2$, $M=4$, and
$\mathcal{S}_M = \{s_0=1, s_1=j, s_2=-j, s_3=-1\}$.
Subsets:
\begin{itemize}
\item $\mathcal{S}_{b_0=0} = \{s_0= 1, s_2=-j\}$ (right-most bit is {\tt 0})
\item $\mathcal{S}_{b_0=1} = \{s_1= j, s_3=-1\}$ (right-most bit is {\tt 1})
\item $\mathcal{S}_{b_1=0} = \{s_0= 1, s_1= j\}$ (left-most bit is {\tt 0})
\item $\mathcal{S}_{b_1=1} = \{s_2=-j, s_3=-1\}$ (left-most bit is {\tt 1})
\end{itemize}
%
A few key points:
\begin{itemize}
\item $\mathcal{S}_{b_j=0} \cap \mathcal{S}_{b_j=1} = \emptyset,     \, \forall_j$.
\item $\mathcal{S}_{b_j=0} \cup \mathcal{S}_{b_j=1} = \mathcal{S}_M, \, \forall_j$.
\end{itemize}
%

%
Let us represent the received signal at a sampling instant $n$ as
%
\begin{equation}
\label{eqn:modem:digital:soft:received_signal}
    r(n) = s(n) + w(n)
\end{equation}
%
where $s$ is the transmitted symbol
and $w$ is a zero-mean complex Gauss random variable with
a variance $\sigma_n^2 = E\{n n^*\}$.
Let the transmitted symbols be {\em i.i.d.} and drawn from a $M$-point
constellation, each with $m$ bits of information
such that the symbols belong to a set of constellation points
$s_k \in \mathcal{S}_M$ and $E\{s_k s_k^*\}=1$.
%
Assuming perfect channel knowledge, timing, and carrier offset recovery,
the log-likelihood ratio (LLR) of each bit $b_j$ is shown to be
\cite[Eq.~(8)]{LeGoff:1994}
the ratio of the two conditional {\em a posteriori} probabilities of
each bit having been transmitted, viz.
%
\begin{equation}
\label{eqn:modem:digital:soft:LLR_true}
    \Lambda(b_j) =
        \ln \frac{
            P\left(b_j=1 | {observation} \right)
        }{
            P\left(b_j=0 | {observation} \right)
        }
\end{equation}
%
Assuming that the channel is memoryless the ``observation'' is simply
the received sample $r$ in
(\ref{eqn:modem:digital:soft:received_signal})
and does not depend on previous symbols; therefore
$P\left(b_j=t|{observation}\right) = P\left(b_j=t|r(n)\right)$
and $t \in \{0,1\}$.
Furthermore, by assuming that the transmitted symbols are equally
probable and that the noise follows a Gauss distribution
\cite{Qiang:2003}
the LLR reduces to
%
\begin{equation}
\label{eqn:modem:digital:soft:LLR}
    \Lambda(b_j) =
        \ln \Biggl(
            \sum_{s^+\in \mathcal{S}_{b_j=1}} { \exp\Bigl\{\|r-s^+\|_2^2 / 2 \sigma_n^2\Bigr\} }
        \Biggr)
       -\ln \Biggl(
            \sum_{s^-\in \mathcal{S}_{b_j=0}} { \exp\Bigl\{\|r-s^-\|_2^2 / 2 \sigma_n^2\Bigr\} }
        \Biggr)
\end{equation}
%
As shown in \cite{Qiang:2003} a sub-optimal simplified LLR expression
can be obtained by replacing the summations in
(\ref{eqn:modem:digital:soft:LLR}) with the single largest component of
each: $\ln \sum_j {e^{z_j}} \approx \max_j \ln (e^{z_j}) = \max_j z_j$.
This approximation provides a tight bound as long as the sum is
dominated by its largest component.
The approximate LLR becomes
%
\begin{equation}
\label{eqn:modem:digital:soft:LLR_approx}
    \tilde{\Lambda}(b_j) =
        \frac{1}{2\sigma_n^2}
        \Bigl\{
            \underset{s^+\in \mathcal{S}_{b_j=0}}{\min} \|r-s^+\|_2^2 -
            \underset{s^-\in \mathcal{S}_{b_j=1}}{\min} \|r-s^-\|_2^2
        \Bigr\}
\end{equation}
%
Conveniently, both the exponential and logarithm operations disappear;
furthermore, the noise variance becomes a scaling factor and is only
used to influence the reliability of the obtained LLR.

%
%-------------------- FIGURE: MODEM DEMOD SOFT--------------------
\begin{figure}
\centering
\mbox{
  \subfigure[$\tilde{\Lambda}(b_0) = -10.55$]
    {
      \includegraphics[trim = 18mm 0mm 15mm 0mm, clip, width=8cm]{figures.gen/modem_demodsoft_b0}
      \label{fig:modem:demodsoft:b0}
    } \quad
  \subfigure[$\tilde{\Lambda}(b_1) = -0.28$]
    {
      \includegraphics[trim = 18mm 0mm 15mm 0mm, clip, width=8cm]{figures.gen/modem_demodsoft_b1}
      \label{fig:modem:demodsoft:b1}
    } \quad
}
\mbox{
  \subfigure[$\tilde{\Lambda}(b_2) = -7.43$]
    {
      \includegraphics[trim = 18mm 0mm 15mm 0mm, clip, width=8cm]{figures.gen/modem_demodsoft_b2}
      \label{fig:modem:demodsoft:b2}
    } \quad
  \subfigure[$\tilde{\Lambda}(b_3) = 2.57$]
    {
      \includegraphics[trim = 18mm 0mm 15mm 0mm, clip, width=8cm]{figures.gen/modem_demodsoft_b3}
      \label{fig:modem:demodsoft:b3}
    } \quad
}
% trim = left bottom right top
\caption{
    Soft demodulation example of a 16-QAM sample.
    Each plot depicts the soft demodulation of each of the 4 bits where
    the $\times$ denotes the received sample and the lines connect it to
    the nearest symbol with each of a {\tt 0} and {\tt 1} bit. %REWORD
    The noise standard deviation is $\sigma_n=0.2$.
}
\label{fig:modem:demodsoft}
\end{figure}
%
Figure~\ref{fig:modem:demodsoft} depicts the soft bit demodulation
algorithm for a received 16-QAM signal point, corrupted by noise.
The received sample is $r = -0.65 - j0.47$ which results in a hard
demodulation of {\tt 0001}.
The subfigures depict each of the four bits in the symbol 
$\{b_0,b_1,b_2,b_3\}$
for which the
soft bit output is given, and show the nearest symbol for which a
{\tt 0} and a {\tt 1} at that particular bit index occurs.
For example, Figure~\ref{fig:modem:demodsoft:b2} shows that
the nearest symbol containing a {\tt 0} at bit index 2
is $s_1=${\tt 0001} (the hard decision demodulation)
at $(-3 - j)/\sqrt{10}$
while
the nearest symbol containing a {\tt 1} at bit index 2
is $s_3=${\tt 0011}
at $(-3 + j)/\sqrt{10}$.
Plugging $s^-=s_1$ and $s^+=s_3$ into
(\ref{eqn:modem:digital:soft:LLR_approx})
and evaluating for $\sigma_n=0.2$ gives
$\tilde{\Lambda}(b_2) = -7.43$.
Because this number is largely negative, it is very likely that the
transmitted bit $b_2$ was {\tt 0}.
This can be verified by Figure~\ref{fig:modem:demodsoft:b2} which shows
that the distance from $r$ to $s^-$ is much shorter than that of $s^+$.

Conversely, Figure~\ref{fig:modem:demodsoft:b1} shows that $b_1$ cannot
be demodulated with such certainty;
the distances from $r$ to each of $s^+$ and $s^-$ are about the same.
This is reflected in the relatively small LLR value of
$\tilde{\Lambda}(b_1)=-0.28$ which suggests a high uncertainty in the
demodulation of $b_1$.
%

% 
% specific implementation
%
One major drawback of computing
(\ref{eqn:modem:digital:soft:LLR_approx}) is that finding the maximum
requires searching over all constellation points to find the one which
minimizes $\|r-s_k\|$
(where $s_k \in \mathcal{S}_{b_j=t}$) is particularly time-consuming.
% TODO : explain in more detail
To circumvent this, \liquid\ only searches over a subset
$\mathcal{S}_k \subset \mathcal{S}_M$ nearest to the
hard-demodulated symbol
% $\mathcal{S}_k$ is the subset of $\mathcal{S}_M$
%  nearest to the symbol $s_k$.
($\mathcal{S}_k$ will typically only have about four values).
This can be done quickly because the hard-demodulated symbol can be
found systematically for most modulation schemes
(e.g. for {\tt LIQUID\_MODEM\_QAM} only $\ord(\log_2 M)$ comparisons are
needed to make a hard decision).
%
If no symbols are found within $\mathcal{S}_k$ for a given bit value
such that $\mathcal{S}_k \cap \mathcal{S}_{b_j=t} = \emptyset$
then the magnitude of $\Lambda(b_j)$ is sufficiently large
and contains little soft bit information;
that is
$\tilde{\Lambda}(b_j) \gg 0$ when $\mathcal{S}_k \cap \mathcal{S}_{b_j=0} = \emptyset$
and
$\tilde{\Lambda}(b_j) \ll 0$ when $\mathcal{S}_k \cap \mathcal{S}_{b_j=1} = \emptyset$.
%
It is guaranteed that
$   \left( \mathcal{S}_k \cap \mathcal{S}_{b_j=0}\right)
        \cup
    \left( \mathcal{S}_k \cap \mathcal{S}_{b_j=1}\right)
    \neq \emptyset $
because $s_k$ must be in either $\mathcal{S}_{b_j=0}$ or
$\mathcal{S}_{b_j=1}$.
%

% 
% soft bit representation
%
Soft bit information is stored in \liquid\ as type {\tt unsigned char}
with a value of {\tt 255} representing a {\em very likely {\tt 1}},
and a value of {\tt 0} representing a {\em very likely {\tt 0}}.
The {\em erasure} condition is {\tt 127}.
%
\begin{Verbatim}[fontsize=\small]
soft bit value:  [0 1 2 3      ...   64 65   ...  127  ...  192 193   ...  253 254 255]
interpretation:  very likely '0'   likely '0'   erasure   likely '1'    very likely '1'
\end{Verbatim}

\subsubsection{Error Vector Magnitude}
\label{module:modem:digital:evm}
The error vector magnitude (EVM) of a demodulated symbol is simply the
average maginitude of the error vector between the received sample
before demodulation and the expected transmitted symbol, viz.
%
\begin{equation}
\label{eqn:modem:evm}
    \textup{EVM} = E\left\{ \left| s - \hat{s} \right|^2 \right\}
\end{equation}
%
EVM is returned by many of the framing objects
(see Section~\ref{module:framing})
because it gives a good indication of signal distortion as a result of
noise, inter-symbol interference, etc.
If the only channel impairment is noise (e.g. perfect symbol timing)
then the SNR can be approximated as
\[
    \hat{\gamma} \approx 1 / \textup{EVM}
\]


%
% CONTINUOUS PHASE MODEMS
%

\subsection{Continuous phase digital modulation schemes}
\label{module:modem:cpm}

\subsubsection{{\tt gmskmod} (Gauss minimum-shift keying)}
\label{module:modem:cpm:gmskmod}

Two objects: {\tt gmksmod} (GMSK modulator), {\tt gmskdem} (GMSK
demodulator).
%
\input{listings/gmskmodem.example.c.tex}
%
<commit_msg>doc|modem: back-referencing fec and packetizer soft decoding<commit_after>% 
% MODULE : modem
%

\newpage
\section{modem}
\label{module:modem}
The modem module implements a set of (mod)ulation/(dem)odulation schemes
for encoding information into signals.
For the analog modems, samples are encoded according to frequency or
analog modulation.
For the digital modems, data bits are encoded into symbols representing
carrier frequency, phase, amplitude, etc.
This section gives a brief overview of modulation schemes available in
\liquid, and provides a brief description of the interfaces.


%
% ANALOG MODEMS
%

\subsection{Analog modulation schemes}
\label{module:modem:analog}
This section describes the two basic analog modulation schemes available
in \liquid:
frequency modulation and amplitude modulation
implemented with the respective {\tt freqmodem} and {\tt ampmodem}
objects.

\subsubsection{{\tt freqmodem} (analog FM)}
\label{module:modem:analog:freqmodem}
The {\tt freqmodem} object implements an analog frequency modulation
(FM) modulator and demodulator.
Given an input message signal $-1 \le s(t) \le 1$, the transmitted
signal is
%
\begin{equation}
\label{eqn:modem:freqmodem_tx}
    s(t) =  \exp\left\{
                j 2 \pi k f_c
                \int_{0}^{t}{
                    s(\tau)d\tau
                }
            \right\}
\end{equation}
%
where $f_c$ is the carrier frequency, and $k$ is the modulation index.
The modulation index governs the relative bandwidth of the signal.
Two options for demodulation are possible:
observing the instantaneous frequency on the output of a phase-locked
loop,
or computing the instantaneous frequency using the delay-conjugate
method.
%Its digital equivalent is
%\[
%    s(nT_s) =   \exp\left\{
%                    j 2 \pi k f_c
%                    \sum_{k=0}^{n}{
%                        m(kT_s)
%                    }
%                \right\}
%\]
%
An example of the {\tt freqmodem} interface is listed below.
%
\input{listings/freqmodem.example.c.tex}
%
A more detailed example can be found in
{\tt examples/freqmodem\_example.c}
located under the main \liquid\ project source directory.
Listed below is the full interface to the {\tt freqmodem} object for
analog frequency modulation/demodulation.
%
\begin{description}
\item[{\tt freqmodem\_create(k,fc,type)}]
    creates and returns an {\tt freqmodem} object with a modulation
    index $k$, a carrier frequency $-0.5 < f_c < 0.5$, and a
    demodulation type defined by {\tt type}.
    The demodulation type can either be
    {\tt LIQUID\_MODEM\_FM\_PLL} which uses a phased-locked loop or
    {\tt LIQUID\_MODEM\_FM\_DELAY\_CONJ} which uses the delay conjugate
    method.
\item[{\tt freqmodem\_destroy(q)}]
    destroys an {\tt freqmodem} object, freeing all internally-allocated
    memory.
\item[{\tt freqmodem\_reset(q)}]
    resets the state of the {\tt freqmodem} object.
\item[{\tt freqmodem\_print(q)}]
    prints the internal state of the {\tt freqmodem} object.
\item[{\tt freqmodem\_modulate(q,x,*y)}]
    modulates the input sample $x$ storing the output to $y$.
\item[{\tt freqmodem\_demodulate(q,y,*x)}]
    demodulates the input sample $y$ storing the output to $x$.
\end{description}

% TODO : clean up this section!
\subsubsection{{\tt ampmodem} (analog AM)}
\label{module:modem:analog:ampmodem}
The {\tt ampmodem} object implements an analog amplitude modulation (AM)
modulator/demodulator pair.
Two basic transmission schemes are available:
single side-band (SSB), and
double side-band (DSB).
%
For an input message signal $-1 \le s(t) \le 1$, the double side-band
transmitted signal is
%
\begin{equation}
\label{eqn:modem:ampmodem:dsb_tx}
    x_{DSB}(t) = 
    \begin{cases}
        s(t)e^{j 2 \pi f_c t}   &   \text{suppressed carrier} \\
        \frac{1}{2}\bigl(1+ks(t)\bigr)e^{j 2 \pi f_c t}   &   \text{unsuppressed carrier}
    \end{cases}
\end{equation}
%
where $f_c$ is the carrier frequency, and $k$ is the modulation index.
%
For single side-band, only the upper (USB) or lower half (LSB)
of the spectrum is transmitted.
The opposing half of the spectrum is rejected using a Hilbert transform
(see Section~\ref{module:filter:firhilb}).
Let $\dot{s}(t)$ represent the Hilbert transform of the message signal
$s(t)$ such that its Fourier transform is non-zero only for positive
frequency components, viz
%
\begin{equation}
\label{eqn:modem:ampmodem:ssb_hilbert}
    \dot{S}(\omega) = \F\left\{ \dot{s}(t) \right\} =
    \begin{cases}
        S(\omega) = \F\left\{ s(t) \right\} & \omega > 0 \\
        0                                   & \omega \leq 0
    \end{cases}
\end{equation}
%
Consequently the transmitted upper side-band signal is
%
\begin{equation}
\label{eqn:modem:ampmodem:ssb_tx}
    x_{USB}(t) = 
    \begin{cases}
        \dot{s}(t)e^{j 2 \pi f_c t}   &   \text{suppressed carrier} \\
        \frac{1}{2}\bigl(1+k\dot{s}(t)\bigr)e^{j 2 \pi f_c t}   &   \text{unsuppressed carrier}
    \end{cases}
\end{equation}
%
For lower single side-band, $\dot{s}(t)$ is simply conjugated.
%
For suppressed carrier modulation the receiver uses a phase-locked loop for
carrier frequency and phase tracking.
When the carrier is not suppressed the receiver demodulates using a
simple peak detector and IIR bias removal filter.
%
An example of the {\tt freqmodem} interface is listed below.
%
\input{listings/ampmodem.example.c.tex}
%
A more detailed example can be found in
{\tt examples/ampmodem\_example.c}
located under the main \liquid\ project source directory.
Listed below is the full interface to the {\tt ampmodem} object for
analog frequency modulation/demodulation.
%
\begin{description}
\item[{\tt ampmodem\_create(k,type,suppressed\_carrier)}]
    creates and returns an {\tt ampmodem} object with a modulation
    index $k$,
    a modulation scheme defined by {\tt type},
    and a binary flag specifying whether the carrier should be
    suppressed.
    The modulation type can either be
    {\tt LIQUID\_MODEM\_AM\_DSB} (double side-band),
    {\tt LIQUID\_MODEM\_FM\_USB} (single upper side-band), or
    {\tt LIQUID\_MODEM\_FM\_LSB} (single lower side-band).
    method.
\item[{\tt ampmodem\_destroy(q)}]
    destroys an {\tt ampmodem} object, freeing all internally-allocated
    memory.
\item[{\tt ampmodem\_reset(q)}]
    resets the state of the {\tt ampmodem} object.
\item[{\tt ampmodem\_print(q)}]
    prints the internal state of the {\tt ampmodem} object.
\item[{\tt ampmodem\_modulate(q,x,*y)}]
    modulates the input sample $x$ storing the output to $y$.
\item[{\tt ampmodem\_demodulate(q,y,*x)}]
    demodulates the input sample $y$ storing the output to $x$.
\end{description}


%\subsection{Continuous phase digital modulation schemes}
%fsk, msk, etc. [NOTE: not yet implemented]



%
% LINEAR DIGITAL MODEMS
%

\subsection{Linear digital modulation schemes}
\label{module:modem:digital}
The {\tt modem} object realizes the linear digital modulation library in which
the information from a symbol is encoded into the amplitude and phase of a
sample.
The modem structure implements a variety of common modulation schemes,
including (differential) phase-shift keying, and (quadrature) amplitude-shift
keying.
The input/output relationship for modulation/demodulation for the {\tt modem}
object is
strictly one-to-one and is independent of any pulse shaping, or interpolation.
%This differs from {\tt cpmodem} in which the pulse shaping filter is
%integrated into the modem itself.

In general, linear modems demodulate by finding the closest of $M$
symbols in the set $\mathcal{S}_M = \{s_0,s_1,\ldots,s_{M-1}\}$ 
to the received symbol $r$, viz
%
\begin{equation}
\label{eqn:modem:demod}
    \underset{s_k \in \mathcal{S}_M}{\arg\min}
    \bigl\{
        \| r - s_k \|
    \bigr\}
\end{equation}
%
For arbitrary modulation schemes a linear search over all symbols in
$\mathcal{S}_M$ is required which has a complexity of $\ord(M^2)$, however one may
take advantage of symmetries in certain constellations to reduce this.
%For example, $M$-ary PSK distributes its symbols evenly throughout the phase
%of the transmitted signal...

% ------------ TABLE: LINEAR MODULATION SCHEMES ------------
\begin{table*}
\caption{Linear Modulation Schemes Available in \liquid}
\label{tab:modem:schemes}
\centering
{\small
\begin{tabular*}{0.95\textwidth}{l@{\extracolsep{\fill}}ll}
\toprule
{\it scheme} &
{\it depth range (bits/symbol)} &
{\it description}\\\otoprule
%
{\tt LIQUID\_MODEM\_UNKNOWN}    & -     & unknown/unsupported scheme\\
{\tt LIQUID\_MODEM\_PSK}        & 1|8   & phase-shift keying\\
{\tt LIQUID\_MODEM\_DPSK}       & 1|8   & differential phase-shift keying\\
{\tt LIQUID\_MODEM\_ASK}        & 1|8   & amplitude-shift keying\\
{\tt LIQUID\_MODEM\_QAM}        & 2|8   & quadrature amplitude-shift keying\\
{\tt LIQUID\_MODEM\_APSK}       & 2|8   & amplitude/phase-shift keying\\
{\tt LIQUID\_MODEM\_ARB}        & 1|8   & arbitrary signal constellation\\\midrule
%
{\tt LIQUID\_MODEM\_BPSK}       & 1     & binary phase-shift keying\\
{\tt LIQUID\_MODEM\_QPSK}       & 2     & quaternary phase-shift keying\\
{\tt LIQUID\_MODEM\_OOK}        & 1     & on/off keying\\
{\tt LIQUID\_MODEM\_SQAM32}     & 5     & ``square'' 32-QAM\\
{\tt LIQUID\_MODEM\_SQAM128}    & 7     & ``square'' 128-QAM\\
{\tt LIQUID\_MODEM\_V29}        & 4     & V.29 star modem\\
{\tt LIQUID\_MODEM\_ARB16OPT}   & 4     & optimal 16-QAM\\
{\tt LIQUID\_MODEM\_ARB32OPT}   & 5     & optimal 32-QAM\\
{\tt LIQUID\_MODEM\_ARB64OPT}   & 6     & optimal 64-QAM\\
{\tt LIQUID\_MODEM\_ARB128OPT}  & 7     & optimal 128-QAM\\
{\tt LIQUID\_MODEM\_ARB256OPT}  & 8     & optimal 256-QAM\\
{\tt LIQUID\_MODEM\_ARB64VT}    & 6     & Virginia Tech logo\\\bottomrule
% 
\end{tabular*}
}
\end{table*}%
% ------------------------


\subsubsection{Interface}
\label{module:modem:digital:interface}
\begin{description}
\item[{\tt modem\_create(scheme,bps)}]
    creates a linear modulator/demodulator {\tt modem} object with one
    of the schemes defined in Table~\ref{tab:modem:schemes}
    with {\tt bps} bits per symbol.
\item[{\tt modem\_destroy(q)}]
    destroys a {\tt modem} object, freeing all internally-allocated
    memory.
\item[{\tt modem\_print(q)}]
    prints the internal state of the object.
\item[{\tt modem\_reset(q)}]
    resets the internal state of the object.
    This method is really only relevant to {\tt LIQUID\_MODEM\_DPSK}
    (differential phase-shift keying) which retains the phase of the
    previous symbol in memory.
    All other modulation schemes are memoryless.
\item[{\tt modem\_arb\_init(q,*map,n)}]
    initializes an arbitrary modem ({\tt LIQUID\_MODEM\_ARB}) with the $n$-point
    constellation map.
    The resulting constellation is normalized such that it is centered
    at zero and has unity energy.
\item[{\tt modem\_arb\_init\_file(q,*filename)}]
    initializes an arbitrary modem ({\tt LIQUID\_MODEM\_ARB}) with a constellation
    map defined in an external file.
    The file includes one line per symbol with the in-phase and
    quadrature components separated by white space, e.g.
    %
    \begin{Verbatim}[fontsize=\small]
       1.46968   0.13529
       1.69067   0.71802
      -0.85603   0.43542
      -0.56563   1.50369
       0.45232   0.42128
          ...
    \end{Verbatim}
    %
    The resulting constellation is normalized such that it is centered
    at zero and has unity energy.
\item[{\tt modem\_modulate(q,symbol,*x)}]
    modulates the integer symbol storing the result in the output value
    of $x$.
    The input symbol value must be less than the constellation size $M$.
\item[{\tt modem\_demodulate(q,x,*symbol)}]
    finds the closest integer symbol which matches the input sample $x$.
    The exact method by which \liquid\ performs this computation is
    dependent upon the modulation scheme.
    For example, while
    {\tt LIQUID\_MODEM\_QAM} ($M=4$), and
    {\tt LIQUID\_MODEM\_PSK} ($M=4$)
    are effectively equivalent (four points on the unit circle)
    they are demodulated differently.
\item[{\tt modem\_get\_demodulator\_phase\_error(q)}]
    returns an angle proportional to the phase error after demodulation.
    This value can be used in a phase-locked loop
    (see Section~\ref{module:nco:pll})
    to correct for carrier phase recovery.
\item[{\tt modem\_get\_demodulator\_evm(q)}]
    returns a value equal to the error vector magnitude after demodulation.
    The error vector is the difference between the received symbol and the
    estimated transmitted symbol, $e = r - \hat{s}$.
    The magnitude of the error vector is an indication to the
    signal-to-noise/distortion ratio at receiver.
\end{description}

While the same modem structure may be used for both modulation and
demodulation for most schemes, it is important to use separate objects
for differential-mode modems (e.g. {\tt LIQUID\_MODEM\_DPSK}) as the internal state
will change after each symbol.
It is usually good practice to keep separate instances of modulators and
demodulators.
This holds true for most any encoder/decoder pair in \liquid.
%
An example of the {\tt qmodem} interface is listed below.
%
\input{listings/modem.example.c.tex}
%

\subsubsection{Gray coding}
\label{module:modem:digital:gray_coding}
In order to reduce the number of bit errors in a digital modem,
all symbols are automatically Gray encoded such that
adjacent symbols in a constellation differ by only one bit.
%
For example, the binary-coded decimal (BCD) value of 183 is {\tt 10110111}.
It has adjacent symbol 184 ({\tt 10111000}) which differs by 4 bits.
Assume the transmitter sends 183 without encoding.
If noise at the receiver were to cause it to demodulate the nearby
symbol 184, the result would be 4 bit errors.
%
Gray encoding is computed to the binary-coded decimal symbol
by applying an exclusive OR bitmask of itself shifted to the right by a
single bit.
%
\begin{Verbatim}[fontsize=\small]
            10110111    bcd_in (183)        10111000    bcd_in (184)
            .1011011    bcd_in >> 1         .1011100    bcd_in >> 1
    xor :   --------                        --------
            11101100    gray_out (236)      11100100    gray_out (228)
\end{Verbatim}
%
Notice that the two encoded symbols
236 ({\tt 11101100}) and
228 ({\tt 11100100}) differ by only one bit.
Now if noise caused the receiver were to demodulate a symbol error, it would
result in only a single bit error instead of 4 without Gray coding.

Reversing the process (decoding) is similar to encoding but slightly
more involved.
Gray decoding is computed on an encoded input symbol by adding to it
(modulo 2) as many shifted versions of itself as it has bits.
In our previous example the receiver needs to map the received encoded
symbol back to the original symbol before encoding:
%
\begin{Verbatim}[fontsize=\small]
            11101100    gray_in (236)       11100100    gray_in (228)
            .1110110    gray_in >> 1        .1110010    gray_in >> 1
            ..111011    gray_in >> 2        ..111001    gray_in >> 2
            ...11101    gray_in >> 3        ...11100    gray_in >> 3
            ....1110    gray_in >> 4        ....1110    gray_in >> 4
            .....111    gray_in >> 5        .....111    gray_in >> 5
            ......11    gray_in >> 6        ......11    gray_in >> 6
            .......1    gray_in >> 7        .......1    gray_in >> 7
    xor :   --------                        --------
            10110111    gray_out (183)      10111000    gray_out (184)
\end{Verbatim}
%
There are a few interesting characteristics of Gray encoding:
\begin{itemize}
\item the first bit never changes in encoding/decoding
\item there is a unique mapping between input and output symbols
\end{itemize}
It is also interesting to note that in linear modems (e.g. PSK), the
{\tt decoder} is actually applied to the symbol at the transmitter while the
{\tt encoder} is applied to the received symbol at the receiver.
%This is somewhat counterintuitive and is because...
In \liquid, Gray encoding and decoding are computed with the
{\tt gray\_encode()} {\tt gray\_decode()} methods, respectively.

\subsubsection{{\tt LIQUID\_MODEM\_PSK} (phase-shift keying)}
\label{module:modem:digital:PSK}
With phase-shift keying the information is stored in the absolute phase
of the modulated signal.
This means that each of $M=2^m$ symbols in the constellation are equally
spaced around the unit circle.
%
%-------------------- FIGURE: PSK MODEM --------------------
\begin{figure}
\centering
\mbox{
  \subfigure[2-PSK (generic BPSK)]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_psk2}
      \label{fig:modem:psk:2}
    } \quad
  \subfigure[4-PSK (generic QPSK)]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_psk4}
      \label{fig:modem:psk:4}
    } \quad
}
\mbox{
  \subfigure[8-PSK]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_psk8}
      \label{fig:modem:psk:8}
    } \quad
  \subfigure[16-PSK]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_psk16}
      \label{fig:modem:psk:16}
    } \quad
}
\mbox{
  \subfigure[32-PSK]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_psk32}
      \label{fig:modem:psk:32}
    } \quad
  \subfigure[64-PSK]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_psk64}
      \label{fig:modem:psk:64}
    } \quad
}
% trim = left bottom right top
\caption{
    Phase-shift keying (PSK) modem constellation map.
    Note that BPSK and QPSK are customized implementations of 2-PSK and
    4-PSK.
    While only PSK up to $M=64$ are shown, \liquid\ supports up to
    256-PSK.
}
\label{fig:modem:psk}
\end{figure}
%
Figure~\ref{fig:modem:psk} depicts the constellation of PSK up to $M=16$
with the bits gray encoded.
While \liquid\ supports up to $M=256$, values greater than $M=32$
are typically avoided due to error rates for practical signal-to-noise
ratios.
%
For an $M$-symbol constellation, the $k^{th}$ symbol is
%
\begin{equation}
    s_k = e^{j 2 \pi k/M}
\end{equation}
%
where $k \in \{0,1,\ldots,M-1\}$.
Specific schemes include BPSK ($M=2$),
%
\begin{equation}
    s_k = e^{j \pi k} =
    \begin{cases}
        +1 & k=0 \\
        -1 & k=1
    \end{cases}
\end{equation}
%
and QPSK ($M=4$)
%
\begin{equation}
    s_k = e^{j\left(\pi k/4 + \frac{\pi}{4}\right)}
\end{equation}
%
Demodulation is performed independent of the signal amplitude for
coherent PSK.


\subsubsection{{\tt LIQUID\_MODEM\_DPSK} (differential phase-shift keying)}
\label{module:modem:digital:DPSK}
Differential PSK (DPSK) encodes information in the phase change of the
carrier.
Like regular PSK
demodulation is performed independent of the signal amplitude;
however because the data are encoded using phase transitions rather than
absolute phase, the receiver does not have to know the absolute phase of
the transmitter.
This allows the receiver to demodulate incoherently, but at a quality
degradation of 3dB.
%
As such the $n^{th}$ transmitted symbol $k(n)$ depends on the previous
symbol, viz
%
\begin{equation}
    s_k(n) = \exp\left\{
                \frac{
                    j 2 \pi \Bigl(k(n) - k(n-1)\Bigr)
                } {
                    M
                }
            \right\}
\end{equation}

\subsubsection{{\tt LIQUID\_MODEM\_APSK} (amplitude/phase-shift keying}
\label{module:modem:digital:APSK}
Amplitude/phase-shift keying (APSK) is a specific form of quadrature
amplitude modulation where constellation points lie on concentric
circles.
The constellation points are further apart than those of PSK/DPSK,
resulting in an improved error performance.
Furthermore the phase recovery for APSK is improved over regular QAM as
the constellation points are less sensitive to phase noise.
This improvement comes at the cost of an increased computational
complexity at the receiver.
%
Demodulation follows as a two-step process: first, the amplitude of the
received signal is evaluated to determine in which level (``ring'') the
transmitted symbol lies.
Once the level is determined, the appropriate symbol is chosen based on
its phase, similar to PSK demodulation.
Demodulation of APSK consumes slightly more clock cycles than the PSK
and QAM demodulators.
%
%-------------------- FIGURE: APSK MODEM --------------------
\begin{figure}
\centering
\mbox{
  \subfigure[4-APSK (1,3)]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_apsk4}
      \label{fig:modem:apsk:4}
    } \quad
  \subfigure[8-PSK (1,7)]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_apsk8}
      \label{fig:modem:apsk:8}
    } \quad
}
\mbox{
  \subfigure[16-APSK (4,12)]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_apsk16}
      \label{fig:modem:apsk:16}
    } \quad
  \subfigure[32-APSK (4,12,16)]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_apsk32}
      \label{fig:modem:apsk:32}
    } \quad
}
\mbox{
  \subfigure[64-APSK (4,14,20,26)]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_apsk64}
      \label{fig:modem:apsk:64}
    } \quad
  \subfigure[128-APSK (8,18,24,36,42)]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_apsk128}
      \label{fig:modem:apsk:128}
    } \quad
}
% trim = left bottom right top
\caption{
    Amplitude/phase-shift keying (APSK) modem demonstrating
    constellation points lying on concentric circles.
    Not shown is 256-APSK~(6,18,32,36,46,54,64).
}
\label{fig:modem:apsk}
\end{figure}
%
Figure~\ref{fig:modem:apsk} depicts the available APSK signal
constellations for $M$ up to 128.
The constellation points and bit mappings have been optimized to
minimize the bit error rate in 10~dB SNR.


\subsubsection{{\tt LIQUID\_MODEM\_ASK} (amplitude-shift keying)}
\label{module:modem:digital:ASK}
Amplitude-shift keying (ASK) is a simple form of amplitude modulation by
which the information is encoded entirely in the in-phase component of
the baseband signal.
The encoded symbol is simply
%
\begin{equation}
    s_k = \alpha \bigl( 2 k - M - 1 \bigr)
\end{equation}
%
where $\alpha$ is a scaling factor to ensure $E\{s_k^2\}=1$,
%
\begin{equation}
    \alpha = 
    \begin{cases}
    1               &   M=2     \\
    1/\sqrt{5}      &   M=4     \\
    1/\sqrt{21}     &   M=8     \\
    1/\sqrt{85}     &   M=16    \\
    1/\sqrt{341}    &   M=32    \\
    \sqrt{3}/M      &   M > 32
    \end{cases}
\end{equation}
%
%-------------------- FIGURE: ASK MODEM --------------------
\begin{figure}
\centering
\mbox{
  \subfigure[2-ASK]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_ask2}
      \label{fig:modem:ask:2}
    } \quad
  \subfigure[4-ASK]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_ask4}
      \label{fig:modem:ask:4}
    } \quad
}
\mbox{
  \subfigure[8-ASK]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_ask8}
      \label{fig:modem:ask:8}
    } \quad
  \subfigure[16-ASK]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_ask16}
      \label{fig:modem:ask:16}
    } \quad
}
% trim = left bottom right top
\caption{Pulse-amplitude modulation (ASK) modem}
\label{fig:modem:ask}
\end{figure}
%
Figure~\ref{fig:modem:ask} depicts the ASK constellation map for $M$ up
to 16.
Due to the poor error rate performance of ASK values of $M$ greater than
16 are not recommended.


\subsubsection{{\tt LIQUID\_MODEM\_QAM} (quadrature amplitude modulation)}
\label{module:modem:digital:QAM}
Also known as quadrature amplitude-shift keying, QAM modems encode data using
both the in-phase and quadrature components of a signal amplitude.
In fact, the symbol is split into independent in-phase and quadrature symbols
which are encoded separately as {\tt LIQUID\_MODEM\_ASK} symbols.
Gray encoding is applited to both the I and Q symbols separately to help
ensure minimal bit changes between adjacent samples across both in-phase and
quadrature-phase dimensions.
This is made evident in Figure~\ref{fig:modem:qam:64} where one can see that
the first three bits of the symbol encode the in-phase component of the
sample, and the last thre bits encode the quadrature component of the sample.
%
We may formally describe the encoded sample is
%
\begin{equation}
    s_k = \alpha \Bigl\{ ( 2 k_i - M_i - 1 ) + j(2 k_q - M_q - 1) \Bigr\}
\end{equation}
%
where
$k_i$ is the in-phase symbol,
$k_q$ is the quadrature symbol,
$M_i = 2^{m_i}$ and $M_q = 2^{m_q}$, are the number of respective in-phase and
quadrature symbols,
$m_i=\lceil \log_2(M) \rceil$ and $m_q=\lfloor \log_2(M) \rfloor$ are the
number of respective in-phase and quadrature bits, and
$\alpha$ is a scaling factor to ensure $E\{s_k^2\}=1$,
%
\begin{equation}
    \alpha = 
    \begin{cases}
    1/\sqrt{2}      &   M=4     \\
    1/\sqrt{6}      &   M=8     \\
    1/\sqrt{10}     &   M=16    \\
    1/\sqrt{26}     &   M=32    \\
    1/\sqrt{42}     &   M=64    \\
    1/\sqrt{106}    &   M=128   \\
    1/\sqrt{170}    &   M=256   \\
    1/\sqrt{426}    &   M=512   \\
    1/\sqrt{682}    &   M=1024  \\
    1/\sqrt{1706}   &   M=2048  \\
    1/\sqrt{2730}   &   M=4096  \\
    \sqrt{2/M}      &   \text{else}
    \end{cases}
\end{equation}
%
%-------------------- FIGURE: QAM MODEM --------------------
\begin{figure}
\centering
\mbox{
  \subfigure[8-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_qam8}
      \label{fig:modem:qam:8}
    } \quad
  \subfigure[16-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_qam16}
      \label{fig:modem:qam:16}
    } \quad
}
\mbox{
  \subfigure[32-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_qam32}
      \label{fig:modem:qam:32}
    } \quad
  \subfigure[64-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_qam64}
      \label{fig:modem:qam:64}
    } \quad
}
\mbox{
  \subfigure[128-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_qam128}
      \label{fig:modem:qam:128}
    } \quad
  \subfigure[256-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_qam256}
      \label{fig:modem:qam:256}
    } \quad
}
% trim = left bottom right top
\caption{Rectangular quaternary-amplitude modulation (QAM) modem}
\label{fig:modem:qam}
\end{figure}
%
Figure~\ref{fig:modem:qam} depicts the arbitrary rectangular QAM modem
constellation maps for $M$ up to 256.
Notice that all the symbol points are gray encoded to minimize bit
errors between adjacent symbols.


\subsubsection{{\tt LIQUID\_MODEM\_ARB} (arbitrary modem)}
\label{module:modem:digital:ARB}
\liquid\ also allows the user to create their own modulation schemes by
designating the number of bits per symbol, and the full signal constellation.
Several pre-loaded arbitrary signal constellations are available.
%
%-------------------- FIGURE: OPTIMAL QAM --------------------
\begin{figure}
\centering
\mbox{
  \subfigure[optimal 16-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_arb16opt}
      \label{fig:modem:optqam:16opt}
    } \quad
  \subfigure[optimal 32-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_arb32opt}
      \label{fig:modem:optqam:32opt}
    } \quad
}
\mbox{
  \subfigure[optimal 64-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_arb64opt}
      \label{fig:modem:optqam:64opt}
    } \quad
  \subfigure[optimal 128-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_arb128opt}
      \label{fig:modem:optqam:128opt}
    } \quad
}
  \subfigure[optimal 256-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_arb256opt}
      \label{fig:modem:optqam:256opt}
    } \quad
% trim = left bottom right top
\caption{Optimal $M$-QAM constellation maps.}
\label{fig:modem:optqam}
\end{figure}
%
Figure~\ref{fig:modem:optqam} shows the constellation maps for the
optimal QAM schemes.
Notice that the constellations approximate a circle with each point
falling on the lattice of equalateral triangles.
Furthermore, adjacent constellation points differ by typically only a
single bit to reduce the resulting bit error rate at the output of the
demodulator.
These constellation marginally out-perform regular square QAM
(see Table~\ref{tab:modem:performance}) at the expense of a significaly
increased computational complexity.

%
%-------------------- FIGURE: ARB MODEM --------------------
\begin{figure}
\centering
\mbox{
  \subfigure[``square'' 32-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_sqam32}
      \label{fig:modem:arb:sqam32}
    } \quad
  \subfigure[``square'' 128-QAM]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_sqam128}
      \label{fig:modem:arb:sqam128}
    } \quad
}
\mbox{
  \subfigure[V.29]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_V29}
      \label{fig:modem:arb:V29}
    } \quad
  \subfigure[64-VT]
    {
      \includegraphics[trim = 15mm 0mm 15mm 0mm, clip, height=6cm]{figures.gen/modem_arb64vt}
      \label{fig:modem:arb:64vt}
    } \quad
}
% trim = left bottom right top
\caption{Arbitrary constellation (ARB) modem}
\label{fig:modem:arb}
\end{figure}
%
Figure~\ref{fig:modem:arb} depicts several available arbitrary
constellation maps;
however the user can create any arbitrary constellation map so long as
no two points overlap
(see {\tt modem\_arb\_init()} and {\tt modem\_arb\_init\_file()} in
Section~\ref{module:modem:digital:interface}).

\subsubsection{Performance}
\label{module:modem:digital:performance}

% ------------ TABLE: LINEAR MODULATION SCHEMES ------------
\begin{table*}
\caption{Performance of linear modulation schemes, $\hat{P}_b=10^{-5}$}
\label{tab:modem:performance}
\centering
{\footnotesize
\begin{tabular*}{0.65\textwidth}{l@{\extracolsep{\fill}}lr}
\toprule
{\it schemes} &
{\it $E_s/N_0$} &
{\it $E_b/N_0$}\\\otoprule
%
\multicolumn{3}{c}{$M=2$}\\
\midrule
BPSK, 2-ASK         &  9.59 &  9.59 \\
DBPSK               & 10.46 & 10.46 \\
OOK                 & 12.61 & 12.61 \\
%
\midrule
\multicolumn{3}{c}{$M=4$} \\
\midrule
QPSK, 4-QAM         & 12.59 &  9.59 \\
4-APSK              & 14.76 & 11.75 \\
DQPSK               & 14.93 & 11.92 \\
4-ASK               & 16.59 & 13.58 \\
%
\midrule
\multicolumn{3}{c}{$M=8$} \\\midrule
8-APSK              & 16.12 & 11.35 \\
8-QAM               & 17.28 & 12.51 \\
8-PSK               & 17.84 & 13.07 \\
8-DPSK              & 20.62 & 15.85 \\
8-ASK               & 22.61 & 17.84 \\
%
\midrule
\multicolumn{3}{c}{$M=16$} \\\midrule
ARB-16-OPT          & 19.15 & 13.13 \\
16-QAM              & 19.57 & 13.55 \\
16-APSK             & 19.92 & 13.90 \\
V.29                & 20.48 & 14.45 \\
16-PSK              & 23.43 & 17.41 \\
16-DPSK             & 26.43 & 20.41 \\
16-ASK              & 28.54 & 22.52 \\
%
\midrule
\multicolumn{3}{c}{$M=32$} \\\midrule
ARB-32-OPT          & 22.11 & 15.12 \\
32-SQAM             & 22.56 & 15.57 \\
32-APSK             & 23.43 & 16.44 \\
32-QAM              & 23.59 & 16.60 \\
32-PSK              & 29.38 & 22.38 \\
32-DPSK             & 32.38 & 25.39 \\
%
\midrule
\multicolumn{3}{c}{$M=64$} \\\midrule
ARB-64-OPT          & 25.22 & 17.44 \\
64-QAM              & 25.50 & 17.71 \\
64-APSK             & 27.06 & 19.28 \\
ARB-64-VT           & 31.67 & 23.89 \\
64-PSK              & 35.32 & 27.38 \\
64-DPSK             & 38.28 & 30.50 \\
%
\midrule
\multicolumn{3}{c}{$M=128$} \\\midrule
ARB-128-OPT         & 28.19 & 19.74 \\
128-SQAM            & 28.42 & 19.97 \\
128-QAM             & 29.60 & 21.15 \\
128-APSK            & 30.55 & 22.10 \\
%
\midrule
\multicolumn{3}{c}{$M=256$} \\\midrule
ARB-256-OPT         & 31.09 & 22.06 \\
256-QAM             & 31.56 & 22.53 \\
256-APSK            & 33.10 & 24.06 \\\bottomrule
%
\end{tabular*}
}
\end{table*}%
% ------------------------


\subsubsection{Soft Demodulation}
\label{module:modem:digital:soft}
Unlike hard demodulation which seeks the most likely transmitted
{\em symbol} for a given received sample,
the goal of soft demodulation is to derive a probability metric for each
{\em bit} for the received sample.
When using the output of the demodulator in conjuction with forward
error-correction coding, the soft bit information can improve the error
detection and correction capabilities of most decoders,
usually by about 1.5~dB.
This soft bit information provides a clue to the decoder as to the
confidence that each bit was received correctly.
For turbo-product codes \cite{Berrou:1993} and
low-density parity check (LDPC) codes \cite{Gallager:1962},
this soft bit information is nearly a requirement.

% ...
Before we continue, let us define some nomenclature:
%
\begin{itemize}
\item $M=2^m$ are the number of points in the constellation
      (constellation size).
\item $m=\log_2(M)$ are the number of bits per symbol in the
      constellation (modulation depth).
\item $s_k$ is the symbol at index $k$ on the complex plane;
      $k \in \{0,1,2,\ldots,M-1\}$.
\item $\{b_0,b_1,\ldots,b_{m-1}\}$ is the encoded bit string of $s_k$
      and is simply the value of $k$ in binary-coded decimal.
\item $b_j$ is the bit at index $j$;
      $b_j \in \{0,1\}$ and $j \in \{0,1,\ldots,m-1\}$.
\item $\mathcal{S}_M = \{s_0,s_1,\ldots,s_{M-1}\}$ is the set of all
      symbols in the constellation where
      $1/M \sum_k \|s_k\|_2^2 = 1$.
\item $\mathcal{S}_{b_j=t}$ is the subset of $\mathcal{S}_M$
      where the bit at index $j$ is equal to $t \in \{0,1\}$.
\end{itemize}
%
For example, let the modulation scheme be
the generic 4-PSK with the constellation map defined in Figure~\ref{fig:modem:psk:4}
which has $m=2$, $M=4$, and
$\mathcal{S}_M = \{s_0=1, s_1=j, s_2=-j, s_3=-1\}$.
Subsets:
\begin{itemize}
\item $\mathcal{S}_{b_0=0} = \{s_0= 1, s_2=-j\}$ (right-most bit is {\tt 0})
\item $\mathcal{S}_{b_0=1} = \{s_1= j, s_3=-1\}$ (right-most bit is {\tt 1})
\item $\mathcal{S}_{b_1=0} = \{s_0= 1, s_1= j\}$ (left-most bit is {\tt 0})
\item $\mathcal{S}_{b_1=1} = \{s_2=-j, s_3=-1\}$ (left-most bit is {\tt 1})
\end{itemize}
%
A few key points:
\begin{itemize}
\item $\mathcal{S}_{b_j=0} \cap \mathcal{S}_{b_j=1} = \emptyset,     \, \forall_j$.
\item $\mathcal{S}_{b_j=0} \cup \mathcal{S}_{b_j=1} = \mathcal{S}_M, \, \forall_j$.
\end{itemize}
%

%
Let us represent the received signal at a sampling instant $n$ as
%
\begin{equation}
\label{eqn:modem:digital:soft:received_signal}
    r(n) = s(n) + w(n)
\end{equation}
%
where $s$ is the transmitted symbol
and $w$ is a zero-mean complex Gauss random variable with
a variance $\sigma_n^2 = E\{n n^*\}$.
Let the transmitted symbols be {\em i.i.d.} and drawn from a $M$-point
constellation, each with $m$ bits of information
such that the symbols belong to a set of constellation points
$s_k \in \mathcal{S}_M$ and $E\{s_k s_k^*\}=1$.
%
Assuming perfect channel knowledge, timing, and carrier offset recovery,
the log-likelihood ratio (LLR) of each bit $b_j$ is shown to be
\cite[Eq.~(8)]{LeGoff:1994}
the ratio of the two conditional {\em a posteriori} probabilities of
each bit having been transmitted, viz.
%
\begin{equation}
\label{eqn:modem:digital:soft:LLR_true}
    \Lambda(b_j) =
        \ln \frac{
            P\left(b_j=1 | {observation} \right)
        }{
            P\left(b_j=0 | {observation} \right)
        }
\end{equation}
%
Assuming that the channel is memoryless the ``observation'' is simply
the received sample $r$ in
(\ref{eqn:modem:digital:soft:received_signal})
and does not depend on previous symbols; therefore
$P\left(b_j=t|{observation}\right) = P\left(b_j=t|r(n)\right)$
and $t \in \{0,1\}$.
Furthermore, by assuming that the transmitted symbols are equally
probable and that the noise follows a Gauss distribution
\cite{Qiang:2003}
the LLR reduces to
%
\begin{equation}
\label{eqn:modem:digital:soft:LLR}
    \Lambda(b_j) =
        \ln \Biggl(
            \sum_{s^+\in \mathcal{S}_{b_j=1}} { \exp\Bigl\{\|r-s^+\|_2^2 / 2 \sigma_n^2\Bigr\} }
        \Biggr)
       -\ln \Biggl(
            \sum_{s^-\in \mathcal{S}_{b_j=0}} { \exp\Bigl\{\|r-s^-\|_2^2 / 2 \sigma_n^2\Bigr\} }
        \Biggr)
\end{equation}
%
As shown in \cite{Qiang:2003} a sub-optimal simplified LLR expression
can be obtained by replacing the summations in
(\ref{eqn:modem:digital:soft:LLR}) with the single largest component of
each: $\ln \sum_j {e^{z_j}} \approx \max_j \ln (e^{z_j}) = \max_j z_j$.
This approximation provides a tight bound as long as the sum is
dominated by its largest component.
The approximate LLR becomes
%
\begin{equation}
\label{eqn:modem:digital:soft:LLR_approx}
    \tilde{\Lambda}(b_j) =
        \frac{1}{2\sigma_n^2}
        \Bigl\{
            \underset{s^+\in \mathcal{S}_{b_j=0}}{\min} \|r-s^+\|_2^2 -
            \underset{s^-\in \mathcal{S}_{b_j=1}}{\min} \|r-s^-\|_2^2
        \Bigr\}
\end{equation}
%
Conveniently, both the exponential and logarithm operations disappear;
furthermore, the noise variance becomes a scaling factor and is only
used to influence the reliability of the obtained LLR.

%
%-------------------- FIGURE: MODEM DEMOD SOFT--------------------
\begin{figure}
\centering
\mbox{
  \subfigure[$\tilde{\Lambda}(b_0) = -10.55$]
    {
      \includegraphics[trim = 18mm 0mm 15mm 0mm, clip, width=8cm]{figures.gen/modem_demodsoft_b0}
      \label{fig:modem:demodsoft:b0}
    } \quad
  \subfigure[$\tilde{\Lambda}(b_1) = -0.28$]
    {
      \includegraphics[trim = 18mm 0mm 15mm 0mm, clip, width=8cm]{figures.gen/modem_demodsoft_b1}
      \label{fig:modem:demodsoft:b1}
    } \quad
}
\mbox{
  \subfigure[$\tilde{\Lambda}(b_2) = -7.43$]
    {
      \includegraphics[trim = 18mm 0mm 15mm 0mm, clip, width=8cm]{figures.gen/modem_demodsoft_b2}
      \label{fig:modem:demodsoft:b2}
    } \quad
  \subfigure[$\tilde{\Lambda}(b_3) = 2.57$]
    {
      \includegraphics[trim = 18mm 0mm 15mm 0mm, clip, width=8cm]{figures.gen/modem_demodsoft_b3}
      \label{fig:modem:demodsoft:b3}
    } \quad
}
% trim = left bottom right top
\caption{
    Soft demodulation example of a 16-QAM sample.
    Each plot depicts the soft demodulation of each of the 4 bits where
    the $\times$ denotes the received sample and the lines connect it to
    the nearest symbol with each of a {\tt 0} and {\tt 1} bit. %REWORD
    The noise standard deviation is $\sigma_n=0.2$.
}
\label{fig:modem:demodsoft}
\end{figure}
%
Figure~\ref{fig:modem:demodsoft} depicts the soft bit demodulation
algorithm for a received 16-QAM signal point, corrupted by noise.
The received sample is $r = -0.65 - j0.47$ which results in a hard
demodulation of {\tt 0001}.
The subfigures depict each of the four bits in the symbol 
$\{b_0,b_1,b_2,b_3\}$
for which the
soft bit output is given, and show the nearest symbol for which a
{\tt 0} and a {\tt 1} at that particular bit index occurs.
For example, Figure~\ref{fig:modem:demodsoft:b2} shows that
the nearest symbol containing a {\tt 0} at bit index 2
is $s_1=${\tt 0001} (the hard decision demodulation)
at $(-3 - j)/\sqrt{10}$
while
the nearest symbol containing a {\tt 1} at bit index 2
is $s_3=${\tt 0011}
at $(-3 + j)/\sqrt{10}$.
Plugging $s^-=s_1$ and $s^+=s_3$ into
(\ref{eqn:modem:digital:soft:LLR_approx})
and evaluating for $\sigma_n=0.2$ gives
$\tilde{\Lambda}(b_2) = -7.43$.
Because this number is largely negative, it is very likely that the
transmitted bit $b_2$ was {\tt 0}.
This can be verified by Figure~\ref{fig:modem:demodsoft:b2} which shows
that the distance from $r$ to $s^-$ is much shorter than that of $s^+$.

Conversely, Figure~\ref{fig:modem:demodsoft:b1} shows that $b_1$ cannot
be demodulated with such certainty;
the distances from $r$ to each of $s^+$ and $s^-$ are about the same.
This is reflected in the relatively small LLR value of
$\tilde{\Lambda}(b_1)=-0.28$ which suggests a high uncertainty in the
demodulation of $b_1$.
%

% 
% specific implementation
%
One major drawback of computing
(\ref{eqn:modem:digital:soft:LLR_approx}) is that finding the maximum
requires searching over all constellation points to find the one which
minimizes $\|r-s_k\|$
(where $s_k \in \mathcal{S}_{b_j=t}$) is particularly time-consuming.
% TODO : explain in more detail
To circumvent this, \liquid\ only searches over a subset
$\mathcal{S}_k \subset \mathcal{S}_M$ nearest to the
hard-demodulated symbol
% $\mathcal{S}_k$ is the subset of $\mathcal{S}_M$
%  nearest to the symbol $s_k$.
($\mathcal{S}_k$ will typically only have about four values).
This can be done quickly because the hard-demodulated symbol can be
found systematically for most modulation schemes
(e.g. for {\tt LIQUID\_MODEM\_QAM} only $\ord(\log_2 M)$ comparisons are
needed to make a hard decision).
%
If no symbols are found within $\mathcal{S}_k$ for a given bit value
such that $\mathcal{S}_k \cap \mathcal{S}_{b_j=t} = \emptyset$
then the magnitude of $\Lambda(b_j)$ is sufficiently large
and contains little soft bit information;
that is
$\tilde{\Lambda}(b_j) \gg 0$ when $\mathcal{S}_k \cap \mathcal{S}_{b_j=0} = \emptyset$
and
$\tilde{\Lambda}(b_j) \ll 0$ when $\mathcal{S}_k \cap \mathcal{S}_{b_j=1} = \emptyset$.
%
It is guaranteed that
$   \left( \mathcal{S}_k \cap \mathcal{S}_{b_j=0}\right)
        \cup
    \left( \mathcal{S}_k \cap \mathcal{S}_{b_j=1}\right)
    \neq \emptyset $
because $s_k$ must be in either $\mathcal{S}_{b_j=0}$ or
$\mathcal{S}_{b_j=1}$.
%

% 
% soft bit representation
%
Soft bit information is stored in \liquid\ as type {\tt unsigned char}
with a value of {\tt 255} representing a {\em very likely {\tt 1}},
and a value of {\tt 0} representing a {\em very likely {\tt 0}}.
The {\em erasure} condition is {\tt 127}.
%
\begin{Verbatim}[fontsize=\small]
soft bit value:  [0 1 2 3      ...   64 65   ...  127  ...  192 193   ...  253 254 255]
interpretation:  very likely '0'   likely '0'   erasure   likely '1'    very likely '1'
\end{Verbatim}
%
The {\tt fec}  and {\tt packetizer} objects can make use of this soft
information to improve the probability of decoding a packet
(see Sections~\ref{module:fec:soft} and
\ref{module:framing:packetizer} for details).

\subsubsection{Error Vector Magnitude}
\label{module:modem:digital:evm}
The error vector magnitude (EVM) of a demodulated symbol is simply the
average maginitude of the error vector between the received sample
before demodulation and the expected transmitted symbol, viz.
%
\begin{equation}
\label{eqn:modem:evm}
    \textup{EVM} = E\left\{ \left| s - \hat{s} \right|^2 \right\}
\end{equation}
%
EVM is returned by many of the framing objects
(see Section~\ref{module:framing})
because it gives a good indication of signal distortion as a result of
noise, inter-symbol interference, etc.
If the only channel impairment is noise (e.g. perfect symbol timing)
then the SNR can be approximated as
\[
    \hat{\gamma} \approx 1 / \textup{EVM}
\]


%
% CONTINUOUS PHASE MODEMS
%

\subsection{Continuous phase digital modulation schemes}
\label{module:modem:cpm}

\subsubsection{{\tt gmskmod} (Gauss minimum-shift keying)}
\label{module:modem:cpm:gmskmod}

Two objects: {\tt gmksmod} (GMSK modulator), {\tt gmskdem} (GMSK
demodulator).
%
\input{listings/gmskmodem.example.c.tex}
%

{'fraction_non_alphanumeric': 0.13391741109824204, 'fraction_numerical': 0.037842734768299253, 'mean_word_length': 3.012146307798482, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 71, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '78590', 'n_tokens_mistral': 32252, 'n_tokens_neox': 29656, 'n_words': 9362}