%mainfile: ../master.tex
\section{Criteria for Language Design}\label{analsum}

This section will, in light of the preceding two chapters, \cref{part:analysis,part:analysis2}, settle on some criteria for TLDR. The criteria are inspired by those found in \cite{sebesta2015concepts}. However, only those characteristics which differentiate TLDR will be discussed, even though other characteristics will be present in the language.

\subsection{Simplicity, Orthogonality and Syntax Design}

In order to accommodate a user group with programming as a secondary skill set, TLDR should be simple. This would result in strict and straightforward rules regarding interactions. The language should try to keep simple rules regarding orthogonality as well, but not necessarily be highly orthogonal for that reason. The syntax design, should for these reasons, cater towards a mathematical perspective rather than a computer science perspective.

\subsection{Data Types}

Since the users of TLDR will typically have a background in mathematics, or require  the use of some mathematics in order to asses the value of any given result of a simulation, the language should strive towards having data types which allow for representation of traditional mathematical numbers.

\subsection{Type Checking and Exception Handling}

Due to the language targeting high performance computation, the language should try to avoid run-time errors, and catch problems as early as possible. This suggests a strongly typed language, but this will be elaborated further on in \cref{typesys}. For the same reasons, the language will not value exception handling, since edge cases should be fully encompassed in a simulation. However it is worth noticing that the actor model could require exception handling, if communication problems, caused by either race conditions or network conditions, should prove frequent.

\subsection{Readability over Writability}

TLDR values readability over writability, since the problems which the languages aims to support are usually big complex mathematical problems, which quickly can confuse the programmers, if they are not able to understand the code. The size of the problems will also likely popularise the use of external libraries, which will also benefit from readability, since an understanding of the functionalities supplied by a given library is useful when exploring which library best solves the problem.


\documentclass[fleqn]{article}

\usepackage[margin=1in]{geometry}
\usepackage{amsmath}

\newcommand{\mxd}{\texttt{mxd}}

\title{\mxd\\Basic Conceps}
\author{F.~Ayala and D.~Rockensahn and J.~Arrieta}
\date{Dec 08, 2018\\\small{Last Update:~\today}}

\begin{document}
\maketitle

\section{Orbital Elements}
In this section we explain some orbital element sets and how to convert to and
from different sets.
\subsection{Cartesian Elements}
The Cartesian elements are
\begin{align}
  \vec{r}(t), \vec{v}(t).
\end{align}
They define position and velocity at a given time.

\subsection{Keplerian Elements}
The Keplerian elements are.
\begin{align}
  a, e, i, \omega, \Omega, f(t).
\end{align}
They define semimajor axis, eccentricity, inclination, right ascension of the
ascending node, argument of periapsis, and true anomaly. Notice that only true
anomaly varies with time.

TODO: Explain what is an osculating orbit.

TODO: Explain why the given elements only apply to elliptical (non-circular,
non-parabolic, non-hyperbolic) orbits.

\subsection{Cartesian-Keplerian Conversion}
TODO: How to get from Cartesian to Keplerian elements.

\subsection{Keplerian-Cartesian Conversion}
TODO: How to get from Keplerian to Cartesian elements.

\section{Basic Vector Algebra}
TODO: Add basic vector algebra

\section{Drawing Conic Sections}
TODO: Explain how would one go about drawing a conic section (which is in a
plane) in some three-dimensional frame.

\end{document}


    \filetitle{dd}{Matlab serial date numbers that can be used to construct daily tseries objects}{dates/dd}

	\paragraph{Syntax}\label{syntax}

\begin{verbatim}
Dat = dd(Year,Month,Day)
\end{verbatim}

\paragraph{Output arguments}\label{output-arguments}

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  \texttt{Dat} {[} numeric {]} - IRIS serial date numbers.
\end{itemize}

\paragraph{Input arguments}\label{input-arguments}

\begin{itemize}
\item
  \texttt{Year} {[} numeric {]} - Years.
\item
  \texttt{Month} {[} numeric {]} - Months.
\item
  \texttt{Day} {[} numeric {]} - Days.
\end{itemize}

\paragraph{Description}\label{description}

\paragraph{Example}\label{example}


\chapter{Time-Frequency Masking}\label{ch:tf_mask_ch}
\section{Introduction}
Speech separation, in similarity to other
prevalent enhancement applications, such as the
Computational Auditory Scene Analysis (CASA)\cite{BROWN1994297}
and Blind Speech Separation (BSS)\cite{6709849},
makes use of various
algorithms in order to distinguish in one way or another
between desired speech and interferences.
The advantages of precise distinction
between speech and interference include, among others,
the ability to apply speech enhancements,
noise cancelation or reduction, speech corrections, and more.
With ASR systems, these abilities are expressed in
improved performance of precisely detecting words
with higher detection rates.

A typical algorithm in CASA applications is the
Time-Frequency Masking (T-F Masking).
Since speech signals vary with time,
as described in chapter \;\ref{ch:features},
they are not considered stationary.
Hence, a unique representation is required
for conducting an accurate analysis of such signals.

A T-F representation means presenting a speech
signal in time-frequency composition,
where each T-F unit contains the
speech's spectral elements at a certain time window bin.
As described in chapter\;\ref{ch:features},
the T-F presentation of a signal
arrives by using the STFT or auditory filtering\cite{Xia2017UsingOR}.

\begin{figure}[H]
    \centering
    \includegraphics[width=\linewidth]{Features/images/noisy_specgram}
    \caption{Noisy mixture spectrogram}\label{fig:noisy_specgram}
\end{figure}
\begin{figure}[H]
    \centering
    \includegraphics[width=\linewidth]{Features/images/clean_specgram}
    \caption{Reference clean speech spectrogram}\label{fig:clean_specgram}
\end{figure}

Examination of the T-F units provides a
possibility to classify an entire unit
or parts of a unit
as a speech-centric bin or, on the contrary,
as interference (mainly noise).
Based on this classification,
appropriate weights are associated with each segment bin.
In that way, speech elements can be extracted
by separating of the classified speech
out of the mixture, or alternatively,
the attenuation of non-speech elements
in certain activity areas
along the length of the audio signal.
In general, the association of weights for classifying different
elements in a signal is called T-F masking.
This process of T-F masking takes a
significant role in CASA and BSS applications,
and in recent years, they proved to be
very useful in E2E-ASR systems.

Additional use of T-F masking
is to tie it as input to a beamformer that
in turn, filters interferences based
on the classification received
by the masking operation.

\section{IBM --- Ideal Binary Mask}
Assuming that a voice activity detection algorithm
can separate speech from noise effectively,
the IBM technique is based on power differences.
Whenever the speech's power
spectral density (PSD) is higher
than any of the interferences PSD,
the speech is masked binarily to ``1''.
\begin{align}\label{eq:ibm_mask}
    \mathbf{M}_{s}(j\omega, t) & =
        \begin{cases}
            1, & if\;|\mathbf{S}(t,j\omega)|^2 - |\mathbf{N}(t,j\omega)|^2 > \epsilon \\
            0, & otherwise
        \end{cases}
\end{align}
Where \(\epsilon\) marks a changeable threshold value
for the speech activity detection over the noise.

Equation~\ref{eq:ibm_mask} indicates that as a result of
applying the IBM masks, the speech and interference separated
sources become complementary in such a way that
\[\mathbf{M}_{n} = 1 - \mathbf{M}_{s} \] and thus:
\begin{align}
    y(t) &= \begin{cases}
        \hat{x_{s}}, &if\;\;\mathbf{M}_{s} = 1 \\
        \hat{x_{n}}, &if\;\;\mathbf{M}_{s} = 0
    \end{cases}
\end{align}

\section{IRM --- Ideal Ratio Mask}
% \begin{align}
%     \mathrm{IRM}(f;t) = \left( \frac{ || }{  } \right)
% \end{align}
Unlike IBM, where hard decisions in terms of
boolean values are made,
that is, marking speech or noise
elements with ``true'' or ``false'', the Ideal Ratio Mask (IRM) provides a soft decision
mechanism with values in the range of \([0,1]\)\cite{Jiang2018RobustBF}.
The IRMs at any T-F unit of the clean speech and noise artifacts,
\(\mathbf{M}_{s}(j\omega, t)\) and \(\mathbf{M}_{n}(j\omega, t)\),
are given in
Equations\;\ref{eq:irm_speech} and \ref{eq:irm_noise}, respectively.

\begin{align}
    \label{eq:irm_speech}\mathbf{M}_{s}(j\omega, t) & = {\left( \frac{|\mathbf{S}(t,j\omega)|^2}{|\mathbf{S}(t,j\omega)|^2 + |\mathbf{N}(t,j\omega)|^2} \right)}^{\beta} \\
    \label{eq:irm_noise}\mathbf{M}_{n}(j\omega, t) & = {\left( \frac{|\mathbf{N}(t,j\omega)|^2}{|\mathbf{S}(t,j\omega)|^2 + |\mathbf{N}(t,j\omega)|^2} \right)}^{\beta}
\end{align}

Where \(\beta \) is a tunable parameter that
controls the strength of the mask estimations.
A value of 0.5 is used
for a fair trade-off between speech and noise mask estimations.
%
\begin{align}
    \mathbf{M}_{s}(j\omega, t) & = \sqrt{\left( \frac{|\mathbf{S}(t,j\omega)|^2}{|\mathbf{S}(t,j\omega)|^2 + |\mathbf{N}(t,j\omega)|^2} \right)} \\
    \mathbf{M}_{n}(j\omega, t) & \approx 1 - \mathbf{M}_{s}
\end{align}

\begin{figure}[H]
    \centering
    \includegraphics[width=\linewidth]{Features/images/irm_mask}
    \caption{IRM Speech Mask \(\mathbf{M}_{s}(j\omega, t)\)}\label{fig:irm_mask}
\end{figure}
\begin{figure}[H]
    \centering
    \includegraphics[width=\linewidth]{Features/images/irm_mask_noise}
    \caption{IRM Noise Mask \(\mathbf{M}_{n}(j\omega, t)\)}\label{fig:irm_mask_noise}
\end{figure}

%
Thus, the covariance matrices are extracted by:
\begin{align}
    \mathbf{R}_{NN}(j\omega) & = \frac{1}{\sum\limits_{t=1}^{T}\mathbf{M}_{n_{(jw, t)}}}\sum_{t=1}^{T}\mathbf{M}_{n_{(jw, t)}}|\mathbf{R}_{x_{(jw, t)}}|^2\\
    \mathbf{R}_{SS}(j\omega) & = \frac{1}{\sum\limits_{t=1}^{T}\mathbf{M}_{s_{(jw, t)}}}\sum_{t=1}^{T}\mathbf{M}_{s_{(jw, t)}}|\mathbf{R}_{x_{(jw, t)}}|^2
\end{align}

\subsection{Masks Estimations}
The IRM masks, \(\mathbf{M}_{s}(j\omega, t)\), \(\mathbf{M}_{n}(j\omega, t)\)
given in Equations\;\ref{eq:irm_speech}, \ref{eq:irm_noise} are bounded
in the range of [0, 1].
Since both the speech and noise masks are bounded in that range, it is easier
to use a Sigmoid activation function
as the output layer,
thus ensuring the output indeed remains in this range.

A simple neural network of six to eight fully-connected (FC) layers,
as seen in Figure\;\ref{fig:irm_dnn}, is proposed for
classifying the input features to the desired IRM masks.
The network's input features are the MFCCs of the microphone-array.
Each input signal is framed into \(25ms\) lasting frames with a
hopping length of \(6.25ms\). With a sampling frequency of \(16KHz\),
the framing settings are 400 samples per frame and
a total of 300 overlapping samples.

A BLSTM (Bidirectional Long Short-Term Memory)
layer is placed as the first block in the network,
giving weight to the temporal context as well.
In that way, three additional adjacent feature maps
are concatenated from both sides of the currently
processed T-F unit feature map.
The BLSTM is then followed
by several fully connected (FC) layers
holding in between the ReLU activation functions.

\begin{figure}[H]
    \centering
    \includegraphics[width=0.95\linewidth]{Features/images/irm_dnn}
    \caption{IRM estimation DNN blocks diagram}\label{fig:irm_dnn}
\end{figure}

Production of both the speech and noise estimations co-occurs.
Consequently, the cost function should
consider the two masks in the
minimization process of the error term.
To that end, the cost function is defined as:
\begin{align}
    \ell(\mathbf{\widehat{M}}_{j\omega, t},\;\mathbf{M}_{j\omega, t}) & =
        \frac{1}{2N}\sum_{j\omega, t}
        \left[
            \beta\!\left(
                \mathbf{\widehat{M}}^{(s)}_{j\omega, t} -
                \mathbf{M}^{(s)}_{j\omega, t}
            \right)^{2}
            + \left( 1- \beta \right)\!
            \left(
                \mathbf{\widehat{M}}^{(n)}_{j\omega, t} -
                \mathbf{M}^{(n)}_{j\omega, t}
            \right)^{2}
        \right]
\end{align}
Here, \(\beta\) denotes the weighing factor.
For a fair and evenly consideration between the masks, \(\beta \)
is set to 0.5.

The proposed IRM estimation network blocks diagram is shown in
Figure\;\ref{fig:irm_nn}.

\begin{figure}[H]
    \centering
    \includegraphics[width=0.75\linewidth]{Beamformers/images/irm_nn}
    \caption{Proposed DNN for IRM T-F masking estimations}\label{fig:irm_nn}
\end{figure}

\begin{figure}[H]
    \centering
    \subfloat[\label{irm_s_ref}]{%
       \includegraphics[width=0.45\linewidth]{Beamformers/images/irm_s_ref}}
    \hspace{0.1cm}
    \subfloat[\label{irm_s_nn}]{%
        \includegraphics[width=0.45\linewidth]{Beamformers/images/irm_s_nn}}
    \vspace{-0.35cm}
    \subfloat[\label{irm_n_ref}]{%
        \includegraphics[width=0.45\linewidth]{Beamformers/images/irm_n_ref}}
    \hspace{0.1cm}
    \subfloat[\label{irm_n_nn}]{%
        \includegraphics[width=0.45\linewidth]{Beamformers/images/irm_n_nn}}
        \caption{(a) and (b) are the ``IRM''
        reference vs. estimation masks of the speech.
        \(\mathbf{\widehat{M}}^{(s)}_{j\omega, t}\), \(\mathbf{M}^{(s)}_{j\omega, t}\);\;\;
        (c) and (d) are the ``IRM'' reference vs. estimation masks
        of the noise \(\mathbf{\widehat{M}}^{(n)}_{j\omega, t}\), \(\mathbf{M}^{(n)}_{j\omega, t}\).}\label{fig:irm_ref_s_n}
\end{figure}

\subsection{Measurements}
\subsubsection{SNR}
\begin{figure}[H]
    \centering
    \subfloat[\label{irm_enh_snr}]{%
       \includegraphics[width=0.5\linewidth]{Features/images/irm_enh_snr}}
    % \hspace{0.1cm}
    \subfloat[\label{irm_noisy_snr}]{%
        \includegraphics[width=0.5\linewidth]{Features/images/irm_noisy_snr}}
    \caption{(a) ``IRM'' enhanced SNR \& Segmental-SNR degradation
        with respect to the clean reference speech;\;\;
        (b) The SNR \& Segmental-SNR ratios between the
        clean reference speech and the noisy mixture.}\label{fig:irm_enh_noisy_snr}
\end{figure}

Figure\;\ref{fig:irm_enh_noisy_snr} shows two measurements of the SNR \&
Segmental-SNR metrics for two subject signals,
an ``IRM'' enhanced beamformed
version of the noisy mixture and the noisy mixture itself
with respect to the clean reference speech.
The overall improvements in SNR and Segmental-SNR
are the ratios between the enhanced beamformed signal
and the noisy mixture. Thus, from Figure\;\ref{fig:irm_enh_noisy_snr}
the accumulated improvement in SNR is:
\[|SNR_{noisy}| - |SNR_{enh}| = 5.1725\;[dB]\]
Likewise, the improvement in Segmental-SNR is \(9.2675\;[dB]\).
It is important to note that the enhanced beamformed signal
does not align in time with the clean speech reference.
In a worst-case scenario, we measured a delay of \(-0.0014\;[s]\),
which equals approximately \(22\) samples.
A perfectly aligned comparison considers being more
accurate, but since the frame lengths' (400 samples)
are much larger than the worst measured delay,
the impact of this time misalignment is less acute.
The Segmental-SNR calculation involves
a VAD (voice activity detection) algorithm
for dropping segments where the detected speech activity is negligible.
These dropped segments are red colored in Figure\;\ref{fig:irm_enh_noisy_snr}.

\begin{figure}[H]
    \centering
    \includegraphics[width=\linewidth]{Experiments/images/irm_pesq_mosq}
    \caption{IRM beamformer PESQ vs. MOSLQ}\label{fig:irm_pesq_mosq}
\end{figure}

In Figure\;\ref{fig:irm_pesq_mosq} presented the ``PESQ'' and ``MOSLQ''
metrics for the IRM beamformer. The results are shown in a pair-plot
diagram, where the correlations between each pair of metrics are plotted.
On the diagonal, the distributions of the measured values are shown.
On top of the plots also shown are the mean values for both
the ``PESQ'' and ``MOSLQ'' under the test cases of the real and
simulation datasets from the ``CHiME4'' dataset. ``et'' stands for
the evaluation subset and ``dt'' marks the development subset.
More details about the datasets are provided in Chapter\;\ref{ch:datasets}.

A strong correlation between the ``PESQ'' and ``MOSLQ'' is seen in the
plot, and this behavior is both understandable and desirable since
the ``MOSLQ'' metric is based on the ``PESQ'' measurement.

Another pair-plot for the SNR, ``Segmental-SNR'', ``SI-SNR'' and ``STOI''
metrics is shown in Figure\;\ref{fig:irm_snr_stoi}.
The ``simulation'' subset yields better results in terms of
performance. It is important to note that faulty microphones
in the ``real'' subset are dropped prior to taking the measurements.
Nevertheless, the ambient noise absorbed is characterized by
a real scenario and a non-artificial room impulse response. On the other hand,
the ``simulation'' subset is composed of a recording taken in a relatively
clean environment (recording booth) and an artificial mixture of
the recorded background noises.

Because the SNR and Segmental-SNR are measured as the improvement
compared to the noisy mixture,
and since the background noises are truncated
to match the booth recorded speech for the ``simulation'' subset,
the results for those metrics are more sparsely distributed
compared to the ``real'' subset measurements.
With the ``SI-SNR'',
the measurements are taken regardless of the noisy mixture.
Hence, the ``simulation'' results are far better
and more spatially dense
in contrast to the ``real'' subset ``SI-SNR'' results.

Likewise, in the same manner,
the ``STOI'' is measured regardless of the noisy mixture
but relatively to the clean speech.
Therefore, the ``simulation''
subset distribution is narrower with lower variance.

% The results are summarized in Table\;\ref{tbl:irm_snr_stoi},
% side by side with the ideal masks and the improvement ratios.

\begin{figure}[H]
    \centering
    \includegraphics[width=\linewidth]{Features/images/irm_snr_stoi}
    \caption{IRM beamformer SNR vs. Segmental-SNR vs. STOI vs. SI-SNR}\label{fig:irm_snr_stoi}
\end{figure}

In order to evaluate the generalization of the prediction model,
the DNN estimations are compared to the ideal mask enhancement.
In Figure\;\ref{fig:irm_ideal_snr}, shown is the measurements of
the SNR and ``Segmental-SNR'' for an ideal IRM mask.
SNR measurement.

\begin{figure}[H]
    \centering
    \includegraphics[width=\linewidth]{Features/images/irm_ideal_snr}
    \caption{Ideal IRM beamformer enhancement SNR \& Segmental-SNR.}\label{fig:irm_ideal_snr}
\end{figure}

\section{cIRM --- Complex Ideal Ratio Mask}\label{ssec:cirm}
Both IBM and IRM utilize the noise and speech magnitudes only
while completely neglecting the phase arguments.
The outcome of the STFT operation is a complex pair
representation of each T-F unit. Recent studies
showed the importance of
the phase element in
speech seperation\cite{7364200,Xia2017UsingOR}.

In that manner, further extension of the IRM mask
to include the imaginary part
altogether with the magnitudes forms the cIRM.
Thus, instead of having a magnitude only based mask matrix, a complex
pair of masking matrices that make use of the phase element too is given.

The mixture \(y(t)\) after being processed by
the STFT operation can be described as a complex sum
whether in polar coordinates as seen in Equation\ref{eq:ystft_polar}
or in the general form as in Equation\ref{eq:ystft_general}.
\begin{align}\label{eq:ystft_polar}
    \mathbf{Y}(j\omega, t)  & = \mathcal{STFT} \{ y(t) \} := \mathbf{Y}_{j\omega, t} \nonumber \\
                            & = |\mathbf{A}_{_{\mathbf{Y}}}|\cos(\bm{\theta}_{_{\mathbf{Y}}})
                            + j|\mathbf{A}_{_{\mathbf{Y}}}|\sin(\bm{\theta}_{_{\mathbf{Y}}}) \\
\label{eq:ystft_general}      & = \mathbf{Y}_{r} + j\mathbf{Y}_{i}
\end{align}

The real and imaginary parts can be summarized as:
\begin{align}
    \mathbf{Y}_{r} & := \mathfrak{R}_{_{\mathfrak{C}}} \{\mathbf{Y}_{j\omega, t}\}
                            = |\mathbf{A}_{_{\mathbf{Y}}}|\cos(\bm{\theta}_{_{\mathbf{Y}}})  \\
    \mathbf{Y}_{i} & := \mathfrak{T}_{_{\mathfrak{M}}} \{\mathbf{Y}_{j\omega, t}\}
                            = |\mathbf{A}_{_{\mathbf{Y}}}|\sin(\bm{\theta}_{_{\mathbf{Y}}})
\end{align}
Extraction of the magnitude and phase from the complex representation
is accomplished by the following set of
Equations\ref{eq:complex_mag},\ref{eq:complex_phase}:
\begin{align}\label{eq:complex_mag}
    |\mathbf{A}_{_{\mathbf{Y}}}|    & = \sqrt{ \mathfrak{R}_{_{\mathfrak{C}}} \{\mathbf{Y}_{j\omega, t}\}^{2}
                                            + \mathfrak{T}_{_{\mathfrak{M}}} \{\mathbf{Y}_{j\omega, t}\}^{2} } \\
    \label{eq:complex_phase}\bm{\theta}_{_{\mathbf{Y}}}     & = \tan^{-1} \Bigg\{ \frac{ \mathfrak{T}_{_{\mathfrak{M}}} \{\mathbf{Y}(j\omega, t)\} }
                                            {\mathfrak{R}_{_{\mathfrak{C}}} \{\mathbf{Y}(j\omega, t)\}} \Bigg\}
\end{align}
Rearranging the equations above,
we can write the cIRM mask's real and
imaginary parts as:
\begin{align}
    \mathbf{M}_{r} & = \frac{\mathbf{Y}_{r}\mathbf{S}_{r} + \mathbf{Y}_{i}\mathbf{S}_{i}}
                            { \mathbf{Y}_{r}^{2} + \mathbf{Y}_{i}^{2}} \\
    \mathbf{M}_{i} & = \frac{\mathbf{Y}_{r}\mathbf{S}_{i} - \mathbf{Y}_{i}\mathbf{S}_{r}}
                            { \mathbf{Y}_{i}^{2} + \mathbf{S}_{r}^{2}}
\end{align}
Thus, the complex masks for the speech and noise are:
\begin{align}
    \mathbf{M}^{(s)}_{j\omega, t} & = \mathbf{M}^{(s)}_{r} + j\mathbf{M}^{(s)}_{i} \nonumber \\
            & = \frac{\mathbf{Y}_{r}\mathbf{S}_{r} + \mathbf{Y}_{i}\mathbf{S}_{i}}
            { \mathbf{Y}_{r}^{2} + \mathbf{Y}_{i}^{2}}
            + j \frac{\mathbf{Y}_{r}\mathbf{S}_{i} - \mathbf{Y}_{i}\mathbf{S}_{r}}
            { \mathbf{Y}_{i}^{2} + \mathbf{S}_{r}^{2}} \label{eq:cirmr_mask} \\
    \mathbf{M}^{(n)}_{j\omega, t} & = \mathbf{M}^{(N)}_{r} + j\mathbf{M}^{(N)}_{i} \nonumber \\
    & = \frac{\mathbf{Y}_{r}\mathbf{N}_{r} + \mathbf{Y}_{i}\mathbf{N}_{i}}
    { \mathbf{Y}_{r}^{2} + \mathbf{Y}_{i}^{2}}
    + j \frac{\mathbf{Y}_{r}\mathbf{N}_{i} - \mathbf{Y}_{i}\mathbf{N}_{r}}
    { \mathbf{Y}_{i}^{2} + \mathbf{N}_{r}^{2}} \label{eq:cirmi_mask}
\end{align}
Therefore, applying a cIRM T-F masking requires a complex multiplication
for separation as opposed to the more basic IBM and IRM
where magnitudes multiplications are taken in the real domain only.

The reference compressed cIRM masks are
shown in Figure\;\ref{fig:cirm_ref_s_n};

\begin{figure}[H]
    \centering
    \subfloat[\label{cIRM_real_mask}]{%
       \includegraphics[width=0.45\linewidth]{Features/images/cIRM_real_mask}}
    \subfloat[\label{cIRM_imag_mask}]{%
        \includegraphics[width=0.45\linewidth]{Features/images/cIRM_imag_mask}}
    \vspace{-0.35cm}
    \subfloat[\label{cIRM_real_noise_mask}]{%
        \includegraphics[width=0.45\linewidth]{Features/images/cIRM_real_noise_mask}}
    \subfloat[\label{cIRM_imag_noise_mask}]{%
        \includegraphics[width=0.45\linewidth]{Features/images/cIRM_imag_noise_mask}}
        \caption{(a) and (b) are the cIRM
        real and imaginary references of the speech
        \(\mathbf{M}^{(s)}_{r}\), \(\mathbf{M}^{(s)}_{i}\);\;\;
        (c) and (d) are the cIRM real and imaginary references
        of the noise \(\mathbf{M}^{(n)}_{r}\), \(\mathbf{M}^{(n)}_{i}\).}\label{fig:cirm_ref_s_n}
\end{figure}

\subsection{Masks Estimations}
In Section~\ref{ssec:cirm},
the \(cIRM\) masks are described in
Equations~\ref{eq:cirmr_mask},~\ref{eq:cirmi_mask}.
In contrast to the \(IRM\) masks which are bounded in the range \([0, 1]\),
the \(cIRM\) masks are unbounded, and have the range \((-\infty, \infty)\).

A neural network cannot train for unbounded values.
Hence, an alternative presentation to the mask values is needed.
One possibility is to compress the real and imaginary masks
with a hyperbolic tangent as suggested in \cite{7364200}:
\begin{align}\label{eq:cirm_compress}
    cIRM_{x} &= K \frac{1-e^{-C\cdot M_{x}}}{1+e^{-C\cdot M_{x}}}
\end{align}
Where \(x\) stands for the real or the imaginary parts of the mask.
By applying this compression, the mask values are bounded in
the range \([-K, K]\), while \(C\) controls the steepness.
For that purpose, we replaced the
simpler IRM DNN sigmoid layers placed at the output
with linear layers.

Then, the cost function is defined to include both real and imaginary parts
of both the noise and speech masks.
\begin{align}
    \ell(\mathbf{\widehat{M}}^{(x)}_{j\omega, t},\;\mathbf{M}^{(x)}_{j\omega, t}) & =
        \frac{1}{2N}\sum_{j\omega, t}
        \left[
            \beta\!\left(
                \mathbf{\widehat{M}}^{(s \in \mathbb{C})}_{j\omega, t} -
                \mathbf{M}^{(s \in \mathbb{C})}_{j\omega, t}
            \right)^{2}
            + \left( 1- \beta \right)\!
            \left(
                \mathbf{\widehat{M}}^{(n \in \mathbb{C})}_{j\omega, t} -
                \mathbf{M}^{(n \in \mathbb{C})}_{j\omega, t}
            \right)^{2}
        \right]
\end{align}

The proposed cIRM estimation network blocks
diagram is shown in Figure\;\ref{fig:cirm_nn}.

\begin{figure}[H]
    \centering
    \includegraphics[width=0.75\linewidth]{Beamformers/images/cirm_nn}
    \caption{Proposed DNN for cIRM T-F masking estimations}\label{fig:cirm_nn}
\end{figure}

\begin{figure}[H]
    \centering
    \subfloat[\label{mel_fb_ref}]{%
       \includegraphics[width=0.45\linewidth]{Beamformers/images/cirm_r_s_ref}}
    \hspace{0.1cm}
    \subfloat[\label{mel_fbfcc_ref}]{%
        \includegraphics[width=0.444\linewidth]{Beamformers/images/cirm_r_s_nn}}
    \caption{(a) Reference cIRM
        real speech mask \(\mathbf{M}^{(s)}_{r}\);\;\;
        (b) The estimated cIRM
        real speech \(\mathbf{\widehat{M}}^{(s)}_{r}\).}\label{fig:cirm_nn_vs_ref}
\end{figure}

Figure\;\ref{fig:cirm_nn_vs_ref} shows the reference real speech cIRM mask
compared to the estimated real speech mask predicted by the DNN model.
Looking at the figure, one can conclude that the model generalized correctly
as the estimated mask resembles the reference to a great extent.
Compared to the ``IRM'' DNN performance, the cIRM model
with a compression in the range of \([-10, 10]\) performs better.

\subsection{Measurements}
Due to the complexity of the cIRM DNN model,
it did not generalize properly for the evaluation dataset
with a number of epochs settings set to 50.
The results hence, are not accurate as a reference nor for comparison,
unless a retraining process is initialized with a sufficient number of epochs
to let the model generalize.

Due to the uncertainty of the impact the low number of epochs have
on the model performance, and the lack of time for a re-evaluation of the
DNN mask estimation, we decide to skip the results and
to drop the cIRM measurements.

% \begin{figure}[H]
%     \centering
%     \includegraphics[width=\linewidth]{Experiments/images/irm_pesq_mosq}
%     \caption{IRM beamformer PESQ vs. MOSLQ}\label{fig:irm_pesq_mosq}
% \end{figure}

\section{PSM --- Phase Sensitive Mask}
The PSM T-F masking makes use of the magnitude ratios and phase differences
rather than requiring a complex multiplication.
In that way, the multiplication is taken in the real domain only,
while utilizing the phase contribution directly.

\begin{figure}[H]
    \centering
    \includegraphics[width=\linewidth]{Features/images/psm_mask}
    \caption{PSM Speech Mask \(\mathbf{M}_{s}(j\omega, t)\)}\label{fig:psm_mask}
\end{figure}
\vspace{-0.5cm}
\begin{figure}[H]
    \centering
    \includegraphics[width=\linewidth]{Features/images/psm_mask_noise}
    \caption{PSM Noise Mask \(\mathbf{M}_{n}(j\omega, t)\)}\label{fig:psm_mask_noise}
\end{figure}
The following equations give the PSM masks for the reference speech and noise,
\(\mathbf{M}^{(s)}_{j\omega, t}\) and \(\mathbf{M}^{(n)}_{j\omega, t}\):
\begin{align}
    \mathbf{M}^{(s)}_{j\omega, t} & = \frac{|\mathbf{S}(t,j\omega)|}{|\mathbf{Y}(t,j\omega)|} \cos(\bm{\theta}_{_{\mathbf{S}}} - \bm{\theta}_{_{\mathbf{Y}}}) \\
    \mathbf{M}^{(n)}_{j\omega, t} & = \frac{|\mathbf{N}(t,j\omega)|}{|\mathbf{Y}(t,j\omega)|} \cos(\bm{\theta}_{_{\mathbf{N}}} - \bm{\theta}_{_{\mathbf{Y}}})
\end{align}

\subsection{Masks Estimations}
Unlike the cIRM complex masks, the PSM masks are real valued.
However, the masks are not bounded similarly to the cIRM masks.
Therefore, the proposed model for the cIRM masks can be reused
with a slight difference in implementation.
Now, only two outputs are created
instead of branching to four outputs at the final layer.
One output for the speech mask and the other for the noise mask.
The same as we did for the ``IRM'' but without the Sigmoids.
In addition, to deal with the unbounded range of values,
we also apply apply a compression algorithm to the reference masks as well.
The compression mechanism is the same as
described in Equation\;\ref{eq:cirm_compress}.

Following this architecture, the cost function can be set
to take two masks in the calculation of the error term,
like with the ``IRM'' masks:
\begin{align}\label{eq:psm_costf}
    \ell(\mathbf{\widehat{M}}_{j\omega, t},\;\mathbf{M}_{j\omega, t}) & =
        \frac{1}{2N}\sum_{j\omega, t}
        \left[
            \beta\!\left(
                \mathbf{\widehat{M}}^{(s)}_{j\omega, t} -
                \mathbf{M}^{(s)}_{j\omega, t}
            \right)^{2}
            + \left( 1- \beta \right)\!
            \left(
                \mathbf{\widehat{M}}^{(n)}_{j\omega, t} -
                \mathbf{M}^{(n)}_{j\omega, t}
            \right)^{2}
        \right]
\end{align}

The proposed PSM estimation network blocks diagram is shown in
Figure\;\ref{fig:psm_nn}.

\begin{figure}[H]
    \centering
    \includegraphics[width=0.75\linewidth]{Beamformers/images/psm_nn}
    \caption{Proposed DNN for PSM T-F masking estimations.}\label{fig:psm_nn}
\end{figure}

\subsection{Measurements}
\begin{figure}[H]
    \centering
    \includegraphics[width=\linewidth]{Features/images/psm_snr_stoi}
    \caption{PSM beamformer SNR vs. Segmental-SNR vs. STOI vs. SI-SNR.}\label{fig:psm_snr_stoi}
\end{figure}

\begin{figure}[H]
    \centering
    \includegraphics[width=\linewidth]{Features/images/psm_ideal_snr}
    \caption{Ideal PSM beamformer enhancement SNR \& Segmental-SNR.}\label{fig:psm_ideal_snr}
\end{figure}

\section{ORM --- Optimal Ratio Mask}
The realization of the phase component importance along with
the desire to keep the masking as simple as possible in terms of number
of matrices and the simplicity of multiplication for separation,
the IRM masking is further developed.

Trying to minimize the general MSE loss function for T-F masking,
same as with the ``Weiner filter'' that the IRM masking approximates, we get:
\begin{align}
    \mathbf{M}^{(s)}_{j\omega, t} & = \frac{
        |\mathbf{S}(t,j\omega)|^{2}
        + \mathfrak{R}_{e}\{ \mathbf{S}(t,j\omega) \cdot {\mathbf{N}}^{*}(t,j\omega) \}
        }{
            |\mathbf{S}(t,j\omega)|^{2}
            + |\mathbf{N}(t,j\omega)|^{2}
            + 2 \mathfrak{R}_{e}\{ \mathbf{S}(t,j\omega) \cdot {\mathbf{N}}^{*}(t,j\omega) \}
        } \\
    \mathbf{M}^{(n)}_{j\omega, t} & = \frac{
        |\mathbf{N}(t,j\omega)|^{2}
        + \mathfrak{R}_{e}\{ \mathbf{N}(t,j\omega) \cdot {\mathbf{S}}^{*}(t,j\omega) \}
        }{
            |\mathbf{S}(t,j\omega)|^{2}
            + |\mathbf{N}(t,j\omega)|^{2}
            + 2 \mathfrak{R}_{e}\{ \mathbf{N}(t,j\omega) \cdot {\mathbf{S}}^{*}(t,j\omega) \}
        }
\end{align}

Looking at the equation above,
it resembles the IRM form but also introduces
the real part of the multiplication between the speech spectrum
and the conjugate noise spectrum.

\subsection{Masks Estimations}
The ORM masking in terms of the estimation process resembles the
PSM completely. Therefore, the same compression and
DNN architecture are used to estimate the ORM masks.

The proposed DNN model blocks diagram is shown in Figure\;\ref{fig:psm_nn},
and the cost function is given in Equation\;\ref{eq:psm_costf}.

\subsection{Measurements}

\begin{figure}[H]
    \centering
    \includegraphics[width=\linewidth]{Features/images/orm_snr_stoi}
    \caption{ORM beamformer SNR vs. Segmental-SNR vs. STOI vs. SI-SNR.}\label{fig:orm_snr_stoi}
\end{figure}

\begin{figure}[H]
    \centering
    \includegraphics[width=\linewidth]{Features/images/orm_ideal_snr}
    \caption{Ideal ORM beamformer enhancement SNR \& Segmental-SNR.}\label{fig:orm_ideal_snr}
\end{figure}

% \section{Masks Estimations}
% \subsection{IRM}

% \begin{align}
%     \ell(\mathbf{\widehat{M}}_{j\omega, t},\;\mathbf{M}_{j\omega, t}) & =
%         \frac{1}{2N}\sum_{j\omega, t}
%         \left[
%             \beta\!\left(
%                 \mathbf{\widehat{M}}^{(s)}_{j\omega, t} -
%                 \mathbf{M}^{(s)}_{j\omega, t}
%             \right)^{2}
%             + \left( 1- \beta \right)\!
%             \left(
%                 \mathbf{\widehat{M}}^{(n)}_{j\omega, t} -
%                 \mathbf{M}^{(n)}_{j\omega, t}
%             \right)^{2}
%         \right]
% \end{align}

% \begin{figure}[H]
%     \centering
%     \includegraphics[width=0.75\linewidth]{Beamformers/images/irm_nn}
%     \caption{Proposed DNN for IRM T-F masking estimations}\label{fig:irm_nn}
% \end{figure}

% \subsection{cIRM}
% In Section~\ref{ssec:cirm},
% the \(cIRM\) masks are described in
% Equations~\ref{eq:cirmr_mask},~\ref{eq:cirmi_mask}.
% In contrast to the \(IRM\) masks which are bounded in the range \([0, 1]\),
% the \(cIRM\) masks are unbounded, and have the range \((-\infty, \infty)\).

% A neural network cannot train for unbounded values.
% Hence, an alternative presentation to the mask values is needed.
% One possibility is to compress the real and imaginary masks
% with a hyperbolic tangent as suggested in \cite{}:
% \begin{align}
%     cIRM_{x} &= K \frac{1-e^{-C\cdot M_{x}}}{1+e^{-C\cdot M_{x}}}
% \end{align}

% Where \(x\), stands for the real or the imaginary parts of the mask.
% By applying this compression, the mask values are bounded in
% the range \([-K, K]\), while \(C\) controls the steepness.
% In that way, a linear layer at the output is placed
% in favor of the sigmoid layers used in the simpler IRM DNN.

% Then, the cost function is defined to include both real and imaginary parts
% of both the noise and speech masks.
% \begin{align}
%     \ell(\mathbf{\widehat{M}}^{(x)}_{j\omega, t},\;\mathbf{M}^{(x)}_{j\omega, t}) & =
%         \frac{1}{2N}\sum_{j\omega, t}
%         \left[
%             \beta\!\left(
%                 \mathbf{\widehat{M}}^{(s \in \mathbb{C})}_{j\omega, t} -
%                 \mathbf{M}^{(s \in \mathbb{C})}_{j\omega, t}
%             \right)^{2}
%             + \left( 1- \beta \right)\!
%             \left(
%                 \mathbf{\widehat{M}}^{(n \in \mathbb{C})}_{j\omega, t} -
%                 \mathbf{M}^{(n \in \mathbb{C})}_{j\omega, t}
%             \right)^{2}
%         \right]
% \end{align}

% \begin{figure}[H]
%     \centering
%     \includegraphics[width=0.75\linewidth]{Beamformers/images/cirm_nn}
%     \caption{Proposed DNN for cIRM T-F masking estimations}\label{fig:cirm_nn}
% \end{figure}

% \subsection{PSM}

% \subsection{ORM}

\section{Conclusions}
In Table\;\ref{tbl:masks_l_params} are presented
the model's sizes in terms of memory requirement
and the number of learnable parameters.
The model's parameters were quantized
to the form of signed 16 bits.
The MSB (most significant bit) is for the sign,
the following four bits are set for the integer part,
and the other eleven bits present the fractional part.
All of the tested models were trained with and without
the \(\Delta, \Delta\Delta\) features.
Usage of the additional \(\Delta, \Delta\Delta\) features
enlarges the input size of the model and thus
leading to a larger number of learnable parameters, resulting
in a bigger model. Bigger models take a longer time to train
and are more complex to fit in limited resources hardware
devices. A trade-off decision can be made with respect to
the memory size and desired performance in the design phase
of T-F masks based applications. Although presenting
better results in audio metrics, the PSM and ORM
masks require \(\sim 43\%\) larger memory space
compared to the IRM masks,
when the feature set does not include
the \(\Delta, \Delta\Delta\) features.
A less severe increase of \(\sim 22\%\) in memory
size requirement has been observed
when the \(\Delta, \Delta\Delta\) features
were not excluded from the feature set.

\begin{table}[H]
    % for more info see: https://www.overleaf.com/learn/latex/tables
    \centering
    % \hspace*{-2.8cm}
    \arrayrulecolor{mtblborder}
\begin{tabular}{ !{\color{mtblborder}\vrule}c!{\color{mtblborder}\vrule}cc|||cc| }
    \hline

    \hline
    \rowcolor{mtblcaption}
    & \multicolumn{2}{c}{\color{white}\bf{Learnable Parameters} [Mil]}
    & \multicolumn{2}{c}{\color{white}\bf{Quant. (S16.11) Mem } [Mb]}\\
    % \cline{2-8}

    \multirow{-2}{*}{\cellcolor{mtblcaption}\color{white}\bf{Targets} }
    & \cellcolor{mtbl} \color{black}{W/o (\(\Delta\),\(\Delta\Delta\))}
    & \cellcolor{mtbl} \color{black}{W/ (\(\Delta\),\(\Delta\Delta\))}
    & \cellcolor{mtbl} \color{black}{W/o (\(\Delta\),\(\Delta\Delta\))}
    & \cellcolor{mtbl} \color{black}{W/ (\(\Delta\),\(\Delta\Delta\))} \\
    % & \color{white}\bf{ORM}
    % & \color{white}\bf{Clean} \\
    \hline

    \hline
    \rowcolor{mtblA} IRM
        & 2.44
        & 4.67
        & 39.0
        & 74.8 \\
    \hline

    \hline
    \rowcolor{mtbl} cIRM
        & 3.76
        & 5.99
        & 60.1
        & 95.9 \\
    \hline

    \hline
    \rowcolor{mtblA} PSM
        & 3.49
        & 5.73
        & 55.9
        & 91.7 \\
    \hline

    \hline
    \rowcolor{mtbl} ORM
        & 3.50
        & 5.74
        & 56.0
        & 91.8 \\
    \hline

    \hline
\end{tabular}
\arrayrulecolor{black}
\caption{T-F Masks models learnable parameters vs. Required memory size}
\label{tbl:masks_l_params}
\end{table}


%!TEX root = /home/renaud/Documents/EPL/tfe/latex/tfe.tex
\addcontentsline{toc}{chapter}{Introduction}
\chapter*{Introduction}
The understanding of geophysical and environmental fluid flows has shown an increasing interest over the past decades. Climate change, and the related issue of pollution have raised the need for accurate simulations allowing to understand and predict the time-space evolution of the concentration of pollutants in the environment. In this regard, the fate of constituents dissolved in a fluid mixture is commonly modelled by means of reactive-transport equations. Those are coupled partial differential equations taking into account the influence of \textit{reactions} as well as of the advective and diffusive \textit{transport phenomena} on the concentration of the constituent in the mixture. Accurate algorithms have been developed by engineers to numerically solve such equations. Finite differences, finite volume and finite elements methods are amongst the most commonly used discretization methods. However, they rely on grids containing thousands and in some instances millions of grid points so that CPU time can become prohibitive in cases where long time simulations are needed. Furthermore, although those methods provide pretty accurate results, these often suffer from a lack of \textit{interpretation}. This raises the need for simpler models with a few number of variables that would allow for an easier interpretation of the results as well as for fast long time simulations. Obviously, one cannot expect such models to provide results that would be as accurate as the ones furnished by the previously mentioned methods. Hence, both approaches are complementary.

One way to build such coarser models is to partition the domain of interest into a relatively small number of subdomains, called \textit{compartments} or \textit{boxes} over which the state variables are assumed \textit{homogeneous}. The fluxes between the compartments are then expressed by simple laws, leading to models that are relatively easy to interpret. This procedure leads to models called \textit{compartment models} or equivalently \textit{box models}. The number of subdomains and their shapes vary widely from one problem to another. Some schematic representations of compartment models found in the literature are shown in figure~\ref{fig:intro:boxmodels}.

Box models have been widely used in studies involving marine systems as well at local scale \cite{deleersnijder1998two,maderich2014regional,soetaert1995estimating} as at global scale \cite{kohler2005quantitative,munhoven1996glacial}. The choice of the subdomains and the specification of the fluxes exchanged between them rely on ad-hoc or empirical methods, based on the known hydrodynamics over the domain considered. It seems that no automatic procedure exists to define a relevant partitioning of the domain. The goal of this work is thus to fill that gap by proposing a method based on the tools of \textit{network science} to automatically delineate relevant compartments.

Network science may be defined as the study of graphs (or networks) and their use to model various (real-life or not) problems. Informally, a graph is a mathematical representation of a set of objects (the \textit{nodes} or \textit{vertices} of the graph), and the links between pairs of them (the \textit{edges} of the graph). The field of application of network science is extremely large, as illustrated by this quote from Newman \cite{newman2010networks}: "\textit{Many objects of interest in the physical, biological, and social sciences can be thought of as networks and [...] thinking of them in this way can often lead to new and useful insights}."

Often, graphs exhibit a \textit{community structure}: it is the case if the vertices can be organized into groups such that there are many interactions between the nodes within a group, and few interaction between the nodes of different groups. Such groups of vertices are called \textit{communities} or \textit{clusters}. An example of a three communities partitioning of a simple graph is shown in figure~\ref{fiug:intro:communities}. The art of revealing the community structure of a graph has a long history in network science, and a variety of \textit{community detection algorithms} and \textit{heuristics} has been developed, see \cite{fortunato2010community} for a 2010 survey. Clustering methods have shown to be useful for a wide applications such as social and biological networks \cite{girvan2002community}, biochemical networks \cite{holme2003subnetwork,guimera2005functional,palla2005uncovering}, or informations networks such as the world wide web \cite{flake2002self}. What makes communities particularly appealing is that they often correspond to \textit{functional units} such as cycles or pathways in metabolic networks \cite{guimera2005functional,palla2005uncovering,huss2007currency} or collections of pages on a single topic on the web \cite{flake2002self}. In the context of geophysical modeling, clustering methods have been used in works providing suggestions for the optimal placement of marine protected areas \cite{thomas2014numerical,jacobi2012identification,rossi2014hydrodynamic}. In this work, we aim to show that communities may correspond to relevant compartments in the case of advection-diffusion flow networks. To this end, we focus on one relatively recent method for community detection based on the \textit{stability} measure \cite{delvenne2010stability,delvenne2013stability,lambiotte2009laplacian}.

A complete procedure is proposed to build a compartment model from any problem whose velocity field and diffusivity tensor are known. First, the Lagrangian equations describing individual particles trajectories are derived from the transport model, and consistent numerical methods are proposed. This allows to compute the transition probability matrix at the desired times, which is the information needed to apply the stability clustering method. Finally, subdomains are delineated from the communities found by the clustering algorithm, and the exchange coefficients between the compartments are estimated numerically, completing the construction of the box model. This approach may be viewed	as a special application of the theory of model order reduction~\cite{deleersnijder2009reduction}. The whole procedure is applied on a simple, two dimensional test problem, and the resulting box model is assessed.

The first part of the work gathers all the theoretical tools needed for that procedure. Chapter~\ref{chap:clustering} is devoted to community detection and in particular to the \textit{stability} measure and the related clustering algorithm. The reactive transport equation and the study of its properties is the topic of chapter~\ref{chap:transportmodel}, whereas compartment models and their properties are studied in chapter~\ref{chap:compartment}. Then, the link between the transport model and the Lagrangian equations describing the position of an individual particle is shown in chapter~\ref{chap:numerical}, leading to the theory of stochastic differential equations and of the consistent numerical methods to solve them. The second part of this work consists in applying the procedure on a simple problem. An idealized, two-dimensional overturning circulation model is presented in~\ref{chap:overturnercirculation} and is then used the build the test problem in chapter~\ref{chap:bioverturner}. The complete procedure is applied on that test problem and assessed in the same chapter.

\begin{figure}[!htp]
	\begin{subfigure}[t]{.47\linewidth}
		\centering
		\includegraphics[width=\textwidth]{fig/intro/boxmodel_KohlerEtAl.png}
		\caption{Geometry of the box model of the isotopic carbon cycle (BICYCLE), where the arrows represent carbon fluxes between the compartments. This is figure 1 of \cite{kohler2005quantitative}.}
	\end{subfigure}
		\begin{subfigure}[t]{.51\linewidth}
		\centering
		\includegraphics[width=\textwidth]{fig/intro/boxmodel_SoetaertHerman.png}
		\caption{Representation of a subdomain decomposition of the Westerschelde. This is figure 1 of \cite{soetaert1995estimating}.}
	\end{subfigure}
	\begin{subfigure}[b]{\linewidth}
		\centering
		\includegraphics[width=\textwidth]{fig/intro/boxmodel_Munhoven.png}
		\caption{Geometry and water fluxes of a compartmental model for the World Ocean. The fluxes are expressed in sverdrups ($1$ Sv = $10^6$ $\rm{m^3/s}$). This is figure 3 of \cite{munhoven1996glacial}.}
	\end{subfigure}%
\caption{Schematic representations of different compartment models.}\label{fig:intro:boxmodels}
\end{figure}
\begin{figure}[!htp]
	\centering
	\includegraphics[width=.4\textwidth]{fig/intro/communities_example.png}
	\caption{Example of a three-communities partitioning on a simple network.} \label{fiug:intro:communities}
\end{figure}


\chapter{Conclusion}\label{chapter:conclusion} \label{ch:conclusions}
Using the setup of the DySpan Spectrum Challenge 2017, the identified need was to determine the transmission fashion that the \ac{PU} has, which switched randomly between ten different scenarios, each one with different characteristics. Although it represents a complex exercise to try to describe this behavior analyticallly, it was observed that each scenario had a clear pattern, and that this pattern could be recorded for further analysis, making this a suitable situation in which machine learning techniques could be applied, and it is shown in this work that these methods provide a satisfactory performance on providing spectrum awareness for interweave systems.

Two main learning techniques are proposed:

\begin{itemize}
    \item feature-based learning using K-nearest neighbors, decision trees and support vector machines classifiers
    \item spectrogram-based learning using convolutional neural networks and different optimizers such as stochastic gradient descent, adamax and adadelta.
\end{itemize}

The feature-based classifiers have a satisfactory performance, reaching up to 95\% of accuracy and representing an improvement over the implementation used in the DySpan Spectrum Challenge in the way that a comparable accuracy is obtained for high SNR values without having to describe the PU procedure analytically . However, they have the inherent limitation from the energy detection based feature extraction, which only allows these classifiers to make decisions in the presence of relatively high (>5dB) PU SNR. Additionally, it is seen that there is still a high correlation between the features for scenario 5 and scenario 9 (scenarios with full bandwidth occupation and same average interframe delay, varying solely in their interframe delay distribution: deterministic for the former, Poisson for the latter). This leads to misclassification even on situations where the \ac{PU} \ac{SNR} is high. This is an invitation to invest further effort on identifying a feature that separates these two scenarios with a higher confidence. Apart from this drawback, for situations where the \ac{PU} power is relatively high, very simple classifiers can be implemented with very small datasets and surprisingly low training and prediction times. K-nearest neighbors and decision trees are recommended for such situations, providing an accuracy up to 98\% with solely the equivalent of 2.5 minutes of recorded data, being able to generate a prediction in less than 200ms and 2ms respectively. Support vector machines, in the configuration that was analyzed in this work, are noticeable worse performing, taking several times longer to train and to predict. Furthermore, they are sensitive to scaling, which represents an additional step in data preprocessing, and therefore are less recommended for this specific use-case.

Spectrograms classifiers require a longer time to train than the feature-based classifiers. Nevertheless, using techniques as the model checkpoint, reliable models such as the Sequential model using Adadelta optimizer could be generated with a training as short as 297 iterations. In the consumer, off-the-shelf, laptop on which this model was trained, this represents a training as short as 30 minutes, being outstandingly accessible for fast implementations  providing superior results. For deep learning approaches, this sequential model with an Adadelta optimizer is recommended.
Furthermore, the need for dedicated hardware for image classification is gradually decreasing with the expanding number of cloud services for this type of procedures. Being able to use dedicated remote hardware could lead to a fast generation of convolutional networks which could potentiate experimentation and research.

As product of this work a reproducible testbed is generated, which serves as a kick-off point for fast experimentation using learning techniques in real communications systems. There are several other machine learning algorithms that are yet to be implemented, analyzed and benchmarked, for which this work serves as a reliable comparison framework. Moreover, although the recording of raw I/Q samples for this work required up to 300GB of hard disk space, the number of samples after preprocessing (around 80.000 features/label pairs and around 85.000 images for classification) are still considered a small dataset. With an improved file management, analysis of these training techniques with a bigger dataset is of special interest for future work. Besides, this work focused on keeping the configuration as loyal to the Spectrum Challenge as possible. However, a careful reduction of the sampling rate should not lead to any functionality difference, leading to less hard disk space needs and, consequently, allowing longer observations.

Also, the approach for the \ac{PU} measurements was based on fixed recording times which for the feature generation process leads to a different amount of samples depending on the scenario. Different approaches to achieve bigger datasets, such as counting generated features at the recording system might be worth further investigation.

Lastly, although satisfactory results are achieved on spectrum awareness, being able to confidently identify the way the \ac{PU} is accessing to the spectrum, it is paramount to extend the functionality of this awareness to the situation in which the \ac{SU} is able to effectively use the time and frequency slots available without interfering the ongoing communication link. Enhancing the results captured in this work to an adaption mechanism in which effective access to the spectrum is granted to the \ac{SU} transmitter would be a valuable step forward in the real implementation of interweave systems.


\chapter{Processor Features}

\section{Introduction}
The Zyelios CPU is a virtual processor. It was created so the Wiremod players could include it in their contraptions, automating their contraptions and learning the basics of low-level programming, assembly programming and, with introduction of the HL-ZASM compiler, C programming.

This processor is very similar to the kind of processors all modern complex devices use. Its closest real-world analog is the \texttt{x86} architecture, but it has several major distinctions, the most of which is the use of floating-point numbers instead of integers.

It should be noted that the processor is a complex machine, and just like a real vehicle it will require some practice to master. It should be understood, however, that despite large number of possible uses of the processor it's based on a very simple set of logic rules. Only the complex combination of these basic logic rules creates all the behaviour of the processor.

This handbook should serve as a concise documentation that covers all of the ZCPU features and quirks you might encounter during your programming. Just like a car manual for a real car, this book covers all of the controls and features of the ZCPU. This handbook assumes the reader has some basic knowledge of real-world processors. %If you feel that you don't know enough about the processors, see page \pageref{processorinfo} for more information.

\section{Theory}
The processor was invented as a logical step up from basic analog computers. First processors were tasked with solving mathematical equations, performing simulations, and processing large arrays of statistic data.

The program that the processor must execute is split into instructions. Each instruction is a simple operation, which somehow alters processor state, or state of any external devices. For example:
\begin{verbatim}
MOV R0,100 //Move 100 to R0
ADD R0,R1 //Add R0 with R1
\end{verbatim}

The extra parameters specified by a programmer to alter the execution of a specific instruction by the processor are called \emph{operands}. All the instructions in ZCPU have zero, one or two operands. The first operand is usually the \emph{destanation} operand, and the second one is the \emph{source} operand.

If there is some result after execution the instruction, it is written to the first operand:
\begin{verbatim}
ADD R0,200; //R0 = R0 + 200
\end{verbatim}

A \emph{register} is a variable inside the processor. They are divided into \emph{general purpose} registers and the \emph{special} (internal) registers. Programmer may use general purpose registers as temporary or intermediate storage for any sort of numeric data:
\begin{verbatim}
MOV R6,100;
MOV R7,R6;
\end{verbatim}

The special registers are used to alter the processor execution mode.

The processor may be attached to external devices and external memory via data bus. A \emph{data bus} is a special type of device which allows to connect several other devices together. There are two data buses in ZCPU: the \reg{MemBus} (memory bus), and the \reg{IOBus} (input/output bus). Any memory cell on these buses and in the processors internal memory can be accessed by an \emph{address} - an integer value. There is no principial difference between how the two buses operate, although it is possible to use memory cells located on the \reg{IOBus} in an easy to understand way - by addressing them as ports:
\begin{verbatim}
MOV R0,PORT0 //Read cell 0 via I/O bus
MOV [500],R0 //Write to cell 500 via memory bus
\end{verbatim}

There are several memory models provided by the ZCPU - these specify how much internal memory the ZCPU has (it may either have some memory and ROM, like a microcontroller, or not use any internal memory at all, similarly to common processors).

\section{General Purpose Registers}
There are 40 general purpose registers in the ZCPU. They are divided into the \emph{main} and the \emph{extended} set. The registers from the main set are called \reg{EAX}, \reg{EBX}, \reg{ECX}, \reg{EDX}, \reg{ESI}, \reg{EDI}, \reg{ESP} and \reg{EBP} (named similarly to the x86 architecture registers). The registers from the extended set are called \reg{R0}, \reg{R1}, ..., \reg{R31}.

You can use any of these for any arithmetics purposes (that means they only hold numerical values), apart from the \reg{ESP} register, which is reserved as the stack pointer (see page \pageref{stack} for more information on the processor stack). When programming using C syntax the \reg{EBP} register is also used for storing stack frame pointer, and must not be altered to avoid program crash.

Every register is a single 64-bit floating point value. It can contain any value between $-10^{3000}$ and $10^{3000}$, but the precision in digits is limited to 48 bits. This is a simplification that differs ZCPU from any other real-world processor.

Registers are \emph{a lot faster} than using memory. In the version 10 of the processor 32 more general purpose registers were added to speed up the program execution.

When the CPU is reset, all registers (except for \reg{ESP}) will be set to 0. If the current ZCPU memory model includes RAM space, then \reg{ESP} will be reset to the CPU internal RAM size minus one (e.g. \reg{65535} for 64k memory model).

\section{Execution}
The Zyelios CPU has a special register called the instruction pointer (\reg{IP}). \reg{IP} points to the currently executed instruction and is incremented every time a new instruction is read.

Instructions can be either variable sized or fixed-sized, depending on the local execution mode (see page \pageref{localexec}), so the \reg{IP} may increment in varying steps. It is possible to set \reg{IP} explictly by using any of the branching opcodes (see page \pageref{branching})

The following is the internal execution flow for fetching and executing an instruction:
\begin{enumerate}
	\item Fetch instruction number (so the processor would know what instruction it is going to execute, and how much operands will the instruction have)
	\item If the instruction has operands, then fetch the RM byte (see \reg{rmbyte}). If the instruction has no operands and the next byte is zero it will be skipped (this behaviour assures that the processor is backwards compatible).
	\item Processor decodes instruction number and fetches segment prefix bytes (if required, this provides support for segment prefixes. See page \pageref{instructionformat} for more information on the instruction format).
	\item If RM byte requires an immediate value to follow, it will be fetched too.
	\item The processor executes the instruction microcode, which somehow alters the processor state (but does not touch the values which are explictly stated in the operation).
	\item All values that must be written are written back to registers, memory, etc.
\end{enumerate}

For the purpose of optimization, one or more of these steps might be cached by the processor and omitted from actual execution. See page \pageref{caching} for more information on this behaviour.

The processor will run a specific amount of cycles per second. The amount of cycles required for executing each instruction may vary, and it is counted by the \reg{TMR} register. Most instructions are only 1 cycle long, although internal caching or memory access may consume additional cycles.

See page \pageref{advexecution} more information on the execution process.

\section{Interrupts}
When a certain exceptional event occurs (external signal, error in arithmetics, memory error, etc), the ZCPU will generate an interrupt. Interrupts are special events which will temporarily "interrupt" or change flow of the program and branch to execute the appropriate interrupt handler code. This means that whenever the ZCPU encounters an interrupt it will remember its current state, store it on the processor stack (see page \pageref{stack}) and change \reg{IP} to the first opcode of the interrupt handler.

In extended mode the processor stores an interrupt table - a table which holds pointers to all interrupt handlers. If extended mode is not enabled, any interrupts called will stop the processor execution.

After the interrupt handler has finished running, it can restore the ZCPU state and the previously executed code will continue executing from where it was interrupted.

For example, if this was the stack state before an interrupt call, and current value of \reg{IP} is 157:
\begin{verbatim}
..........
65304: ...
65306: 181
65305: -94

ESP = 65304
\end{verbatim}
then the stack state will be altered to this after an interrupt call (and \reg{IP} will be set to interrupt handler entrypoint):
\begin{verbatim}
..........
65304: ...
65306: 181
65305: -94
65304: 0   CS
65303: 157 IP

ESP = 65302
\end{verbatim}

Interrupts are very similar to normal calls (see page \pageref{branching}), but instead of using a memory pointer an interrupt number is given. Also unlike the regular calls a special return instruction \reg{IRET} must be used in place of \reg{RET}. Any interrupt can be called using the \reg{INT} instruction. For example:
\begin{verbatim}
interrupt_handler:
  ....
iret;
\end{verbatim}

There are two types of interrupts: internal interrupts, and external interrupts. The external interrupts will push the entire ZCPU state (along with the return data internal interrupt would push) to stack before entering the interrupt handler. They can only be triggered via external interrupt pin, or by using the \reg{EXTINT} instruction. The external interrupts require \reg{EXTRET} instruction instead of the \reg{IRET} to restore the processor state.

There are several static interrupts. These interrupts are executed when certain exceptional conditions happen internally. All interrupt numbers less than 32 are reserved by the processor. In addition, interrupts 0 and 1 have special meanings and are handled internally. The user program can only use the interrupts 32..255. See page \pageref{errorcodes} for more information on the error interrupts.

The following table describes all of the reserved interrupt numbers:

\singlespacing
\begin{longtable}{|c|p{3.5in}|} \hline
Number & Description \\ \hline
0 & \emph{Reset} \\ \hline
1 & \emph{Halt} \\ \hline
2 & End of program execution \\ \hline
3 & Division by zero \\ \hline
4 & Unknown opcode \\ \hline
5 & Internal processor error \\ \hline
6 & Stack error (overflow/underflow) \\ \hline
7 & Memory read/write fault \\ \hline
8 & MemBus fault \\ \hline
9 & Write access violation (page protection) \\ \hline
10 & Port read/write fault \\ \hline
11 & Page acccess violation (page protection) \\ \hline
12 & Read access violation (page protection) \\ \hline
13 & General processor fault \\ \hline
14 & Execute access violation (page protection) \\ \hline
15 & Address space violation \\ \hline
17 & Frame instruction limit (\emph{GPU only}) \\ \hline
23 & String read error (\emph{GPU only}) \\ \hline
28 & \emph{Page read access trap} \\ \hline
29 & \emph{Page write access trap} \\ \hline
30 & \emph{Page access trap} \\ \hline
31 & \emph{Debug trap} \\ \hline
\end{longtable}
\onehalfspacing

The reset interrupt (0) will reset the processor state, and restart code execution from the top of memory. The halt interrupt (1) will stop execution until the processor is reset externally. The \texttt{int 1} and \texttt{int 0} instructions will work as long as the interrupts are not handled by the software (as long as they are disabled in the interrupt table, or interrupt table is not used):
\begin{verbatim}
 INT 1; //Stop execution

 INT 0; //Reset the processor
\end{verbatim}

If extended mode is not enabled, \emph{all the interrupts} will work similarly to the halt interrupt (\texttt{int 1}) when triggered. The error code will be set on the error output.

Interrupt handling can be disabled using the \reg{IF} flag. It is not directly writeable, but it can be changed using the special instructions. \emph{When setting the flag, the value will only become updated after the next instruction}. For example:

\begin{verbatim}
STI;         //Set interrupt flag
MOV EAX,123; //IF = 0
ADD EAX,123; //IF = 1 (flag updated)
CLI;         //Clear interrupt flag
SUB EAX,123; //IF = 0 (flag clear on this instruction)
RET;         //IF = 0
\end{verbatim}

This assures that for example in this situation the interrupt will not occur between the \texttt{RET} and the \texttt{STI}:

\begin{verbatim}
ContextSwitch:
  CLI;

  ... thread switcher code ...

  STI;  //An interrupt will never occur between this
EXTRET; //STI instruction and the NMIRET
\end{verbatim}

For information on using the interrupt table, consult the advanced interrupts chapter (see page \pageref{advancedinterrupts}).

\section{Memory Segmenting and Segment Registers} \label{segments}
There are 8 segment registers in the ZCPU. They are \reg{CS}, \reg{SS}, \reg{DS}, \reg{ES}, \reg{GS}, \reg{FS}, \reg{KS} and \reg{LS}. They are used by the ZCPU to support certain memory models. Additionally any of the 40 general purpose registers can be used as segment registers.

Every segment register can contain a 48-bit integer. This value can be used for specifying an offset for a pointer to memory. The ZCPU always uses segments when referencing memory: it translates the local address (the memory address explictly written by the user, it's important to remember that any variable or label has a certain memory address) into the absolute address (the physical address, which serves as a command to direct ZCPU towards where the real data is located).

The formula used for the address translation is:
\[AbsoluteAddress = LocalAddress + SegmentOffset\]

The user can specify which register to use for offsets by prefixing the operand with the segment name followed by a semicolon. If a segment is not specified, \reg{DS} is used.

Both segment and general purpose registers can be used for segment prefixing. It is not possible to use a constant value for segment prefix. Here is an example of various ZASM syntax for reading memory:
\begin{verbatim}
MOV EAX,#EBX      //Address: DS+EBX
MOV EAX,ES:#EBX   //Address: ES+EBX
MOV EAX,[EBX]     //Address: DS+EBX
MOV EAX,[ES:EBX]  //Address: ES+EBX
MOV EAX,[ES+EBX]  //Address: ES+EBX

MOV EAX,EBX:ECX   //Address: EBX+ECX
MOV EAX,[EBX+ECX] //Address: EBX+ECX
MOV EAX,[EBX:100] //Address: EBX+100
MOV EAX,[100:EBX] //This is not valid
\end{verbatim}

With some clever programming the segment prefixes can be used for quick array access, typically by using the prefix as the array pointer and the base as the index into the array:
\begin{verbatim}
MOV ES,ArrayStart
MOV EAX,ES:#0 //EAX = 10
MOV EBX,ES:#2 //EBX = 30
MOV ECX,ES:#1 //ECX = 50

MOV EAX,0
MOV EBX,EAX:#ArrayStart //EBX = 10
INC EAX
MOV EBX,EAX:#ArrayStart //EBX = 50
INC EAX
MOV EBX,EAX:#ArrayStart //EBX = 30

ArrayStart: db 10,50,30
\end{verbatim}

Some of the segment registers are used by the processor for specific tasks, as per the following table:

\singlespacing
\begin{longtable}{|c|c|p{3.0in}|} \hline
Register & Name & Description \\ \hline
\texttt{CS} & Code segment    & Processor fetches code from this segment \\ \hline
\texttt{SS} & Data segment    & Default segment for data \\ \hline
\texttt{DS} & Stack segment   & Processor stack is located in this segment \\ \hline
\texttt{ES} & Extra segment   & User segment \\ \hline
\texttt{GS} & G segment       & User segment \\ \hline
\texttt{FS} & F segment       & User segment \\ \hline
\texttt{KS} & Key segment     & User segment \\ \hline
\texttt{LS} & Library segment & User segment \\ \hline
\end{longtable}
\onehalfspacing

All segment registers other than \reg{CS} can be directly set by using the \reg{MOV} operation. The only way to modify the \reg{CS} is to execute \reg{CALLF} or \reg{JMPF} instructions (see page \pageref{branching} for more information):
\begin{verbatim}
//CS = 0
//IP = 928

JMPF 500,100;

//CS = 100
//IP = 500
\end{verbatim}

Attempting to set \reg{CS} directly will trigger interrupt \reg{13:1} (general processor fault). For example:
\begin{verbatim}
MOV DS,100
MOV ES,KS
MOV CS,1000 //Will generate interrupt 13:1
\end{verbatim}

After CPU reset all segment registers will be initialized to \reg{0}.

\section{Memory Models}
The ZCPU is capable of working in several different memory modes. Linear addressing mode is the default mode, and it is the mode in use when the CPU is reset.

Different modes require different use of registers and provide different execution features. Each mode will usually require extended processor mode to be active, enabling some advanced memory protection features such as page permissions and memory mapping.

It is important to be aware of how memory access actually works. When a memory request occurs (read or write) these are the actions that will be undertaken by the CPU:

\begin{enumerate}
	\item Check \texttt{BusLock} register. If this register is set to 1 the request will fail.
	\item Validate the address. The address must be a 48-bit integer value.
	\item Fetch page that corresponds to the requested address.
	\item If \texttt{EF} flag is set check if current runlevel is less or equal to target page runlevel and check if it's possible to read/write on the page.
	\item If page has \texttt{Mapped} flag set then change the address accordingly.
	\item Perform the I/O operation.
\end{enumerate}

\subsection{Linear Address Mode}
This is the default address mode when all segment registers are initialized to \reg{0}. This mode is available after the initial processor startup. Since all registers are set to zero, in this mode the code, data and stack are all located in same address space.

No segment prefixes are required in this mode. For example you can access the processor stack without specifying the \reg{SS} prefix:

\begin{verbatim}
MOV EAX,#0  //EAX will be equal to 14 (MOV opcode no)
MOV #ESP,100 //Same as PUSH 100
DEC ESP
POP EAX     //EAX will be equal to 100
\end{verbatim}

\subsection{Segmented Address Mode}
This is the most common addressing mode when segment registers are used differently. For example, the code, data and stack might all be located in different areas of memory. This has certain benefits:

\begin{itemize}
  \item Allows to prevent accidental data/code corruption
  \item Same code can be used for different blocks of data
  \item Programs can run in local address space, not aware of different programs (for example BIOS)
\end{itemize}

Example:
\begin{verbatim}
MOV DS,1000 //Set first data block
MOV SS,2000 //Set first stack block
CALLF 0,500 //Call the routine (CS will be set to 500, IP to 0)

MOV DS,3000 //Set second data block
MOV SS,4000 //Set second stack block
CALLF 0,500 //Call the same routine, but now
            //working on different data block
\end{verbatim}

This will run the same routine (located at physical offset \reg{500}) on two different sets of data. Thus the same subprogram can be reused for different sets of variables.

\subsection{Mapped Memory Mode}
Mapped memory mode uses the memory mapping features of the processor to reroute memory addresses in order to create the appearance of a single continuous address space for the user program. This mode allows user programs to dynamically allocate blocks of data, which can themselves be physically located in different areas of memory. This also allows use of dynamic libraries, where single library loaded once can be used in many programs while remaining in a single place in physical memory.

See page \pageref{paging} for more information.

\section{Stack} \label{stack}
The Zyelios CPU has a built-in hardware processor stack. Stack operation is controlled by the current stack pointer register (\reg{ESP}), the stack size register (\reg{ESZ}) and the stack segment register (\reg{SS}) Stack data is located in physical RAM.

\reg{ESP} points to the \emph{next free value on the stack}. The stack grows \emph{down}.

\reg{PUSH} and \reg{POP} are used to push or pop values to or from the stack, respectively. Stack overflow or underflow is indicated by the interrupt \reg{6:ESP} (stack error). The interrupt parameter will be set to the value of \reg{ESP}. For example:

\begin{verbatim}
MOV SS,5000   //Stack starts at offset 5000
MOV ESP,2999  //Stack is 3000 bytes in size
              //Next free offset in segment is 2999
CPUSET 9,3000 //Set ESZ register

PUSH 200
PUSH 100
POP EAX //EAX = 100
POP EBX //EBX = 200

//PUSH X is same as the following (but with error checks):
MOV SS:#ESP,X
DEC ESP

//POP Y is same as the following (but with error checks):
INC ESP
MOV Y,SS:#ESP
\end{verbatim}

Additionally, the \reg{RSTACK} and \reg{SSTACK} instructions allow the user to read or write an arbitrary position on the stack. These instructions may also trigger stack underflow or overflow interrupts. The following example illustrates the use of \reg{RSTACK} and \reg{SSTACK}:

\begin{verbatim}
RSTACK X,Y //X = MEMORY[SS+Y]
SSTACK X,Y //MEMORY[SS+X] = Y

RSTACK EAX,ESP:1 //Read stack top
RSTACK EAX,ESP:2 //Read value under stack top

PUSH 100 //
PUSH 200 //Value under top value
PUSH 300 //Value on top

SSTACK ESP:2,123 //Set value under stack top
POP EAX //EAX = 300
POP EBX //EBX = 123
POP ECX //ECX = 100
\end{verbatim}

\section{Branching} \label{branching}
The Zyelios CPU supports various kinds of branching: conditional or unconditional, absolute or relative. The instruction pointer (\reg{IP}) points to the currently executing instruction. All branching instructions modify \reg{IP}; some also modify \reg{CS} (see page \pageref{segments}).

The simpliest type of branching is absolute unconditional. To perform an unconditional jump, \reg{JMP} or \reg{JMPF} are used (the latter also modifies \reg{CS}).

Program subroutines can be called by using \reg{CALL} or \reg{CALLF}. This will save current the instruction pointer (and \reg{CS} when \reg{CALLF} is used) to the processor stack. The instruction pointer (and code segment if required) can be restored from the stack by using \reg{RET} or \reg{RETF} accordingly.

The following example illustrates creating routines and jumping:

\begin{verbatim}
JMPF MAIN,CODE_SEGMENT //Syntax is JMPF IP,CS

......

MAIN: //A label
  CALL SUBROUTINE
  JMP EXIT

SUBROUTINE:
  CALL SUBROUTINE2
RET //Exit subroutine

SUBROUTINE2: //Called inside SUBROUTINE
  ... do something ...
RET
......

EXIT:
\end{verbatim}

It is possible to perform a relative jump. To do this, \reg{JMPR} (jump relative) is used. This instruction adds or subtracts \reg{IP} by a certain amount instead of giving a specific number. For example example:

\begin{verbatim}
JMPR +10 //Jump 10 bytes forward
JMPR -10 //Jump 10 bytes backward

JMPR LABEL-__PTR__ //Jump to label
                   //__PTR__ label always points
                   //to current write pointer

......

LABEL:
\end{verbatim}

Conditional branching allows program flow to be changed depending on certain conditions. \reg{CMP} is used to compare two values, and instructions from the following table react accordingly:

\singlespacing
\begin{longtable}{|c|c|p{3.0in}|} \hline
Instruction & Operation & Description \\ \hline
\texttt{JNE}   & X <> Y     & Jump if not equal \\ \hline
\texttt{JNZ}   & X - Y <> 0 & Jump if not zero \\ \hline
\texttt{JG}    & X > Y      & Jump if greater than \\ \hline
\texttt{JNLE}  & NOT X <= Y & Jump if not less or equal \\ \hline
\texttt{JGE}   & X >= Y     & Jump if greater or equal \\ \hline
\texttt{JNL}   & NOT X < Y  & Jump if not less than\\ \hline
\texttt{JL}    & X < Y      & Jump if less than \\ \hline
\texttt{JNGE}  & NOT X >= Y & Jump if not greater or equal \\ \hline
\texttt{JLE}   & X <= Y     & Jump if less or equal\\ \hline
\texttt{JNG}   & NOT X > Y  & Jump if not greater than \\ \hline
\texttt{JE}    & X = Y      & Jump if equal \\ \hline
\texttt{JZ}    & X - Y = 0  & Jump if zero \\ \hline

\texttt{CNE}   & X <> Y     & Call if not equal \\ \hline
\texttt{CNZ}   & X - Y <> 0 & Call if not zero \\ \hline
\texttt{CG}    & X > Y      & Call if greater than \\ \hline
\texttt{CNLE}  & NOT X <= Y & Call if not less or equal \\ \hline
\texttt{CGE}   & X >= Y     & Call if greater or equal \\ \hline
\texttt{CNL}   & NOT X < Y  & Call if not less than\\ \hline
\texttt{CL}    & X < Y      & Call if less than \\ \hline
\texttt{CNGE}  & NOT X >= Y & Call if not greater or equal \\ \hline
\texttt{CLE}   & X <= Y     & Call if less or equal\\ \hline
\texttt{CNG}   & NOT X > Y  & Call if not greater than \\ \hline
\texttt{CE}    & X = Y      & Call if equal \\ \hline
\texttt{CZ}    & X - Y = 0  & Call if zero \\ \hline

\texttt{JNER}   & X <> Y     & Jump relative if not equal \\ \hline
\texttt{JNZR}   & X - Y <> 0 & Jump relative if not zero \\ \hline
\texttt{JGR}    & X > Y      & Jump relative if greater than \\ \hline
\texttt{JNLER}  & NOT X <= Y & Jump relative if not less or equal \\ \hline
\texttt{JGER}   & X >= Y     & Jump relative if greater or equal \\ \hline
\texttt{JNLR}   & NOT X < Y  & Jump relative if not less than\\ \hline
\texttt{JLR}    & X < Y      & Jump relative if less than \\ \hline
\texttt{JNGER}  & NOT X >= Y & Jump relative if not greater or equal \\ \hline
\texttt{JLER}   & X <= Y     & Jump relative if less or equal\\ \hline
\texttt{JNGR}   & NOT X > Y  & Jump relative if not greater than \\ \hline
\texttt{JER}    & X = Y      & Jump relative if equal \\ \hline
\texttt{JZR}    & X - Y = 0  & Jump relative if zero \\ \hline

\end{longtable}
\onehalfspacing

There are other instruction which perform branch testing, such as \reg{BIT}, which tests specific bits of a given value. For example: \label{branchbit}

\begin{verbatim}
CMP EAX,EBX
JG  LABEL1 //Jump if EAX >  EBX
JLE LABEL2 //Jump if EAX <= EBX
JE  LABEL3 //Jump if EAX  = EBX
CL  LABEL4 //Call if EAX <  EBX
CGE LABEL5 //Call if EAX >= EBX

BIT EAX,4 //Test 5th bit of EAX
JZ  LABEL1 //Jump if 5th bit is 0
JNZ LABEL1 //Jump if 5th bit is 1
\end{verbatim}

\section{Processor Error Codes}\label{errorcodes}
There are several error codes that might be generated during program execution. Each error condition generates an interrupt.

If processor is not in extended mode, code execution will halt when the error is generated. Upon encountering an error, the processor will halt and output the error code to \reg{ERROR} processor output. It will also emit a secondary error code in the fraction part of the \reg{ERROR} processor output. If the processor is in extended mode, the corresponding interrupt will be called instead.

For example, a typical output might be \texttt{7.65536}, which would indicate a memory read/write fault at address 65536.

The error code will be reset to zero when the CPU is reset. The following are error codes are defined by the current version of the processor:

\singlespacing
\begin{longtable}{|c|c|p{3.0in}|} \hline
Code & Description \\ \hline
\texttt{02} & End of program execution \\ \hline
\texttt{03} & Division by zero \\ \hline
\texttt{04} & Unknown opcode \\ \hline
\texttt{05} & Internal processor error \\ \hline
\texttt{06} & Stack error (overflow/underflow) \\ \hline
\texttt{07} & Memory read/write fault \\ \hline
\texttt{08} & MemBus fault \\ \hline
\texttt{09} & Write access violation (page protection) \\ \hline
\texttt{10} & Port read/write fault \\ \hline
\texttt{11} & Page acccess violation (page protection) \\ \hline
\texttt{12} & Read access violation (page protection) \\ \hline
\texttt{13} & General processor fault \\ \hline
\texttt{14} & Execute access violation (page protection) \\ \hline
\texttt{15} & Address space violation \\ \hline

\end{longtable}
\onehalfspacing

\newcommand{\errorentry}[4]{

\textbf{Error message}: #1 \\ \textbf{Occurs when}: #2 \\ \textbf{Cause}: #3 \\ \textbf{Result}: #4

\vspace{0.1in}

}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{End of program execution (02)}
\errorentry{STOP detected}
           {\reg{STOP}/\reg{OPCODE 0} is executed}
           {Abnomal program end}
           {None}
\errorentry{Invalid opcode}
           {Any of the branching instructions is executed (\reg{JMP}, \reg{CALL}, etc)}
           {Jumping by offset that does not point to valid ZCPU instruction}
           {None}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Division By Zero (03)}
\errorentry{Unable to divide by zero}
           {Second operand for \reg{DIV} opcode is zero}
           {User error}
           {\reg{LADD = 1}}
\errorentry{Unable to perform inversion on a zero}
           {Calling \reg{FINV} opcode with zero operand}
           {User error}
           {\reg{LADD = 2}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Unknown Opcode (04)}
\errorentry{Unknown opcode detected in the instruction stream}
           {Next executed instruction is not one of the recognized instructions}
           {Invalid branching operation is performed (processor attempts to execute data)}
           {\reg{LADD = OPCODE NUMBER}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Internal Processor Error (05)}
\errorentry{Unable to execute instruction (microcode error)}
           {An internal error has ocurred while executing microcode}
           {Encountering a bug in processor}
           {\reg{LADD = 01}}
\errorentry{Unknown internal error}
           {Never}
           {None}
           {\reg{LADD = 02}}
\errorentry{Read error while fetching the instruction}
           {Instruction decoder was not able to fetch all of the instruction bytes}
           {\reg{JMP} or \reg{CALL} to a memory location outside of physical/logical range}
           {\reg{LADD = 12}}
\errorentry{Could not fetch an immediate byte for operand 1}
           {Instruction decoder was not able to fetch an immediate byte for the first operand}
           {\reg{JMP} or \reg{CALL} to a memory location outside of physical/logical range}
           {\reg{LADD = 22}}
\errorentry{Could not fetch an immediate byte for operand 2}
           {Instruction decoder was not able to fetch an immediate byte for the second operand}
           {\reg{JMP} or \reg{CALL} to a memory location outside of physical/logical range}
           {\reg{LADD = 32}}
\errorentry{Invalid RM parameter for operand 1}
           {Never}
           {None}
           {\reg{LADD = 42}}
\errorentry{Invalid RM parameter for operand 2}
           {Never}
           {None}
           {\reg{LADD = 52}}
\errorentry{Target operand not writeable}
           {Never}
           {None}
           {\reg{LADD = 62}}
\errorentry{Source operand not writeable (\texttt{XCHG} instruction only)}
           {Never}
           {None}
           {\reg{LADD = 72}}
\errorentry{Unknown opcode}
           {Never}
           {None}
           {\reg{LADD = 82}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Stack Error (06)}
\errorentry{Stack overflow error}
           {\reg{PUSH} is executed}
           {\reg{ESP} register value becomes negative}
           {\reg{LADD = 0}}
\errorentry{Stack underflow error}
           {\reg{POP} is executed}
           {\reg{ESP} register is greater than \reg{ESZ}}
           {\reg{LADD = ESZ}}
\errorentry{Stack read error}
           {\reg{POP} is executed}
           {Unable to read value from memory}
           {\reg{LADD = ESP}}
\errorentry{Stack out of bounds error}
           {\reg{RSTACK} or \reg{SSTACK} is executed}
           {Requested value out of stack bounds}
           {\reg{LADD} equals to requested index on stack}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Memory Read/Write Fault (07)}
\errorentry{Read error: address does not exist}
           {Processor attempts to read a value from outside of the internal RAM}
           {No device is attached to the MemBus}
           {\reg{LADD} equals to faulty address in memory}
\errorentry{Read error: unable to read memory location}
           {Processor attempts to read a value from outside of the internal RAM}
           {A failure has occured while attempting to read a value (value out of the device address range)}
           {\reg{LADD} equals to faulty address in memory}
\errorentry{Write error: address does not exist}
           {Processor attempts to write a value to outside of the internal RAM}
           {No device is attached to the MemBus}
           {\reg{LADD} equals to faulty address in memory}
\errorentry{Write error: unable to write to memory location}
           {Processor attempts to write a value to outside of the internal RAM}
           {A failure has occured while attempting to write a value (value out of the device address range)}
           {\reg{LADD} equals to faulty address in memory}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{MemBus Fault (08)}
\errorentry{MemBus device error}
           {Processor attempts to read a value from outside of the internal RAM}
           {Device currently attached to MemBus does not support hispeed interface}
           {\reg{LADD} equals to faulty address in memory}
\errorentry{IOBus device error}
           {Processor attempts to read a value from a port}
           {Device currently attached to IOBus does not support hispeed interface}
           {\reg{LADD = -PORT\textunderscore NUMBER}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Write Access Violation (09)}
\errorentry{Access violation}
           {Attempting to write a value}
           {\reg{EF} flag set to 1, no write permission on referenced page, and referenced by the address has a smaller runlevel than the current one.}
           {\reg{LADD} equals to faulty address in memory}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Port Read/Write Fault (10)}
\errorentry{Read error: unable to read a port}
           {Processor attempts to read a value from a port}
           {A failure has occured while attempting to read a value (value out of he device address range)}
           {\reg{LADD} equals to faulty address in memory}
\errorentry{Write error: unable to write to a port}
           {Processor attempts to write a value to a port}
           {A failure has occured while attempting to write a value (value out of the device address range)}
           {\reg{LADD} equals to faulty address in memory}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Page acccess violation (11)}
\errorentry{Unable to set page readonly}
           {\reg{SPG} opcode is executed}
           {Current runlevel greater than runlevel of the refernced page}
           {\reg{LADD} points to referenced page}
\errorentry{Unable to set page read- and writeable}
           {\reg{CPG} opcode is executed}
           {Current runlevel greater than runlevel of the refernced page}
           {\reg{LADD} points to referenced page}
\errorentry{Unable to set page flag}
           {\reg{SPP} opcode is executed}
           {Current runlevel greater than runlevel of the refernced page}
           {\reg{LADD} points to referenced page}
\errorentry{Unable to clear page flag}
           {\reg{CPP} opcode is executed}
           {Current runlevel greater than runlevel of the refernced page}
           {\reg{LADD} points to referenced page}
\errorentry{Unable to set page runlevel}
           {\reg{SRL} opcode is executed}
           {Current runlevel greater than runlevel of the refernced page}
           {\reg{LADD} points to referenced page}
\errorentry{Unable to set page mapping}
           {\reg{SMAP} opcode is executed}
           {Current runlevel greater than runlevel of the refernced page}
           {\reg{LADD} points to referenced page}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Read access violation (12)}
\errorentry{Access violation}
           {Attempting to read a value}
           {\reg{EF} flag set to 1, no read permission on referenced page, and referenced by the address has a smaller runlevel than the current one.}
           {\reg{LADD} equals to faulty address in memory}
\errorentry{Referenced page outside ROM}
           {\reg{ERPG} opcode executed}
           {Page referenced by the instruction could not be erased, because it lies outside the processor ROM}
           {\reg{LADD = 0}}
\errorentry{Referenced page outside ROM}
           {\reg{WRPG} opcode executed}
           {Page referenced by the instruction could not be written, because it lies outside the processor ROM}
           {\reg{LADD = 0}}
\errorentry{Referenced page outside ROM}
           {\reg{RDPG} opcode executed}
           {Page referenced by the instruction could not be read, because it lies outside the processor ROM}
           {\reg{LADD = 0}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{General Processor Fault (13)}
\errorentry{Code segment write violation}
           {\reg{CS} value is being used as a target operand}
           {An attempt is being made to set a read-only segment register. Use \texttt{CALLF} or \texttt{JMPF} instructions to modify the CS register}
           {\reg{LADD = 1}}
\errorentry{Unable to read interrupt table}
           {Could not fetch entry from interrupt table}
           {Invalid interrupt table location set with \reg{LIDTR}}
           {\reg{LADD = 2}}
\errorentry{Invalid interrupt number}
           {Interrupt outside of the acceptable boundary (0..255) is called}
           {Misuse of the \reg{INT} or the \reg{EXTINT} instructions}
           {\reg{LADD = 3}}
\errorentry{Unprivileged external interrupt call}
           {External interrupt was called while the appropriate flag was not set in the interrupt table}
           {\reg{6th} bit not set for the external interrupt in the interrupt table, and the external interrupt is called}
           {\reg{LADD = 4}}
\errorentry{Incompatible mode}
           {Interrupt call in protected (compatibility) mode with less than 512 bytes of RAM}
           {Not enough RAM to contain a complete interrupt table}
           {\reg{LADD = 5}}
\errorentry{Unable to push return data}
           {Interrupt handler was unable to push return data onto the processor stack}
           {Interrupt was called with no stack space available}
           {\reg{LADD = 6}}
\errorentry{Unable to call an interrupt}
           {Interrupt is called without sufficient rights}
           {Interrupt is called without sufficient rights to complete the jump}
           {\reg{LADD = 7}}
\errorentry{Unable to read page table}
           {Page table is not located in valid memory range}
           {Page table is not located in valid memory range}
           {\reg{LADD = 8}}
\errorentry{Attempting to execute a privileged instruction}
           {Could not execute a privileged instruction due to runlevel}
           {Calling one of the following instructios without sufficient rights: \reg{RD}, \reg{WD}, \reg{SPG}, \reg{CPG}, \reg{STI}, \reg{CLI}, \reg{STP}, \reg{CLP}, \reg{STEF}, \reg{CLEF}, \reg{EXTINT}, \reg{ERPG}, \reg{WRPG}, \reg{RDPG}, \reg{LIDTR}, \reg{EXTRET}, \reg{IDLE}, \reg{STD2}, \reg{STM}, \reg{CLM}, \reg{CPUGET}, \reg{CPUSET}, \reg{CPP}, \reg{SPP}, \reg{SRL}, \reg{GRL}, \reg{SMAP}, \reg{GMAP}
}
           {\reg{LADD = Opcode number}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Execute Access Violation (14)}
\errorentry{Access violation}
           {Execution is attempted on a memory page that does not allow execution}
           {Invalid branching into the protected memory areas}
           {\reg{LADD = Page number}}
\errorentry{Access violation}
           {Execution is attempted on a memory page that does not allow execution}
           {Code execution has entered page that does not allow execution}
           {\reg{LADD = Page number}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Address space violation (15)}
\errorentry{Address space violation}
           {Memory is accessed by an invalid address}
           {Address is not a 48-bit signed integer}
           {\reg{LADD = Referenced invalid address}}