esds/manual/manual.tex

\documentclass[11pt]{article}

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

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

% Commands
\newcommand{\stateoff}{"\textit{off}"\xspace}
\newcommand{\stateon}{"\textit{on}"\xspace}
\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}}

% 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


\section{Architecture of ESDS}

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

ESDS simulator comprises two major components: 1) The Simulation Orchestrator (SO) 2) The Simulated
Nodes (SN). This architecture is depicted in 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), collects and processes the events (e.g communications,turn on/off). On the other hand,
nodes are threads that implement the node behaviors.

\section{Running your first simulation}

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}

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}

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

To execute our first simulation, the following command should be executed from the same folder
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}

\end{document}