\chapter{Overview}
\label{cha:overview}

This chapter gives informal introduction to the RFSM language and of how to use it to describe
FSM-based systems.

\section{Introductory example}
\label{sec:first-example}

Listing~\ref{lst:rfsm-gensig} is an example of a simple RFSM program\footnote{This program is
  provided in the distribution, under directory \texttt{examples/single/gensig/v2}.}. This program is
used to describe and simulate the model of a calibrated pulse generator. Given an input clock
\verb|H|, with period $T_H$, it generates a pulse of duration $n \times T_H$ whenever input
\texttt{E} is set when event $H$ occurs.

\begin{lstlisting}[language=Rfsm,frame=single,numbers=left,caption=A simple RFSM
  program,label={lst:rfsm-gensig},float]
@\label{gensig-1a}@fsm model gensig <n: int> (
  in h: event,
  in e: bool,
  out s: bool)
{
  states: E0, E1;
@\label{gensig-3}@  vars: k: int<0:n>;
  trans:
  | E0 -> E1 on h when e=1 with k:=1,s:=1
@\label{gensig-4}@  | E1 -> E1 on h when k<n with k:=k+1
@\label{gensig-5}@  | E1 -> E0 on h when k=n with s:=0;
  itrans:
  | -> E0 with s:=0;
@\label{gensig-1b}@}

@\label{gensig-2a}@input H : event = periodic (10,0,80)
input E : bool = value_changes (0:0, 25:1, 35:0)
@\label{gensig-2b}@output S : bool

@\label{gensig-6}@fsm g = gensig<4>(H,E,S)
\end{lstlisting}

The program can be divided in four parts.

\medskip The first part (lines \ref{gensig-1a}--\ref{gensig-1b}) gives a \textbf{generic model} of
the generator behavior. The model, named \verb|gensig|, has one parameter, \verb|n|, two inputs,
\verb|h| and \verb|e|, of type \verb|event| and \verb|bool| respectively, and one output \verb|s| of
type \verb|bool|. Its behavior is specified as a reactive FSM with two states, \verb|E0| and
\verb|E1|, and one internal variable \verb|k|. The transitions of this FSM are given after the
\verb|trans:| keyword in the form :
\begin{center}
  \framebox{\lstinline[language=Rfsm]{| source_state -> destination_state on ev when guard with
    actions}}
\end{center}
where
\begin{itemize}
\item \emph{ev} is the event trigerring the transition,
\item \emph{guard} is a set of (boolean) conditions,
\item \emph{actions} is a set of actions performed when the transition is enabled.
\end{itemize}
The semantics is that the transition is enabled
whenever the FSM is in the source state, the event \emph{ev} occurs and all the conditions in the
guard are true. The associated actions
are then performed and the FSM moves to the destination state. For example, the first transition is
enabled whenever an event occurs on input \verb|h| and, at this instant, the value of input \verb|e|
is 1. The FSM then goes from state \verb|E0| to state \verb|E1| and sets its internal variable
\verb|k| and its output \verb|s| to 1. The \emph{initial transition} of the FSM is given
after the \verb|itrans:| keyword in the form :
\begin{center}
  \framebox{\lstinline[language=Rfsm]{| -> initial_state with actions}}
\end{center}
Here the FSM is initially in state \verb|E0| with output \verb|s| set to 0.

A graphical representation of the \verb|gensig| model is given in
Fig.~\ref{fig:rfsm-gensig-model} (this representation was actually automatically generated from the
program in Listing~\ref{lst:rfsm-gensig}, as explained in Chap.~\ref{cha:rfsmc}).

\begin{figure}[!h]
   \includegraphics[height=8cm]{figs/gensig-model}
   \centering
  \caption{A graphical representation of FSM model defined in Listing~\ref{lst:rfsm-gensig}}
  \label{fig:rfsm-gensig-model}
\end{figure}

Note that, at this level, the value of the parameter \verb|n|, used in the type of the internal
variable \verb|k| (line~\ref{gensig-3}) and in the transition conditions (lines \ref{gensig-4} and
\ref{gensig-5}) is left unspecified, making the \verb|gensig| model a \emph{generic} one.

\medskip The second part of the program (lines \ref{gensig-2a}--\ref{gensig-2b}) lists \textbf{global inputs and
  outputs}\footnote{In case of multi-FSM programs, this part will also contains the declaration of
  \emph{shared} events and variables. See Sec.~\ref{sec:globals}.}.  For global outputs the
declaration simply gives a name and a type.  For global inputs, the declaration also specifies the
\textbf{stimuli} which are attached to the corresponding input for simulating the system. The
program of Listing~\ref{lst:rfsm-gensig} uses two kinds of stimuli\footnote{See
  Sec.~\ref{sec:globals} for a complete description of stimuli.}. The stimuli attached to input
\verb|H| are declared as \emph{periodic}, with a period of 10 time units, a start time of 0 and a
end time of 80. This means than an event will be produced on this input at time 0, 10, 20, 30, 40,
50, 60, 70 and 80. The stimuli attached to input \verb|E| say that this input will respectively take
value 0, 1 and 0 at time 0, 25 and 35 (thus producing a ``pulse'' of duration 10 time units starting
at time 25).

\medskip
The third and last part of the program (line~\ref{gensig-6}) consists in building the global model of the system by
\emph{instanciating} the FSM model(s).
Instanciating a model creates a ``copy'' of this model for which
\begin{itemize}
\item the generic parameters (\verb|n| here) are now bound to actual values (4 here),
\item the inputs and outputs are connected to the global inputs or outputs.
\end{itemize}

\medskip
A graphical representation of the system described in Listing~\ref{lst:rfsm-gensig} is given in
Fig.~\ref{fig:rfsm-gensig-top}\footnote{Again, this representation was actually automatically generated from the
program in Listing~\ref{lst:rfsm-gensig}, as explained in Chap.~\ref{cha:rfsmc}}.

\begin{figure}[!h]
   \includegraphics[height=8cm]{figs/gensig-top}
   \centering
  \caption{A graphical representation of system described in Listing~\ref{lst:rfsm-gensig}}
  \label{fig:rfsm-gensig-top}
\end{figure}

\subsection*{Simulating}
\label{sec:simulating-1}

Simulating the program means computing the reaction of the system to the input stimuli. Simulation
can be performed the RFSM command-line compiler or the IDE (see Chap.~\ref{cha:rfsmc} and
\ref{cha:gui} resp.). It produces a set of
\emph{traces} in VCD (Value Change Dump) format which can visualized using \emph{waveform viewers}
such as \texttt{gtkwave}. The simulation results for the program in Listing~\ref{lst:rfsm-gensig}
are illustrated in Fig.~\ref{fig:rfsm-gensig-chrono}.

\begin{figure}[!h]
   \includegraphics[width=\textwidth]{figs/gensig-chrono}
   \centering
  \caption{Simulation results for the program in Listing~\ref{lst:rfsm-gensig}, viewed using
    \texttt{gtkwave}}
  \label{fig:rfsm-gensig-chrono}
\end{figure}

\subsection*{Code generation}
\label{sec:code-generation-1}

RFSM can also generate code implementing the described systems simulation and/or
integration to existing applications.

\medskip
Currently, three backends are provided :
\begin{itemize}
\item a backend generating a C-based implementation of each FSM instance,
\item a backend generating a \emph{testbench} implementation in SystemC (FSM instances + stimuli
  generators),
\item a backend generating a \emph{testbench} implementation in VHDL (FSM instances + stimuli
  generators).
\end{itemize}

\medskip
The target language for the C backend is a C-like language augmented with
\begin{itemize}
\item a \verb|task| keyword for naming generated behaviors,
\item \verb|in|, \verb|out| and \verb|iinout| keywords for identifying inputs and outputs,
\item a builtin \verb|event| type,
\item primitives for handling events : \verb|wait_ev()|, \verb|wait_evs()| and
  \verb|notify_ev()|.
\end{itemize}
The idea is that the generated code can be turned into an application for a multi-tasking operating
system by providing actual implementations of the corresponding constructs and primitives.

\medskip
For the SystemC and VHDL backends, the generated code can actually be compiled and executed for
simulation purpose and. The FSM implementations generated by the VHDL backend can also be
synthetized to be implemented hardware using hardware-specific tools\footnote{We use the
  \textsc{quartus} toolchain from Intel/Altera.}.

\medskip
Appendices C1, C2 and C3 respectively give the C and SystemC code generated from the example in
Listing~\ref{lst:rfsm-gensig}.

\clearpage
\section{The RFSM language}
\label{sec:rfsm-language}

This section is more thorough presentation of the RFSM language introduced in the previous
section. This presentation is deliberately informal. The complete language syntax can
be found in Appendix~A.

\subsection{Types}
\label{sec:types}

There are two categories of types~: builtin types and user defined types.

\medskip
\textbf{Builtin types} are : \texttt{bool}, \texttt{int}, \texttt{float}, \texttt{char}, \texttt{event} and
\texttt{array}s.

\step Objects of type \texttt{bool} can have only two values : \texttt{0} (false) and \texttt{1} (true).

\step Values of type \texttt{char} are
denoted using single quotes. For example, for a variable \verb|c| having type \verb|char| :
\begin{center}
  \example{\lstinline[language=Rfsm]|c := 'A'|}
\end{center}
They can be converted from/to they internal representation as integers using the "\verb|::|" \emph{cast}
operator. For example, if \verb|c| has type \verb|char| and \verb|n| type \verb|int|, then
\begin{center}
  \example{\lstinline[language=Rfsm]|n := 'A'::int; c:=(n+1)::char|}
\end{center}
assigns value 65 to \verb|n| (ASCII code) and, then, value \verb|'B'| to \verb|c|.

\step The type \texttt{int} can be refined using a \emph{size} or a \emph{range annotation}. The
type \verb|int<sz>|, where \verb|sz| is an integer, is the type of integers which can be encoded using
\verb|n| bits. The type \verb|int<min:max>|, where both \verb|min| and \verb|max| are integers, is
the type of integers whose value ranges from \verb|min| to \verb|max|. The size and range limits,
can be constants or expressions whose value can be computed as compile time
(expressions involving parameter values, as exemplified line 9 in Listing~\ref{lst:rfsm-gensig}).

\step Supported operations on values of type \texttt{int} are described in Table~\ref{tab:int-ops}.
If \verb|n| is an integer and \verb|hi| (resp. \verb|lo|) an integer expression then \verb|n[hi:lo]|
designates the value represented by the bits \verb|hi|...\verb|lo| in the binary representation of
\verb|n|. Bit ranges can be both read (ex: \verb|x=y[6:2]|) or written (ex: \verb|x[8:4]:=0|). The
syntax \verb|n[i||, where \verb|n| is an integer is equivalent to \verb|n[i:i]|. The \emph{cast}
operator (\verb|::|) can be used to combine integers with different sizes (for example, if \verb|n|
has type \verb|int<16>| and \verb|m| has type \verb|int<8>|, writing \verb|n:=n+m| is not allowed
and mus be written, instead, \verb|n:=n+m::int<16>|. Note that the
logical ``or'' operator is denoted ``\verb+||+'' because the single ``\verb+|+'' is already used in
the syntax.

\begin{table}
\begin{center}
\begin{tabular}{|l|l|} \hline
\verb|+|, \verb|-|, \verb|*|, \verb|/|, \verb|%| (modulo) & arithmetic operations \\ \hline
\verb|>>|, \verb|<<| & (logical) shift right and left \\ \hline
\verb|&|, \verb+||+, \verb|^| & bitwise and, or and xor \\ \hline
\verb|[.:.]| & bit range extraction (ex: \verb|n:=m[5:3]|) \\ \hline
\verb|[.]| & single bit extraction (ex: \verb|b:=m[4]|) \\ \hline
\verb|::| & resize (ex: \verb|n::8|) \\ \hline
\end{tabular}
\caption{\label{tab:int-ops}Builtin operations on integers}
\end{center}
\end{table}

\step The operations on values of type \texttt{float} are : "\verb|+.|", "\verb|-.|", "\verb|*.|" and
"\verb|/.|" (the dot suffix is required to distinguish them from the corresponding operations on
\texttt{int}s).

\step Arrays are 1D, fixed-size collections of \verb|int|s, \verb|bool|s or \verb|float|s. Indices
range from 0 to \verb|n-1| where \verb|n| is the size of the array. For example,
 \verb|int array[4]| is the type describing arrays of four integers. If \verb|t| is an object
  with an array type, its cell with index $i$ is denoted \verb|t[i]|.

\medskip
\textbf{User defined types} are either \emph{type abbreviations}, \emph{enumerations} or
\emph{records}.

\step Type abbreviations are introduced with the following declaration
\begin{center}
  \framebox{\lstinline[language=Rfsm]{type typename = type_expression}}
\end{center}
Each occurrence of the defined type in the program is actually substituted by the corresponding type
expression.
% Type expressions in type abbreviations are currently limited to builtin types.

\medskip
\step Enumerated types  are introduced with the following declaration
\begin{center}
  \framebox{\lstinline[language=Rfsm]|type typename = enum \{ C1, ..., Cn \}|}
\end{center}
where \verb|C1|, \ldots, \verb|Cn| are the enumerated values, each being denoted by an identifier
starting with an uppercase letter. For example :
\begin{center}
  \example{\lstinline[language=Rfsm]|type color = \{ Red, Green, Orange \}|}
\end{center}

\medskip
\step Record types are introduced with the following declaration
\begin{center}
  \framebox{\lstinline[language=Rfsm]|type typename = record \{ fid1: ty1, ..., fidn: tyn \}|}
\end{center}
where \verb|fid1|, \ldots, \verb|fidn| and \verb|ty1|, \ldots, \verb|tyn| are respectively the name
and type of each record field For example :
\begin{center}
  \example{\lstinline[language=Rfsm]|type coord = record \{ x: int, y: int\}|}
\end{center}

Individual fields of a value with a record type can be accessed using the classical ``dot''
notation. For example, with a variable \verb|c| having type \verb|record| as defined above :
\begin{center}
  \example{\lstinline[language=Rfsm]|c.x := c.x+1|}
\end{center}

\subsection{FSM models}
\label{sec:fsm-models}

An FSM model, introduced by the \verb|fsm model| keywords, describes the interface and behavior of a
\emph{reactive finite state machine}. A reactive finite state machine is a finite state machine
whose transitions can only be caused by the occurrence of \emph{events}.

\begin{center}
\framebox{\lstinline[language=Rfsm]|fsm model <interface> { <body> }|}
\end{center}

\medskip
The \textbf{interface} of the model gives its name, a list of parameters (which can be empty) and a
list of inputs and outputs. All parameters and IOs are typed. Inputs and outputs are explicitely
tagged. An IO tagged \verb|inout| acts both as input and output (it can be read and written by the
model). Inputs and outputs are listed between \verb|(...)|. Parameters, if present are given between
\verb|<...>|. Examples :

\begin{center}
\example{\lstinline[language=Rfsm]|fsm model cntmod8 (in h: event, out s: int<0..7>) \{ ... \}|}
\end{center}

\begin{center}
\example{\lstinline[language=Rfsm]|fsm model gensig<n:int> (in h: event, in  e: bit, out s: bit) \{ ... \}|}
\end{center}

\begin{center}
\example{\lstinline[language=Rfsm]|fsm model update (in top: event, inout  lock: bool) \{ ... \}|}
\end{center}

\medskip
The model \textbf{body}, written between \verb|{...}|, generally comprises four sections :
\begin{itemize}
\item a section giving the list of \emph{states},
\item a section introducing local (internal) \emph{variables},
\item a section giving the list of \emph{transition},
\item a section specifying the \emph{initial transition}.
\end{itemize}

Each section starts with the corresponding keyword (\verb|states:|, \verb|vars:|, \verb|trans:| and
\verb|itrans:| resp.) and ends with a semi-colon.

\begin{center}
\framebox{\lstinline[language=Rfsm]| fsm model ... ( ... ) \{ states: ...; vars: ...; trans: ...; itrans: ...; \}|}
\end{center}

\subsubsection*{States}
\label{sec:states}

The \verb|states:| section gives the set of internal states, as a comma-separated list of
identifiers (each starting with a uppercase letter). Example :

\begin{center}
\example{\lstinline[language=Rfsm]|states: Idle, Wait1, Wait2, Done;|}
\end{center}

\subsubsection*{Variables}
\label{sec:variables}

The \verb|vars:| section gives the set of internal variables, each with its type. Example :

\begin{center}
\example{\lstinline[language=Rfsm]|vars: cnt: int, stop: bool;|}
\end{center}

The type of a variable may depend on parameters listed in the model interface. Example

\begin{center}
\example{\lstinline[language=Rfsm]|fsm gensig<n: int> (...) \{ ... vars: k: int<0..n>; ... \}|}
\end{center}

The \verb|vars:| section may be omitted.

\subsubsection*{Transitions}
\label{sec:transitions}

The \verb|trans:| section gives the set of transitions between states. Each transition is denoted

\begin{center}
\framebox{\lstinline[language=Rfsm]{| src_state -> dst_state on ev when guards with actions}}
\end{center}

where
\begin{itemize}
\item \emph{src\_state} and \emph{dst\_state} respectively designates the source state and destination state,
\item \emph{ev} is event trigerring the transition,
\item \emph{guards} is a set a enabling conditions,
\item \emph{actions} is a set of actions performed when then transition is enabled.
\end{itemize}

\medskip The semantics is that the transition is enabled whenever the FSM is in the source state,
the triggering event occurs and all conditions evaluate to true. The associated actions are then
performed and the FSM moves to the destination state.

\medskip
The triggering event must be listed in the inputs.

\medskip
Each condition listed in \emph{guards} must evaluate to a boolean value. The guard is true if
\emph{all} conditions evaluate to true (conjonctive semantics).
The guards may involve inputs and/or internal variables.

\medskip
The guard can be empty. In this case, the transition is denoted
\begin{center}
\framebox{\lstinline[language=Rfsm]{| src_state -> dst_state on ev with actions}}
\end{center}

\medskip The \textbf{actions} associated to a transition consists in modifications of the outputs
and/or internal variables or emissions of events. Modifications of outputs and internal variables
are denoted

\begin{center}
\framebox{\lstinline[language=Rfsm]{id := expr}}
\end{center}

where \emph{id} is the name of the output (resp. variable) and \emph{expr} an expression involving
inputs, outputs and variables and operations allowed on the corresponding types. The set of allowed
operations is given in Table~\ref{tab:type-ops}.

\begin{table}
\begin{minipage}[c]{1.0\linewidth}
\small
\begin{center}
\begin{tabular}{|l|l|} \hline
{\tt int}       & {\tt + - * / mod = != > < >= <=} \\  \hline
{\tt bool}      & {\tt = !=} \\ \hline
{\tt enumeration}     & {\tt = !=} \\  \hline
\end{tabular}
\caption{Operations on types}
\label{tab:type-ops}
\end{center}
\end{minipage}
\end{table}

\medskip
The action of emitting of an event  is simply denoted by the name of this event.

\medskip
Examples :

\begin{center}
\example{\lstinline[language=Rfsm]'S0 -> S1 on top '}
\end{center}

In the above example, the enclosing FSM switches from state \verb|S0| to state \verb|S1| when the
event \verb|top| occurs.

\begin{center}
\example{\lstinline[language=Rfsm]'Idle -> Wait on Clic with ctr:=0, received'}
\end{center}

In the above example, the enclosing FSM switches from state \verb|Idle| to state \verb|Wait|, resetting the internal variable
  \verb|ctr| to 0 and emitting event \verb|received| whenever an event occurs on its \verb|Clic| input.

\begin{center}
\example{\lstinline[language=Rfsm]'Wait -> Wait on Top when ctr<8 with ctr:=ctr+1'}
\end{center}

In the above example, the enclosing FSM stays in state \verb|Wait| but increments the internal
variable \verb|ctr| whenever an event \verb|Top| occurs and that, \emph{at this instant}, the
value of variable \verb|ctr| is smaller than 8.

\medskip
Expressions may also involve the C-like ternary conditional operator \verb|?:|.
For example, in the example below, the enclosing FSM stays in state \verb|S0| but updates the variable \verb|k|
at each occurrence of event \verb|H| so that is incremented if its current value is less than 8 or
reset to 0 otherwise.

\begin{center}
\example{\lstinline[language=Rfsm]'S0 -> S0 on H with k:=k<8?k+1:0'}
\end{center}

\medskip
The set of actions may be empty. In this case, the transition is denoted :

\begin{center}
\framebox{\lstinline[language=Rfsm]{src_state -> dst_state on ev when guard}}
\end{center}

\subsubsection*{Initial transition}
\label{sec:initial-transition}

The \verb|itrans:| section specifies the initial transition of the FSM. This transition is denoted~:

\begin{center}
\framebox{\lstinline[language=Rfsm]{| -> init_state with actions}}
\end{center}

where \emph{init\_state} is the initial state and \emph{actions} a list of actions to be performed
when initializing the FSM. The latter can be empty. in this case the initial transition is simply
denoted~:

\begin{center}
\framebox{\lstinline[language=Rfsm]{| -> init_state}}
\end{center}

\subsection{Globals}
\label{sec:globals}

Globals are used to connect model instances to the external world or to other instances.

\subsubsection*{Inputs and outputs}
\label{sec:inputs-outputs}

Interface to the external world are represented by \verb|input| and \verb|output| objects.

\step For outputs the declaration simply gives a name and a type~:

\begin{center}
\framebox{\lstinline[language=Rfsm]'output name : typ'}
\end{center}

\step For inputs, the declaration also specifies the \textbf{stimuli} which are attached to the
corresponding input for simulating the system.
\begin{center}
\framebox{\lstinline[language=Rfsm]'input name : typ = stimuli'}
\end{center}

There are three types of stimuli~:
periodic and
sporadic stimuli for inputs of type \verb|event| and value changes for scalar inputs.

\medskip
Periodic stimuli are specified with a period, a starting time and an ending time.

\begin{center}
\framebox{\lstinline[language=Rfsm]'periodic(period,t0,t1)'}
\end{center}

Sporadic stimuli
are simply a list of dates at which the corresponding input event occurs.

\begin{center}
\framebox{\lstinline[language=Rfsm]'sporadic(t1,...,tn)'}
\end{center}

Value changes are given as
list of pairs \verb|t:v|, where \verb|t| is a date and \verb|v| the value assigned to the
corresponding input at this date.

\begin{center}
\framebox{\lstinline[language=Rfsm]'value_changes(t1:v1,...,tn:vn)'}
\end{center}

\medskip
Examples:

\begin{center}
\example{\lstinline[language=Rfsm]'input Clk: event = periodic(10,10,120)'}
\end{center}

The previous declaration declares \verb|Clk| as a global input producing periodic events with period 10, starting
  at t=10 and ending at t=100\footnote{Note that, at this level, there's no need for an absolute
    unit for time.}.

\begin{center}
\example{\lstinline[language=Rfsm]'input Clic: event = sporadic(25,75,95)'}
\end{center}

The previous declaration declares \verb|Clic| as a global input producing events at t=25, t=75 and
  t=95.

\begin{center}
\example{\lstinline[language=Rfsm]'input E : bool = value_changes (0:false, 25:true, 35:false)'}
\end{center}

The previous declaration declares \verb|E| as a global boolean input taking value \texttt{false} at
t=0, \texttt{true} at t=25 and \texttt{false} again at t=35.

\subsubsection*{Shared objects}
\label{sec:shared}

Shared objects are used to represent interconnexions between FSM instances. This situation only
occurs when the system model involves several FSM instances and when the input of a given instance
is provided by the output of another one (see Section~\ref{sec:fsm-instances}).

\step For shared objects the declaration simply gives a name and a type~:

\begin{center}
\framebox{\lstinline[language=Rfsm]'shared name : typ'}
\end{center}

\subsection{Instances and system}
\label{sec:fsm-instances}

The description of the system is carried out by instanciating
-- and, possibly, inter-connecting -- previously defined FSM models.

\medskip
Instanciating a model creates a ``copy'' of the corresponding FSM for which
\begin{itemize}
\item the parameters of the model are bound to their actual value,
\item the declared inputs and outputs are connected to global inputs, outputs or shared
  objects.
\end{itemize}

\medskip
The syntax for declaring a model instance is as follows~:

\begin{center}
\framebox{\lstinline[language=Rfsm]'fsm inst_name = model_name<param_values>(actual_ios)'}
\end{center}

where
\begin{itemize}
\item \emph{inst\_name} is the name of the created instance,
\item \emph{model\_name} is the name of the instanciated model,
\item \emph{param\_values} is a comma-separated list of values to be assigned to the formal
  (generic) parameters,
\item \emph{actual\_ios} is a comma-separated list of global inputs, outputs or shared objects to be
  connected to the instanciated model.
\end{itemize}

Binding of parameter values and IOs is done by position. Of course the number and respective types
of the formal and actual parameters (resp. IOs) must match.

\medskip
For example, the last line of the program given in Listing~\ref{lst:rfsm-gensig}

\begin{center}
\example{\lstinline[language=Rfsm]'fsm g = gensig<4>(H,E,S)'}
\end{center}

creates an instance of model \verb|gensig| for which \verb|n=4| and whose inputs (resp. output) are
connected to the global inputs (resp. output) \texttt{H} and \texttt{E} (resp. \texttt{S}).

\subsubsection*{Multi-FSM models}
\label{sec:multi-fsm-models}

It is of course possible to build a system model as a \emph{composition} of FSM instances.  An
example is given in Listing~\ref{lst:rfsm-cntmod8}. The system is a simple modulo 8 counter, here
described as a combination of three event-synchronized modulo 2 counters\footnote{This program is
  provided in the distribution, under directory \texttt{examples/multi/ctrmod8}.}.

\medskip
Here a single FSM model (\texttt{cntmod2}) is instanciated thrice, as \texttt{C0}, \texttt{C1} and
\texttt{C2}. These instances are synchronized using two \textbf{shared events}, \texttt{R0} and \texttt{R1}.

\medskip
The graphical representation of the program is given in Fig.~\ref{fig:rfsm-cntmod8-top}. Simulation
results are illustrated in Fig~\ref{fig:rfsm-cntmod8-vcd}.

\begin{lstlisting}[language=Rfsm,frame=single,numbers=left,caption=A multi-model RFSM
  program,label={lst:rfsm-cntmod8},float]
fsm model cntmod2(
  in h: event,
  out s: int<0:1>,
  out r: event)
{
  states: E0, E1;
  trans:
  | E0 -> E1 on h with s:=1
  | E1 -> E0 on h with r, s:=0;
  itrans:
  | -> E0 with s:=0;
}

input H: event = periodic(10,10,100)
output S0, S1, S2: int<0:1>
output R2: event

shared R0, R1: event

fsm C0 = cntmod2(H,S0,R0)
fsm C1 = cntmod2(R0,S1,R1)
fsm C2 = cntmod2(R1,S2,R2)
\end{lstlisting}

\begin{figure}[!h]
   \includegraphics[height=9cm]{figs/ctrmod8-top}
   \centering
  \caption{A graphical representation of program described in Listing~\ref{lst:rfsm-cntmod8}}
  \label{fig:rfsm-cntmod8-top}
\end{figure}

\clearpage
\begin{figure}[!h]
   \includegraphics[width=\textwidth]{figs/ctrmod8-chrono}
   \centering
  \caption{Simulation results for the program in Listing~\ref{lst:rfsm-cntmod8}}
  \label{fig:rfsm-cntmod8-vcd}
\end{figure}

\subsection{Functions}
\label{sec:functions}

Conditions and actions associated to FSM transitions can use globally defined functions. An example
is given in listing~\ref{lst:rfsm-heron}\footnote{This example can be found in directory
  \texttt{examples/heron/v2} in the distribution.}. The FSM described here computes an approximation
of its input \verb|u| using Heron's classical algorithm. Successive approximations are computed in
state \verb|Iter| and the end of computation is detected when the square of the current
approximation \verb|x| differs from the argument (\verb|a|) from less than a given threshold
\verb|eps|. For this, the model uses the global function \verb|f_abs| defined at the beginning of
the program. This function computes the absolute value of its argument and is used twice in the
definition of the FSM model \verb|heron|, for defining the condition associated to the two
transitions going out of state \verb|Iter|.

\begin{lstlisting}[language=Rfsm,frame=single,numbers=left,caption=An RFSM program using a global
  function definition,label={lst:rfsm-heron},float]
function f_abs(x: float) : float { return x < 0.0 ? -.x : x }

fsm model Heron<eps: float>(
  in h: event,
  in start: bool,
  in u: float,
  out rdy: bool,
  out niter: int,
  out r: float)
{
  states: Idle, Iter;
  vars: a: float, x: float, n: int;
  trans:
  | Idle -> Iter on h when start=1 with a:=u, x:=u, rdy:=0, n:=0
  | Iter -> Iter on h when f_abs(x*.x-.a)>=eps with x:=(x+.a/.x)/.2.,
                                                    n:=n+1
  | Iter -> Idle on h when f_abs(x*.x-.a)<eps with r:=x, niter:=n, rdy:=1;
  itrans:
  | -> Idle with rdy:=1;
}

input H : event = periodic (10,10,200)
input U : float = value_changes (5:2.0)
input Start : bool = value_changes (0:0, 25:1, 35:0)
output Rdy : bool
output R : float
output niter : int

fsm heron = Heron<0.00000001> (H,Start,U,Rdy,niter,R)
\end{lstlisting}

\medskip
\step The general form for a function definition is

\begin{center}
\framebox{\lstinline[language=Rfsm]| function name (<arg\_1>:<type\_1>, ..., <arg\_n>:<type\_n>)\ :\ <type\_r> \{ return <expr> \}|}
\end{center}

\noindent
where
\begin{itemize}
\item \lstinline[language=Rfsm]|<arg_i>| (resp. \lstinline[language=Rfsm]|<type_i>|) is the name
  (resp. type) of the i$^{th}$ argument,
\item \lstinline[language=Rfsm]|<type_r>| is the type of value returned by the function,
\item \lstinline[language=Rfsm]|<expr>| is the expression defining the function value.
\end{itemize}

\medskip
\step Functions can only return one result and cannot use local variables. There are therefore more
like so-called \emph{macros} in the C language than full-fledged functions and are typically used to
improve readability of the programs.

\clearpage
\subsection{Constants}
\label{sec:constants}

Global constants can be defined using the following syntax~:

\begin{center}
\framebox{\lstinline[language=Rfsm]|constant name : <type> = <value>|}
\end{center}

\noindent
where
\begin{itemize}
\item \lstinline[language=Rfsm]|<type>| is the type of the defined constant (currently limited to
  \verb|int|, \verb|float| and arrays of \verb|int|s or \verb|float|s,
\item \lstinline[language=Rfsm]|<value>| is the value of the constant (which must be an \verb|int|
  or \verb|float| literal or an array of such literals).
\end{itemize}

Global constants, just like global functions, have a global scope and hence can be used in any FSM
model or instance.

\subsection{Semantic issues}
\label{sec:semantic-issues}

This presentation of the language has deliberately focused on syntax. Formalizing the semantics of programs made of
reactive finite state machines -- and in particular when several of these machines are interacting
-- is actually far from trivial and will not be carried out here.

Instead, this section will describe some ``practical'' problems that may arise when simulating such
systems and how the language currently addresses them, without delving too much into the underlying
semantics issues\footnote{This is not that these issues do not deserve a formal treatment. Of
  course, they do ! But we think we this document is not the right place to do it.}.

\subsubsection{Priorities}
\label{sec:priorities}

The FSM models involved in programs should normally be \emph{deterministic}. In other words, a
situation where several transitions are enabled at the same instant should normally never arise. But
this condition may actually be difficult to enforce, especially for models reacting to several input
events. Consider for example, the model described in Listing~\ref{lst:rfsm-prio-pb}. This model
describes a (simplified) stopwatch. It starts counting seconds (materialized by event \verb|sec|)
as soon as event \verb|startstop| occurs and stops as soon as it occurs again.

\begin{lstlisting}[language=Rfsm,frame=single,numbers=left,caption=A program showing a potentially non-deterministic
  model,label={lst:rfsm-prio-pb},float]
fsm model chrono (
     in sec: event,
     in startstop: event,
    out aff: int)
  {
  states: Stopped, Running;
  vars: ctr: int;
  trans:
  | Stopped -> Running on startstop with ctr:=0; aff:=0
  | Running -> Running on sec with ctr:=ctr+1; aff:=ctr
  | Running -> Stopped on startstop;
  itrans:
  |-> Stopped;
  }

input StartStop: event = sporadic(25,70)
input H:event = periodic(10,10,110)
output Aff: int

fsm c = chrono(H,StartStop,Aff)
\end{lstlisting}

The problem is that if both events occur simultaneously  then
both the transitions at line 10 and 11 are enabled. In fact, here's the error message produced by
the compiler when trying to simulate the above program :

\small
\begin{verbatim}
Error when simulating FSM c: non deterministic transitions found at t=70:
	- Running--h|ctr:=ctr+1; aff:=ctr->Running[0]
	- Running--startstop->Stopped[0]
\end{verbatim}
\normalsize

Of course, this could be avoided by modifying the stimuli attached to input \verb|StartStop| so that the
corresponding events are never emitted at time $t=n\times 10$. But this is, in a sence, cheating,
since this event is supposed to modelize user interaction which occur, by essence, at impredictible
dates.

The above problem can be solved by assigning a \emph{priority} to transitions. In the current
implementation, this is achieved by tagging some transitions as ``high priority''
transitions\footnote{Future versions may evolve towards a more sophisticated mechanism allowing
  numeric priorities.}.  When several transitions are enabled, if one is tagged as ``high priority''
than it is automatically selected\footnote{If none (resp. several) is (resp. are) tagged, the
  conflict remains, of course.}.

Syntaxically, tagging a transition is simply achieved by replacing the leading ``\verb+|+'' by a
``\verb|!|''.  In the
case of the example above, the modified program is given in
Listing~\ref{lst:rfsm-prio-solved}. Tagging the last transition is here equivalent to give to the
\verb|startstop| precedence against the \verb|h| event when the model is in state
\verb|Running|.

\begin{lstlisting}[language=Rfsm,frame=single,numbers=left,caption=A rewriting of the model defined
  in Listing~\ref{lst:rfsm-prio-pb}, label={lst:rfsm-prio-solved},float]
fsm model chrono (...)
  {
  ...
  trans:
    ...
    | Running -> Running on sec with ctr:=ctr+1; aff:=ctr
    ! Running -> Stopped on startstop
  itrans: -> Stopped;
  }
...
\end{lstlisting}

\subsubsection{Sequential vs. synchronous actions}
\label{sec:sequ-vs.-synchr}

An important question is whether, when a transition specifying \emph{several actions} to be
performed is taken, the corresponding actions are performed sequentially or not.

Consider for example, the following transition, in which \verb|x| and \verb|y| are internal
variables of the enclosing FSM :

\begin{center}
\example{\lstinline[language=Rfsm]'S0 -> S1 on H with x:=x+1, y:=x*2'}
\end{center}

Suppose that the value of variable \verb|x| is 1 just before event \verb|H| occurs. What will the value of
variables \verb|x| and \verb|y| after this transition ?

\step With a \textbf{sequential interpretation}, actions are performed sequentially, one after the
other, in the order they are specified. With this interpretation, order of execution matters. In the example above, it will
assign the value 2 to \verb|x| and 4 to \verb|y|.

\step With a \textbf{synchronous interpretation}, actions are performed in parallel, the value of each variable
occuring in right-hand-side expressions being the one \emph{before} the transition. With this
interpretation, order of executions does \emph{not} matter. In the example above, it will
assign the value 2 to \verb|x| and 2 to \verb|y|.

\medskip
A sequential interpretation naturally fits a software execution model, in which FSM variables are
implemented as program variables and actions as immediate modifications of these variables, whereas
a synchronous interpretation reflects hardware execution models, in which FSM variables are
typically implemented as registers which are updated in parallel at each clock cycle.

\medskip
By default, the \verb|rfsmc| compiler relies on a sequential interpretation, both for simulation and
code production\footnote{For the C and SystemC backends, this means that FSM variables are
  implemented as local variables of the function implementing the FSM model. For the VHDL backend,
  these variables are implemented as \texttt{variable}s withing the process implementing the
  FSM.}. But, in certain cases, and in particular when specifying models to be synthetized on
hardware, a synchronous interpretation is more natural and/or can lead to more efficient
implementations. Switching to a synchronous interpretation is possible by invoking the \verb|rfsmc|
compiler with the \verb|-synchronous_actions| option\footnote{For the VHDL backend, in particular, the
  \texttt{-synchronous\_actions} option forces the FSM variables to be implemented as
  \texttt{signal}s.}.

% \medskip
% \textbf{Note}. As a syntactic reminder, list of actions are printed in diagrams using ``\verb|;|'' as a separator when using
% a sequential interpretation and using ``\verb|,|'' when using a synchronous interpretation.

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "rfsm"
%%% End:


\subsection{Cross Sections}
Some of the primary quantities we are interested in predicting and measuring in proton-proton collisions are \emph{cross sections}, which can be thought of as a measure of the probability\footnote{More precisely, a cross section is measured in units of distance squared. However, the characteristic cross section of a process is synonymous with its probability of occuring and it is more intuitive to describe cross sections in these terms.} of a specific process occurring.
The QCD factorization theorem~\cite{Collins:1989gx} allows the cross section for an arbitrary deep inelastic proton-proton collision to be written in terms of two components: a perturbatively calculable hard term and a non-perturbative PDF.
Thus, the cross section for $pp \to X + Y$ can be calculated in the following way:
\begin{equation}
    \sigma(pp \to X + Y) = \sum_{i,j} \int dx_i dx_j f(x_i, Q^2) f(x_j, Q^2) \sigma(q_i q_j \to Y),
\end{equation}
in which $X$ may be any hadronic final state, and $Y$ is an arbitrary final state for the inelastic scattering of two partons $q_i$ and $q_j$.
The sum is calculated over all partons and integrated over all possible momentum fractions for the PDFs of each parton.
The hard term, $\sigma(q_i q_j \to Y)$, can be calculated perturbatively in QCD.
In practice, these calculations are done through the use of Monte Carlo generators, described in greater detail in Sec.~\ref{sec:pp_mc}.
Cross sections for typical processes of interest at pp collision experiments are shown as a function of the center-of-mass energy in Fig.~\ref{fig:pp_xs}.
\begin{figure}[htbp!]
    \centering
    \includegraphics[width=0.6\linewidth]{figures/physics_of_pp/pp_cross_sections.png}
    \caption{Cross sections for typical processes of interest in pp collision experiments, shown as a function of the center-of-mass energy, $\sqrt{s}$. Taken from~\cite{Campbell:2006wx}.}
    \label{fig:pp_xs}
\end{figure}

\subsection{Parton Showers, Hadronization, and Jets} \label{sec:pp_physics_jets}
High energy processes involving the strong interaction are very well-described by perturbative QCD calculations.
However, at lower energies (less than or equal to about 1 GeV), the perturbative appraoch fails to provide an accurate description of the SM phenomena: the strong coupling $\alpha_s$ of QCD becomes close to unity, as shown in Fig.~\ref{fig:pp_qcd_coupling}.
\begin{figure} [htbp!]
    \centering
    \includegraphics[width=0.6\linewidth]{figures/physics_of_pp/pp_qcd_coupling.png}
    \caption{The strong coupling constant $\alpha_s$ of QCD as a function of $Q^2$. Different colored lines correspond to various renormalization schemes. Taken from~\cite{Deur:2016tte}.}
    \label{fig:pp_qcd_coupling}
\end{figure}
When the coupling $\alpha_s$ nears unity, the perturbative approach fails for the following reason: perturbative expansions are made in powers of the coupling, so the coupling must be significantly less than one in order for a finite expansion to provide a good approximation.
In describing phenomena like parton showers and hadronization, energy scales of $\mathcal O(1)$ GeV are relevant, and a strictly perturbative calculation will not provide a satisfactory description.

A \emph{parton shower} refers to the process by which a high energy parton stemming from the hard interaction produce showers of ``soft'' particles at lower energies.
Typically, this is either gluon splitting, in which a gluon converts into a quark-antiquark pair, or gluon radiation, in which a quark radiates a gluon.
In practice, parton showers are modeled with Monte Carlo generators which utilize Sudakov form factors~\cite{Sudakov:1954sw} and splitting functions to simplify calculations~\cite{Hoche:2014rga}.

As discussed in Sec.~\ref{sec:theory_qcd}, quarks and gluons are confined to bound states which must be colorless.
Moreover, the potential energy of a hadron increases as a function of the distance between the partons.
At a large enough distance, it becomes energetically favorable to break the original bound state in which they existed and instead form new hadrons.
This process is called \emph{hadronization}.
In high energy collisions, quarks and gluons are often ejected from the hard interaction with high enough momentum for hadronization to occur.
Frequently, the newly formed hadron will initiate a cascade of decays and gluon radiation, forming a cone of hadronic activity.
This cone of particles stemming from the hadronization of a quark or gluon is called a \emph{hadronic jet}.
Hadronization cannot be adequately described through perturbative calculations alone, and instead phenomenological models like the Lund-String Model~\cite{Andersson:1983ia} are employed.

\subsection{Underlying Event and Pileup}
In a given bunch crossing, there is typically only one hard scattering interaction of interest from a physics point of view.
In addition to this hard interaction, there are additional lower energy ``soft'' scattering interactions.
The soft scattering may be due either to interactions between partons other than those involved in the hard scattering interaction or interactions between protons other than those involved in the hard scattering interaction.
The former is called the \emph{underlying event}, while the latter interactions are called \emph{pileup} interactions.
The modeling of underlying event and pileup is often performed through heuristic approaches which extrapolate directly from experimental collision data.

Though soft scattering interactions from underlying event and pileup are typically not of interest, it is still imperative to understand and adequately model them in order to study physics processes of interest.
A large portion of the hadronic activity in an event at the LHC stems from these soft interactions and will effect, for example, the jet multiplicity and missing transverse momentum calculation in that event.
Physics analyses often use the jet multiplicity and missing transverse momentum to identify regions of high signal purity (for example, an analysis searching for supersymmetric particles will typically select for events with high missing transverse momentum) -- for these reasons, it is vital to understand the contribution of underlying event and pileup to these distributions in order to properly model the targeted signal process and accurately estimate the relevant SM background processes.

Parton showers, hadronization, and underlying event are visually depicted for a hadron-hadron collision in Fig.~\ref{fig:pp_event_schematic}.

\begin{figure} [htbp!]
    \centering
    \includegraphics[width=0.7\linewidth]{figures/physics_of_pp/pp_event_schematic.png}
    \caption[Schematic of a hadron-hadron collision. Taken from~\cite{Hoche:2014rga}.]{Schematic of a hadron-hadron collision. The red blob indicates the hard scattering interaction and the subsequent tree-like structure depicts parton showers, while the purple blob indicates an underlying event scattering interaction. Light green blobs depict hadronization, dark green blobs depict subsequent decays of those hadrons, and yellow lines depict soft Bremsstrahlung radiation. Taken from~\cite{Hoche:2014rga}.}
    \label{fig:pp_event_schematic}
\end{figure}


\clearpage
\chapter{BASIC TYPESETTING}
\doublespacing

$$\kappa^(23)$$

Albert Einstein's theory of relativity stated that $E=mc^2$ \cite{Einstein:1944a}

In these paragraphs, we will display examples for many common features in \LaTeX. The code is shown in \texttt{main.tex} and the associated output in \texttt{main.pdf}. We assume you already know the basic syntactical structure of \TeX with its commands and environments. If you are not familiar, it is recommended you read \texttt{intro to latex.pdf} provided in this package. We will start with the most basic examples of different fonts and styles.

\section*{Fonts and Styles}

\textbf{Bold} font is made using the \texttt{\textbackslash textbf} command. \textit{Italic} font is made using the \texttt{\textbackslash textit} command. \underline{Underline} font is made using the \texttt{\textbackslash underline} command. \texttt{Monospace/teletype} font is made using the \texttt{\textbackslash texttt} command. \textsf{Sans-serif} font is made using the \texttt{\textbackslash textsf} command.

\section*{Math}

One of \LaTeX's greatest strengths is its mathemetical typesetting. You can enter inline math $\mathrm{e}^{\mathrm{i}\pi}$. You can also have a math block.

$$
f(x) = \int _{-\infty} ^\infty g(x) \, \mathrm{d}x
$$

You can have $f(x) = \int _{-\infty} ^\infty g(x) \, \mathrm{d}x$ numbered equations with the \texttt{equation} environment.

\begin{equation}
	\Phi(n) = \gamma^n + \Delta \gamma \cdot \vec{\zeta} \label{eqn:exampleEqn}
\end{equation}

You can also align equations by using a \texttt{\&} in the \texttt{align*} environment. Omitting the \texttt{*} will number each line.

\begin{align*}
	h_1 &= \mathbf{X}_1 + N \\
	h_2 &= \mathbf{X}_1 + N \\
	&\vdots \\
	h_n &= \mathbf{X}_n + N \\
\end{align*}

Make sure you use the proper notation for your field. A common mistake is to italicize units in math mode. Units are supposed to be typset in a roman font because $\mu m$ in italic means you are multiplying two variables and $\mathrm{\upmu m}$ means your value is in micrometers. A similar mistake is often made for special functions. If you are using a multi-letter function such as $\sin()$ or $\mathrm{floor}()$, it should not be italic for the same reason as before. To fix these issues, you can use the \texttt{\textbackslash mathrm} command when in math mode to set your text as roman (or upright). Greek letters need to be specified as upright by prepending `up' to the command, e.g., \texttt{\$\textbackslash upmu\$}.

\section*{Quotation marks}
Quotes are written in latex using \texttt{\`} for opening and \texttt{\'} for closing. They can be used for `single' and ``double'' quotes alike.

\section*{Lists}
Bulleted lists are made with the \texttt{itemize} environment. Numbered lists are made with hte \texttt{enumerate} environment. They can be made hierrarchal by embedding another lists within. A bulleted list:
\begin{itemize}
	\item First level
	\begin{itemize}
		\item second level
	\end{itemize}
\end{itemize}
A numbered list:
\begin{enumerate}
	\item First level
	\begin{enumerate}
		\item second level
	\end{enumerate}
\end{enumerate}

\section*{Code Listing}
You can make a code block using the \texttt{verbatim} environment. Be mindful that unlike most \TeX environments, it is senstive to spaces (but not tabs) at the beginning of lines so that you may indent your code.
\begin{verbatim}
class Fill:
  def __init__(self, color=BLACK, style='solid'):
    self.color = color
    self.style = style
\end{verbatim}

\section*{Figures}
Figures can be included using the \texttt{\textbackslash includegraphics} command, and their placement and captioning can be configured using the \texttt{figure} environment. Generally, \LaTeX can determine the best placement of your figure on the page itself, but you can give it a placement option of \texttt{h}, \texttt{t}, \texttt{b}, or \texttt{p} to place it \underline{h}ere, on \underline{t}op, on \underline{b}ottom, or on its own \underline{p}age. Note that in \texttt{main.tex}, we have already set the graphics path with the \texttt{\textbackslash graphicspath\{ \{Figures/ \} \}} command, which means it is always going to look in that folder for your figures.

\begin{figure}[ht]
	\centering
	\includegraphics[width=4 in]{elbee.jpg}
	\caption{This is our new mascot!}
	\label{fig:exampleFig}
\end{figure}

$$20 (epsilon / 2) = \sqrt{5}$$

\section*{Tables}
Tables can be generated using the \texttt{tabular} environment, and their placement and captioning is configured with the \texttt{table} environment, like with figures. In the \texttt{tabular} environment, you provide a section parameter that configures your number ofcolumns, their text alignment, and vertical borders.

\begin{table}[ht]
	\centering
	\caption{An example of a table}
	\begin{tabular}{l c c c}
		\hline
		Color	&  Radius, $r$ [mm] & RMS Voltage, $v$ [V]  & Height \\
		\hline
		Cyan	&	72.2	&	2.1 \\
		Magenta	&	45.2	&	5.5 \\
		Yellow	&	78.5	&	1.3 \\
		Black	&	33.3	&	6.9 \\
		Blue    &   20.9    &   2.1 \\
		\hline
	\end{tabular}
	\label{tab:exampleTable}
\end{table}

\section*{Citations and Cross-references}
You can add citations \cite{customBibLabel} from \cite{Q} your \texttt{references.bib} file \cite{Burka:1993a} using the \texttt{\textbackslash cite} command \cite{customBibLabel2}. You can also cross-reference equations, figures, and tables and many other items by giving them a custom label with the \texttt{\textbackslash label} command, and using the  \texttt{\textbackslash ref} command to call them. Citations and references like this are very nice because you don't have to worry about item numbering and how it may change as you develop your document; you tell \LaTeX where you want it, and it will handle the numbering so it makes sense. And in PDF viewers, the cross-references are clickable intra-document links that will take you to the associated item. Figure \ref{fig:exampleFig}. Table \ref{tab:exampleTable}. Equation \ref{eqn:exampleEqn}.

\section*{Footnotes}
Footnotes can be placed with the \texttt{\textbackslash footnote} command\footnote{This is a footnote but it's a very long footnote so that we can test the indent of the footnote text when it leads onto a second line at the bottom of the page.}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% CS638: Applied Machine Learning
% Copyright 2016 Pejman Ghorbanzade <pejman@ghorbanzade.com>
% Creative Commons Attribution-ShareAlike 4.0 International License
% More info: https://github.com/ghorbanzade/beacon
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\def \topDirectory {.}
\def \srcDirectory {\topDirectory/src}
\def \texDirectory {\srcDirectory/tex}
\def \imgDirectory {\topDirectory/../build/umb-cs638-2016s/img}

\documentclass[12pt,letterpaper,twoside]{article}

\usepackage{\texDirectory/directives}
\input{\texDirectory/config}
\usepackage{\texDirectory/report}

\begin{document}

\doc{title}{Solution to Assignment 2}
\doc{date-pub}{Feb 11, 2016 at 4:00 PM}
\doc{date-due}{Feb 18, 2016 at 4:00 PM}

\makeHeader

\section*{Question}

Profit of stores of a coffeehouse chain has been recorded and provided in \texttt{data.txt} file, along with population of the city they are in.

The coffeehouse is planning an expansion and is deciding which city to expand to.

Objective is to use the dataset to predict profit of the new store given population of the city in which it will operate.

\subsection*{Solution}

To understand the data, profit of the stores based on population of the city they operate in is visualized in Figure \ref{fig1}.

\begin{figure}[H]\centering
\includegraphics[width=0.8\textwidth]{\imgDirectory/umb-cs638-2016s-hw02-01.png}
\caption{Profit of Coffee Shop based on Population of the City}\label{fig1}
\end{figure}

Correlation of the dataset is calculated at 0.837 which ensures there is a correlation between the profit (dependant variable) and the city population (independant variable).

As there is only one single feature in our dataset, the hypothesis function for linear regression will be of the form shown in Eq. \ref{eq1}.

\begin{equation}\label{eq1}
h(x) = \theta_0 + \theta_1 x
\end{equation}

Applying linear regression on the dataset, coefficients $\theta_0$ and $\theta_1$ of the hypothesis function will be obtained.

\begin{equation}\label{eq2}
\begin{split}
\theta_0 = -3.89578\\
\theta_1 = 1.19303
\end{split}
\end{equation}

\begin{terminal}
lm.out <- lm(data$profit ~ data$population)
theta <- coef(lm.out)
\end{terminal}

Thus, the best fitted regression line will be as depicted in Fig. \ref{fig2}.

\begin{figure}[H]\centering
\includegraphics[width=0.8\textwidth]{\imgDirectory/umb-cs638-2016s-hw02-03.png}
\caption{Best-Fitted Regression Line for the Dataset}\label{fig2}
\end{figure}

Using previously obtained $\theta_0$ and $\theta_1$, the cost function can be obtained as shown in Eq. \ref{eq3}.

\begin{equation}\label{eq3}
\begin{split}
J(\theta_0, \theta_1) & = \frac{1}{2m}\sum\limits_{i=1}^m \left(h_{\theta}(x^{(i)})-y^{(i)}\right)^{2} \\
 & = \frac{1}{2 \times 97}\sum\limits_{i=1}^{97} \left({-3.90} + {1.19}x^{(i)} - y^{(i)}\right)\\
 & = 4.476971
\end{split}
\end{equation}

\begin{terminal}
cost <- sum((x%*%theta)-y)^2)/(2*m)
\end{terminal}

\subsubsection*{Cost Function Minimization using Gradient Descent}

To measure the impact of the learning rate, the cost function is minimized using gradient descent as shown in Eq. \ref{eq4}.

\begin{equation}\label{eq4}
\theta_j := \theta_j - \alpha \frac{\partial}{\partial\theta_j}J(\theta_0, \theta_1)
\end{equation}

Taking $\alpha = 0.02$ and the number of iterations $i = 500$, final values for $\theta_0$ and $\theta_1$ are obtained as $\theta_0 = 3.261$ and $\theta_1 = 1.130$.
Meanwhile, using the same number of iterations, choosing $\alpha = 0.005$ will result in $\theta_0 = -1.367$ and $\theta_1 = 0.939$ which is much closer to the values obtained using linear regression tool in Eq. \ref{eq2}.

\begin{terminal}
gradient_descent <- function(x, y, alpha) {
	x <- cbind(1, x)
	iterations <- 500
	theta <- c(0, 0)
	for (i in 1:iterations)
	{
		theta[1] <- theta[1] - alpha * (1/m) * sum(((x%*%theta)- y))
		theta[2] <- theta[2] - alpha * (1/m) * sum(((x%*%theta)- y)*x[,2])
	}
	return(theta)
}
theta <- gradient_descent(data$population, data$profit, 0.02)
theta <- gradient_descent(data$population, data$profit, 0.005)
\end{terminal}

To better illustrate the impact of the learning rate, Fig. \ref{fig3} is presented in which $\theta_i$ values obtained by applying gradient descent model with 500 iterations are plotted for different values of $\alpha$.

\begin{figure}\centering
\includegraphics[width=0.8\textwidth]{\imgDirectory/umb-cs638-2016s-hw02-05.png}
\caption{$\theta_0$ and $\theta_1$ values obtained from gradient descent algorithm for different learning rates and fixed number of iterations}\label{fig3}
\end{figure}

We can also investigate changes in normalized error of coefficient values obtained by gradient descent algorithm for different learning rates, as shown in Fig. \ref{fig4}.

\begin{figure}\centering
\includegraphics[width=0.8\textwidth]{\imgDirectory/umb-cs638-2016s-hw02-06.png}
\caption{Normalized error of gradient descent algorithm for different learning rates with fixed number of iterations}\label{fig4}
\end{figure}

As is clearly deducted from Fig. \ref{fig4}, if the learning rate $\alpha$ is too small, more iterations will be needed to achieve the same level of accuracy.
To visualize this point, Fig. \ref{fig5} is provided where number if iterations to achieve errors of less than 1\% (compared to values obtained in Eq. \ref{eq2}) is plotted for different learning rates $\alpha$.

\begin{figure}\centering
\includegraphics[width=0.8\textwidth]{\imgDirectory/umb-cs638-2016s-hw02-07.png}
\caption{Number of required iterations for different learning rates to achieve the same level of accuracy}\label{fig5}
\end{figure}

\newpage

\subsubsection*{Linear Regression Model to Predict Profit based on Population}

Given the linear regression line shown in Fig. \ref{fig2} and values given in Eq. \ref{eq2}, it is easy to predict profit of a future store, given the population of the city in which it is going to operate.
As an instance, given that Boston has a population of 645966, profit of the store can be projected as follows.

\begin{equation}\label{eq5}
\begin{split}
\mathit{profit}_\mathit{Boston} & = \theta_0 + \theta_1 \times \mathit{population}_\mathit{Boston} \\
 & = -3.89578 + 1.19303 * 64.5966 \\
 & = 73.17014
\end{split}
\end{equation}

Therefore, based on current dataset, a new store for the coffee house chain is projected to have \$731701 profit.

Fig. \ref{fig6} visualizes the dataset along with the newly estimated profit for Boston branch.

\begin{figure}[H]\centering
\includegraphics[width=0.8\textwidth]{\imgDirectory/umb-cs638-2016s-hw02-08.png}
\caption{Dataset including the estimated profit for potential branch in Boston}\label{fig6}
\end{figure}

\cleardoublepage

\section*{Appendices}

\subsection*{Source Code}

\lstset{language=r,tabsize=4}
\lstinputlisting[firstline=1]{\srcDirectory/r/hw02.r}

\end{document}


\section{Model}

Let index $i$ runs through
users, index $j$ runs through items, index $k$ runs through topics,
and index $n$ runs through terms in an item. Let $M, N, K$ and $W$ denote
the numbers of users, items, topics and distinct terms in the
vocabulary, respectively. $W_j$ denotes the number of terms in item
$j$ (with duplicate terms preserved). We also abuse the notation a
little by letting $x_i$, $x_j$ and $x_{ij}$ denote the feature vectors
for user $i$, item $j$ and the dyad $(i,j)$, respectively.
The model is specified in the following table.\\

\noindent
\begin{tabular}{lllr}
\hline
	\multicolumn{4}{c}{{\bf LDA-based Regression Latent Factor Model}} \\
\hline
	\multicolumn{4}{c}{\vspace{-0.1in}} \\
{\bf Rating:} &
	\multicolumn{2}{l}{$y_{ij} \sim \mathcal{N}(m_{ij}, \sigma^2), \textrm{or}$
	~~~ (Gaussian)} & \\
	%~$[y_{ij} | X_{ij}, \delta_{ij}, \Theta_1]$
 	&
	\multicolumn{2}{l}{$y_{ij} \sim \textrm{Bernoulli}(m_{ij})$
	~~~~ (Logistic)} & \\
	\vspace{0.07in}
	& \multicolumn{2}{l}{
	$l(m_{ij}) = (x_{ij}^{\prime}\, b) \gamma_i  + \alpha_i + \beta_j +
					 u_{i}^{\prime} \, v_{j} +
					 s_{i}^{\prime} \, \bar{z}_{j}$
	} &  \\
{\bf User factors:}
& 	$\alpha_i = g_{0}^{\prime}x_i + \epsilon_{i}^{\alpha}$,
		& $\epsilon_{i}^{\alpha} \sim \mathcal{N}(0,a_{\alpha})$ &  \\
& 	$\gamma_i = c_{0}^{\prime}x_i + \epsilon_{i}^{\gamma}$,
		& $\epsilon_{i}^{\gamma} \sim \mathcal{N}(1,a_{\gamma})$ &  \\
& 	$u_i = G x_i + \epsilon_{i}^{u}$,
		& $\epsilon_{i}^{u} \sim \mathcal{N}(\bm{0},A_u)$ & \\
& 	$s_i = H x_i + \epsilon_{i}^{s}$,
		& $\epsilon_{i}^{s} \sim \mathcal{N}(\bm{0},A_s)$ & \vspace{0.07in} \\
{\bf Item factors:}
& 	$\beta_j = d_{0}^{\prime}x_j + \epsilon_{j}^{\beta}$,
		& $\epsilon_{j}^{\beta} \sim \mathcal{N}(0,a_{\beta})$ & \\
&  $v_j = D x_j + \epsilon_{j}^{v}$,
	   & $\epsilon_{j}^{v} \sim \mathcal{N}(\bm{0},A_v)$ & \\
& 	$\bar{z}_{j} = \sum_n z_{jn} ~/~ W_j$
		& &  \vspace{0.07in}\\
{\bf Topic model:}
& 	$\theta_j \sim \textrm{Dirichlet}(\lambda)$
		& (Topic distribution of item $j$) & \\
& 	$\Phi_k \sim \textrm{Dirichlet}(\eta)$
		& (Word distribution of topic $k$) & \\
&  $z_{jn} \sim \textrm{Multinom}(\theta_j)$
		& (Topic of the $n$th word in $j$) & \\
&  $w_{jn} \sim \textrm{Multinom}(\Phi \, z_{jn})$
		& ($n$th observed word in $j$) &  \vspace{0.07in}\\ \hline
\end{tabular}
\\

\noindent {\bf Notes:}
\begin{itemize}
\item $y_{ij}$ is the observed rating given by user $i$ to item $j$.

\item $l(m_{ij}) = m_{ij}$ for Gaussian; $l(m_{ij}) = \log\frac{m_{ij}}{1-m_{ij}}$ for Logistic.

\item $x_{ij}$, $x_i$ and $x_j$ are the dyadic, user and item feature vectors for user $i$ and item $j$, respectively.

\item $\alpha_i$ and $\beta_j$ are the main factors for user $i$ and item $j$, respectively, intuitively representing the ``default'' rating that user $i$ would give to a random item and the overall popularity of item $j$. $u_i$ and $v_j$ are latent-factor vectors. We call the length of a latent-factor vector the number of latent dimensions.

\item $z_{jn}$ is a vector of zeros except for one position being one, which is the position representing the topic of the word. $\Phi = [\Phi_1, ..., \Phi_K]$ and $\Phi \, z_{jn} = \Phi_k$ such that $z_{jnk} = 1$. $\eta$ is a scalar for the symmetric Dirichlet prior, but $\lambda$ is a vector.

\item $\bar{z}_j$ represents the probability distribution of topics in item $j$, and $s_i$ represents user $i$'s affinity to different topics. They are vectors of length equal to the number of topics. Notice that $x_{ij}$ may include TF/IDF similarity
between the profile of user $i$ (e.g., top 200 entities in the items
that user $i$ frequently clicks) and the text of item $j$, and other
IR similarity measures between user $i$ and item $j$.  Thus,
$s_{i}^{\prime} \, \bar{z}_{j}$ captures user $i$'s affinity to
relatively coarse-grained topics, while $x_{ij}^{\prime}$ captures
user $i$'s affinity to fine-grained topics/entities. $b$ quantifies
how important each element of $x_{ij}$ is. For fine-grained
topic affinity, this model does not try to fit regression coefficients
because of data sparseness at fine granularities.

\item $\gamma_i$ is a scaling factor that gives the relative
importance of find-grained affinity $x_{ij}$ to coarse-grained
affinity $s_{i}^{\prime} \, \bar{z}_{j}$. Intuitively, this relative
importance should be different for different users. To prevent from
adding too many factors (instead of replacing $b$ by $b_i$, which is a
vector, for each user), we only add a single scaling factor $\gamma_i$
for each user.  If $x_{ij}$ only has one element, then we just set $b$
to 1. Whether we really need $\gamma_i$ is not clear. I just include this so that we can try this out.

\item $b$, $g_0$, $d_0$ and $c_0$ are regression weight vectors. $G$, $D$ and $H$ are regression weight matrices.

\item $a_{\alpha}$, $a_{\beta}$ and $a_\gamma$ are unknown variances. $A_u$, $A_v$ and $A_s$ are unknown variance-covariance matrices.

\end{itemize}