esds/manual/manual.tex

\documentclass[11pt]{article}

% Packages
\usepackage{fullpage}
\usepackage{minted}
\usepackage{booktabs}
\usepackage{xspace}
\usepackage{hyperref}
\usepackage{graphicx}
\usepackage{makecell}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{svg}
\usepackage[most]{tcolorbox}
\usepackage{adjustbox}

% Packages setups
\graphicspath{{./assets}}

% Commands
\newcommand{\version}{\InputIfFileExists{version}{}{version}}
\newcommand*{\addsource}[2]{\vspace{0.3cm}\begin{tcolorbox}[breakable,enhanced,arc=1.4mm,arc is angular,title=\textbf{\small#1}]\inputminted[breaklines,fontsize=\scriptsize]{#2}{#1}\end{tcolorbox}}
\newenvironment{tabminted}[1]
               {\VerbatimEnvironment\begin{minipage}{3.3in}\begin{tcolorbox}[frame empty]\begin{minted}{#1}}
               {\end{minted}\end{tcolorbox}\end{minipage}}

% Document
\begin{document}

% Title page
\makeatletter
\begin{titlepage}
  \begin{center}
    \Huge
    \textbf{\fontsize{90}{60}\selectfont User Manual\\}
    \vspace{0.6cm}
    \textbf{\LARGE --- ESDS v\version --- \\}
    {\Large \today}
    \vspace{2cm}
    
    {\includesvg[scale=0.8]{../icon.svg}}
    \vspace{1.5cm}
    
    \LARGE
    \textbf{ESDS an Extensible Simulator for Distributed Systems\\}
    \vspace{1cm}
    \textit{Written by Loic Guegan and Issam Raïs}
  \end{center}
\end{titlepage}
\pagebreak

\tableofcontents
\pagebreak

\section{Architecture of ESDS}

\begin{figure}[!h]
\centering
\includegraphics[scale=0.5]{components.pdf}
\caption{Simulation architecture used by ESDS}
\label{architecture}
\end{figure}

The ESDS simulator comprises two major components: 1) The Simulation Orchestrator (SO) 2) The Simulated
Nodes (SN). This architecture is depicted on Figure~\ref{architecture}. The SO is the main process
in charge of implementing the simulation main loop. It instantiates the network (e.g bandwidths and
latencies matrices), collects and processes the events (e.g communications,turn on/off). On the other hand,
the SNs are threads that implement the node behaviors by following so called \textit{node API}.

\section{Getting started}

To run a simulation, at least 2 files are required: 1) a platform file 2) a node implementation
source code. The platform file defines the simulated network platform (network links and
performances etc.)  and sets various simulation parameters. The node implementation source code
provides the logic of the simulated nodes.

\subsection{Platform file}
\label{sec:firstsimulation:platform}

Platform files are written in YAML and contains 3 sections namely: 1) \textit{general} 2)
\textit{nodes} 3) \textit{interfaces}. The \textit{general} section is optional but all the other
sections must be present. Here is an example of a simple platform file to simulate 2 wireless nodes:
\addsource{assets/platform.yaml}{yaml}

\subsection{Node implementation file}

Nodes implementations are written using python. Here is the implementation of the node mentioned in
the last \verb|platform.yaml| file:
\addsource{assets/node.py}{python}

More details about implementations of nodes are availablein the
\href{https://gitlab.com/manzerbredes/esds/-/raw/main/example/sender.py}{\textit{example code}} and the
\href{https://gitlab.com/manzerbredes/esds/-/raw/main/example/sender.py}{\textit{ESDS implementation of the SNs interface}}.

\subsection{Execution}
\label{sec:firstsimulation:execution}

To run our first simulation, the following command can be run:
that contains \verb|platform.yaml| and \verb|node.py|:
\begin{verbatim}
  > esds run platform.yaml
\end{verbatim}
Here is the output of the simulation:
\verbatiminput{assets/output.txt}
In this case, simulation tooks $0.002s$ and $10$ bytes were sent on the wlan0 interface from node 0
(src=n0) to node 1 (src=n1).

\subsection{Custom orchestrator instantiation}

Instead of using a \verb|platform.yaml| file, it is possible to instantiate manually the esds
orchestrator. To do so, you need to implement that procedure in a python file. Here is and example
that performs the exact same simulation presented in Section \ref{sec:firstsimulation:execution} but
with a custom instantiation of the orchestrator:
\addsource{assets/orchestrator.py}{python}
Next we can run the simulation:
\begin{verbatim}
  > ./orchestrator.py
\end{verbatim}

\section{Platform file}

As explain in Section \ref{sec:firstsimulation:platform}, esds platform files comprise 3 sections:
\begin{enumerate}
\item \textbf{general:} to settings up esds
\item \textbf{nodes:} to configure the simulated nodes
\item \textbf{interfaces:} to create network the interfaces available for each nodes
\end{enumerate}
Lets see in details the format of each section.

\subsection{The general section}
This section is used to settings up the overall parameters of esds. Table \ref{keywords:general} reference all the keywords for this section of the platform file.

\begin{table}[H]
  \centering
  \begin{adjustbox}{width=0.75\textwidth}
  \begin{tabular}{m{0.25\textwidth}m{0.3\textwidth}p{0.5\textwidth}}
    \toprule
    \textbf{Keyword} & \textbf{Description} & \textbf{Example} \\ \midrule

    \textbf{interferences} & Turn on/off interferences detection during wireless communications. &
    \begin{tabminted}{yaml}
interferences: on
    \end{tabminted}
    \\ \cmidrule{1-3}
    
    \textbf{debug} & Turn on/off esds debugging mode (generate a debug file). &
    \begin{tabminted}{yaml}
debug: on
    \end{tabminted}
    \\ \cmidrule{1-3}

    \textbf{debug\_file} & Specify the file to use as output for the debugging. &
    \begin{tabminted}{yaml}
debug_file: "./myfile.txt"
    \end{tabminted}
    \\ \cmidrule{1-3}
    
    \textbf{breakpoints} & Specify a list of simulated time (in seconds) at which esds must interrupt and call the specified callback. &
    \begin{tabminted}{yaml}
breakpoints: [5, 6, 7]
    \end{tabminted}
    \\ \cmidrule{1-3}
    
    \textbf{breakpoints\_every} & Specify an interval of time (in seconds) at which esds will interrupt and call the specified callback. &
    \begin{tabminted}{yaml}
breakpoints_every: 5
    \end{tabminted}
    \\ \cmidrule{1-3}
    
    \textbf{breakpoints\_callback} & Tell esds where how to reach the callback used during breakpoints. &
    \begin{tabminted}{yaml}
breakpoints_callback:
  file: "platform_callback.py"
  callback: "callback"
    \end{tabminted}
    \\ \bottomrule
  \end{tabular}
  \end{adjustbox}
  \caption{Usable keywords in the general section of a esds platform file.}
  \label{keywords:general}
\end{table}

\subsubsection{Notes}
The \textbf{interferences} keywords allows to control interference detection. It works as follow. If at any point in time during a wireless communication, another communication happens, on the same wireless interface, in the range of the receiver, then the interference return code will be given to the receiver upon reception.

\subsection{The node section}
The node section is used configure the simulated node of esds. Table \ref{keywords:nodes} references
all the keywords used in the nodes section.

\begin{table}[H]
  \centering
  \begin{adjustbox}{width=0.9\textwidth}
  \begin{tabular}{m{0.25\textwidth}m{0.3\textwidth}p{0.5\textwidth}}
    \toprule
    \textbf{Keyword} & \textbf{Description} & \textbf{Example} \\ \midrule

    \textbf{count} & Number of simulated nodes. &
    \begin{tabminted}{yaml}
nodes: 5
    \end{tabminted}
    \\ \cmidrule{1-3}
    
    \textbf{implementations} & Bind each node to their respective implementation (uses \textbf{the range syntax}). &
    \begin{tabminted}{yaml}
implementations:
   - 0 sender.py
   - 1-@ receiver.py
    \end{tabminted}
    \\ \cmidrule{1-3}

    \textbf{groups} & Specify the group to use in the nodes log reports. Useful to filter logs. By default, nodes are in the \textit{def} group. &
    \begin{tabminted}{yaml}
groups:
   - 0 groupA
   - 1-@ groupB
    \end{tabminted}
    \\ \cmidrule{1-3}

    
    \textbf{arguments} & Define the arguments that will be passed to each node implementation (keys of each element uses \textbf{the range syntax}). &
    \begin{tabminted}{yaml}
arguments:
        all: 2 
    \end{tabminted}
    \\ \bottomrule
  \end{tabular}
  \end{adjustbox}
  \caption{Usable keywords in the nodes section of a esds platform file.}
  \label{keywords:nodes}
\end{table}

Several entries in the platform file use a \textbf{range syntax} to bind data (node
implementations, links etc.) to node $ids$. For a simulation with $p$ nodes, each
node will have an allocated $id$ such that $id \in [0,1,...,p-1]$. Here are examples of valid range
syntax for a simulation that uses 5 nodes:
\begin{itemize}
\item \makebox[2cm]{\textbf{0,1,2,3}\hfill} Node 0,1,2 and 3
\item \makebox[2cm]{\textbf{0-2}\hfill} Node 0,1 and 2
\item \makebox[2cm]{\textbf{all}\hfill} Node 0,1,2,3 and 4
\item \makebox[2cm]{\textbf{2-@}\hfill} Node 2,3 and 4
\item \makebox[2cm]{\textbf{0-@}\hfill} Node 0,1,2,3 and 4 (same as \textbf{all})
\end{itemize}


\subsection{The interfaces section}
The interfaces section allows to define the network interfaces that will be usable by each node
during the simulation. For each interface the Table \ref{keywords:interfaces} references the
available keywords.

\begin{table}[H]
  \centering
  \begin{adjustbox}{width=0.9\textwidth}
  \begin{tabular}{m{0.25\textwidth}m{0.3\textwidth}p{0.5\textwidth}}
    \toprule
    \textbf{Keyword} & \textbf{Description} & \textbf{Example} \\ \midrule

    \textbf{type} & Interface is "wireless" or "wired". &
    \begin{tabminted}{yaml}
type: "wireless"
    \end{tabminted}
    \\ \cmidrule{1-3}

    \textbf{nodes} & Specify the nodes that have access the current network/interface (uses the \textbf{range syntax}) &
    \begin{tabminted}{yaml}
nodes: 2-@
    \end{tabminted}
    \\ \cmidrule{1-3}

    
    \textbf{links} & List all the links between nodes on the interface (uses the \textbf{range syntax}). &
    \begin{tabminted}{yaml}
links:
  # Link node 0 to node 1:
  - 0 10Mbps 0s 1
  # Link node 1 and 2 to node 3 and 4:
  - 1,2 1 Mbps 5s 3,4
    \end{tabminted}
    \\ \cmidrule{1-3}
    
    \textbf{txprefs} & Define the transmission performance of each wireless node (keys of each element uses \textbf{the range syntax}). This keyword is only available for wireless interfaces. &
    \begin{tabminted}{yaml}
txperfs:
  - 0 10kbps 0s
  - 1 10kbps 5s
    \end{tabminted}
    \\ \bottomrule
  \end{tabular}
  \end{adjustbox}
  \caption{Usable keywords for each interface in the interfaces section of a esds platform file.}
  \label{keywords:interfaces}
\end{table}

In esds, txperfs (or transmission performance) corresponds to the transmission performance on the
wireless interface. It is used to compute the transmission duration of wireless communications.
When using custom orchestrator instantiation, the txperfs parameter of a given node can be assigned by fixing the diagonal components of the bandwidth and latency matrices.

\end{document}