\section{Methodology}
%Description of D3ploy
In \Cyclus, developers have the option to design
agents using C++ or Python.
The \deploy \texttt{Institution} agent was
implemented in Python to enable the use of
well-developed time series forecasting Python packages.

During a \Cyclus simulation, at every time step, \deploy
predicts the supply and demand of each commodity for the next time
step.
It is assumed that facility deployment occurs
within one time step (month).
Commodities refer to materials in the nuclear fuel cycle such as
reactor fuel.
Upon undersupply for any commodity,
\deploy deploys facilities to meet its predicted demand.
Therefore, if the simulation begins with user-defined power
demand, \deploy deploys reactors to meet power demand,
followed by enrichment facilities to meet fuel demand, and so on,
to create the supply chain.
Based on the demand and supply trends of each commodity,
\deploy predicts their
future demand and supply, and deploys facilities
accordingly to meet the future demand to prevent demand
from surpassing supply.
Figure \ref{fig:flow} shows the logical flow of \deploy
at every time step.
In subsequent subsections, we describe how to set up a
transition scenario using \deploy and the input parameters
\deploy accepts.

\begin{figure}[]
	\centering
	\resizebox{0.8\textwidth} {0.8\height}{
    \begin{tikzpicture}[node distance=2.5cm]
    \tikzstyle{every node}=[font=\large]
	\node (Start) [bblock] {\textbf{Start time step ($t$).}};
	\node (Predict) [bblock, below of=Start] {\textbf{Calculate predicted $D(t+1)$ and $S(t+1)$ for a commodity}};
	\node (IsThere) [oblock, below of=Predict]{\textbf{$U(t+1) = S(t+1)-D(t+1)$}};
	\node (Deploy) [bblock, below of=IsThere, xshift = -3.5cm]{\textbf{Deploy Facilities}};
    \node (NoDeploy) [bblock, right of=Deploy, xshift = 3.5cm]{\textbf{No Deployment} };
    \node (All) [oblock, below of=Deploy, xshift = 3.5cm] {\textbf{Has $D(t+1)$ and \\ $S(t+1)$ been calculated for all commodities?}};
    \node (End) [bblock, below of=All] {\textbf{Proceed to next time step.}};

	\draw [arrow] (Start) -- (Predict);
	\draw [arrow] (Predict) -- (IsThere);
    \draw [arrow] (IsThere) -- node[anchor=east] {$U(t+1) <$ buffer} (Deploy);
    \draw [arrow] (IsThere) -- node[anchor=west] {$U(t+1) \geq$ buffer} (NoDeploy);
    \draw [arrow] (Deploy) -- (All);
    \draw [arrow] (NoDeploy) -- (All);
    \draw [arrow] (All) -- node[anchor=west] {yes} (End);
    \draw [arrow] (All) -- ([shift={(-4cm,0.8cm)}]All.south west)-- node[anchor=east] {no} ([shift={(-4cm,-0.8cm)}]Predict.north west)--(Predict);
    \draw [arrow] (End) |-([shift={(3cm,-0.5cm)}]End.south east)-- ([shift={(3cm,0.5cm)}]Start.north east)-|(Start);
	\end{tikzpicture}
	}
    \caption{\deploy logic flow at every time step in \Cyclus \cite{chee_demonstration_2019}.}
    \label{fig:flow}
\end{figure}

\deploy aims to minimize the undersupply of power:
\begin{align}
	\label{eq:pow}
	\textrm{obj} &= \min \sum_{t=1}^{t_{f}} |D_{t,p}-S_{t,p}|.
    \intertext{where:}
    t_f &= \mbox{Number of time steps [months]} \nonumber \\
    t &= \mbox{time [month]} \nonumber \\
	D &= \mbox{Demand} \nonumber\\
	S &= \mbox{Supply} \nonumber\\
	p &= \mbox{power [MW]} \nonumber
\end{align}
The sub-objectives are to minimize the number of time
steps of undersupply or under-capacity of any
commodity:
\begin{align}
	\label{eq:sub1}
    obj &= min \sum_{c=1}^{M}\sum_{t=1}^{t_f} |D_{t,c}-S_{t,c}|, \\
    \intertext{and to minimize excessive oversupply of all commodities: }
    obj &= min \sum_{c=1}^{M}\sum_{t=1}^{t_f} |S_{t,c}-D_{t,c}|. \\
    \intertext{where:}
    c &= \mbox{commodity type} \nonumber \\
	M &= \mbox{Number of commmodities} \nonumber
\end{align}

Minimizing excessive oversupply
reflects reality, in which utilities ensure grid availability
by ensuring power plants are never short of fuel while
avoiding expensive storage of excess fuel.
Nuclear fuel cycle simulations often face power shortages
due to lack of viable fuel, despite having sufficient installed
reactor capacity.
Using \deploy to automate the deployment of supporting
facilities prevents this.

\subsection{Structure}
Front-end facilities
meet the demand for commodities they produce, whereas back-end
facilities meet supply for the commodities they demand.
Therefore, in \deploy two distinct institutions control
front-end and back-end fuel cycle facilities:
\texttt{DemandDrivenDeploymentInst} and
\texttt{SupplyDrivenDeploymentInst}, respectively.
For example, when a reactor facility
demands fuel, \texttt{DemandDriven-}

\noindent
\texttt{DeploymentInst}
deploys fuel fabrication facilities to create fuel
supply.
For back-end facilities, the reactor generates spent fuel, and
\texttt{SupplyDrivenDeploymentInst} deploys
used fuel storage facilities to create capacity to store the spent fuel.
Figure \ref{fig:insts} depicts a simple once-through fuel cycle
and the \texttt{Institution} type governing each
facility's deployment.

\begin{figure}[]
	\centering
	\resizebox{\textwidth}{!}{
	\trimbox{0cm -.5cm 0cm 0cm}{
\begin{tikzpicture}[node distance=2.7cm,auto,>=latex']
	\tikzstyle{every node}=[font=\scriptsize]
    \node [bbslock] (a) {\textbf{Mine}};
    \node [bbslock] (b) [right of=a] {\textbf{Enrichment \\ Facility}};
	\node [bbslock] (c) [right of=b] {\textbf{Reactor}};
	\node [obslock] (d) [right of=c] {\textbf{Cooling \\ Pool}};
	\node [obslock] (e) [right of=d] {\textbf{Repository}};
    \path[->] (a) edge node {\shortstack{Natl \\ U}} (b);
    \draw [arrow] (b) -- ([xshift=0.5cm,yshift=0.9cm]b.north west)-- node[anchor=south] {Demand for Natl U} ([shift={(0cm,0.9cm)}]a.north)--(a);
    \draw [arrow] (c) -- ([shift={(0.5cm,0.9cm)}]c.north west)-- node[anchor=south] {Demand for Fuel} ([shift={(0cm,0.9cm)}]b.north)--(b);
    \draw [arrow] (c) -- ([shift={(1.5cm,0.9cm)}]c.north west)-- node[anchor=south] {\shortstack{Demand for Cooling \\ Pool Capacity}} ([shift={(0cm,0.9cm)}]d.north)--(d);
	\draw [arrow] (d) -- ([shift={(1.5cm,0.9cm)}]d.north west)-- node[anchor=south] {\shortstack{Demand for \\ Repository Capacity}} ([shift={(0cm,0.9cm)}]e.north)--(e);
    \draw[->] (b) edge node {Fuel} (c) ;
	\draw[->] (c) edge node {\shortstack{Used \\ Fuel}} (d) ;
	\draw[->] (d) edge node {\shortstack{Cooled \\ Used \\ Fuel}} (e) ;
\end{tikzpicture}
	}}

\resizebox{0.5\textwidth}{!}{
    \fbox{\begin{tabular}{ll}
        \textcolor{illiniblue}{$\blacksquare$} & Deployed by \texttt{DemandDrivenDeploymentInst}\\
        \textcolor{illiniorange}{$\blacksquare$} & Deployed by \texttt{SupplyDrivenDeploymentInst}
		\end{tabular}}}
		\caption{Simple once-through fuel cycle depicting which facilities are deployed by
		\texttt{DemandDrivenDeploymentInst} and \texttt{SupplyDrivenDeploymentInst}.}
\label{fig:insts}
\end{figure}

\subsubsection{Deployment-Driving Method}
\label{sec:ddm}
To prevent over-deployment of facilities with an intermittent
supply such as reactors that require refueling, and
to prevent infinite deployment of a facility that demands
a commodity no longer available in the simulation,
we introduced the capability to deploy facilities
based on the difference between predicted demand and installed capacity.
The user may deploy facilities based on the difference
between predicted demand and predicted supply, \textit{or}
predicted demand and installed capacity.
For example, a reprocessing plant that fabricates Sodium-Cooled Fast Reactor
(SFR) fuel demands for Pu after depletion of the existing Pu inventory and
decommissioning of the \glspl{LWR} that produce it.
If we used the deployment-driving method driven by
the difference in predicted demand and predicted supply, this results in
infinite deployment of reprocessing facilities in a futile attempt
to produce SFR fuel, crashing the simulation.
Instead, if we use the deployment-driving method driven by the
difference in predicted demand and installed capacity, only one reprocessing
facility will be deployed, the simulation will finish, and the user will see that
a large Pu inventory must be accumulated.
Therefore, using the deployment-driving method that deploys facilities based on
the difference between predicted demand and installed capacity is ideal for most
transition scenarios.

\subsection{Input Variables}
Table \ref{tab:inputs} lists and gives examples of the input
variables \deploy accepts.
The user must define the following input variables:
\begin{enumerate}
\item \textbf{The available facilities for \deploy to deploy in the simulation and their respective capacities.}
Users must define the facilities they want \deploy to deploy. It is the user's responsibility to
ensure the defined facilities create a supply chain to produce the demand driving commodity.
\item \textbf{The demand driving commodity and its demand equation.} For most simulations, the demand driving
commodity is power. The demand equation is defined by a mathematical equation with units of MW. For example,
a constant power demand equation is $10000$, while a linearly increasing power demand equation is $100t$.
\item \textbf{The deployment driving method}. This input variable is described in Section \ref{sec:ddm}.
\item \textbf{The prediction method}. This input variable is described in Section \ref{sec:pm}.
There are also optional input variables:
\item \textbf{Supply/capacity buffers for individual commodities.} This input variable is described in
section \ref{sec:buf}.
\item \textbf{Facility preferences.} This input variable is described in section \ref{sec:pref}.
\item \textbf{Facility fleet shares.} This input variable is described in section \ref{sec:pref}.
\end{enumerate}

\begin{table}[]
	\centering
    \caption{\deploy's required and optional input parameters with examples.}
    \label{tab:inputs}
        \begin{tabular}{l|ll}
        \hline
            & \textbf{Input Parameter}                                                           & \textbf{Examples}                                                                                \\ \hline
            \multirow{5}{*}{\textbf{Required}} & Demand driving commodity                                                           & Power                                                                                \\ \cline{2-3}
                                                      & Demand equation [MW]                                                                   & P(t) = $10000, sin(t), 10000t$                                                                                \\ \cline{2-3}
                                                      & Available Facilities                                                             & Mine, \gls{LWR}, Repository, etc.                                                                                \\ \cline{2-3}
                                                      & Capacities of the facilities                                                       & 3000 kg, 1000 MW, 50000 kg                                                                                \\ \cline{2-3}
                                                      & Prediction method                                                                  & \begin{tabular}[c]{@{}l@{}}Power: Fast Fourier Transform\\ Fuel: Moving Average\\ Spent fuel: Moving Average\end{tabular} \\ \cline{2-3}
                                                      & Deployment driven by & Installed Capacity                                                                                \\ \hline
            \multirow{4}{*}{\textbf{Optional}} & Supply/Capacity Buffer type                                                                        & Absolute                                                                                \\ \cline{2-3}
                                                      & Supply/Capacity Buffer size                                                                        & \begin{tabular}[c]{@{}l@{}}Power: 3000 MW\\ Fuel: 0 kg \\ Spent fuel: 0 kg\end{tabular}                                   \\ \cline{2-3}
                                                      & Facility preferences [month]                                                              & \begin{tabular}[c]{@{}l@{}}\gls{LWR} = 100-t\\ SFR = t-99 \end{tabular}          \\ \cline{2-3}
                                                      & Fleet share percentage [\%]                                                            & \begin{tabular}[c]{@{}l@{}}MOX \gls{LWR} = 85\%\\ SFR = 15\% \end{tabular}          \\ \hline
                    \end{tabular}
\end{table}
\subsubsection{Supply/Capacity Buffer}
\label{sec:buf}
The user has the option to specify a
supply buffer for each commodity; \deploy accounts for the buffer when
calculating predicted demand and deploys facilities accordingly.
The buffer is defined as a percentage:
\begin{align}
	S_{pwb} &= S_{p}(1+d)
\intertext{or an absolute value:}
    S_{pwb} &= S_{p}+b
\end{align}
    \begin{align}
	\intertext{where:}
	S_{pwb} &= \mbox{predicted supply/capacity with buffer} \nonumber\\
	S_p &= \mbox{predicted supply/capacity} \nonumber\\
	d &= \mbox{buffer's percentage value in decimal form} \nonumber\\
	b &= \mbox{buffer's absolute value} \nonumber
\end{align}

Using the buffer capability and
installed capacity to drive facility deployment in a transition
scenario simulation will effectively minimize undersupply of a
commodity while avoiding excessive oversupply.
This is demonstrated in Section \ref{sec:demo}.

\subsection{Facility Preference and Fleet Share}
\label{sec:pref}
The user can define time-dependent preference equations to facilities'
that supply the same commodity.
If there are two reactor types, \glspl{LWR} and \glspl{SFR}, in a simulation,
the user can make use of time-dependent
preferences to make the simulation deploy \glspl{LWR} at earlier times
in the simulation, and deploy SFRs at later times in the
simulation when there is a power demand.
In Table \ref{tab:inputs},
the user defined that the \gls{LWR} has a preference of $100-t$, while
the SFR has a preference of $t-99$.
Figure \ref{fig:prefplot} depicts how the preference for each reactor changes
with time.
When there is a power undersupply, \deploy will deploy the reactor that has a
larger preference at that time step.
At time step 100, \gls{LWR} preference is 0, while SFR preference is 1;
therefore an SFR is deployed if there is a power shortage.
Thus, the transition occurs at the $100^{th}$ time step.

\begin{figure}[]
	\begin{center}
		\includegraphics[width=\linewidth]{./figures/prefplot}
	\end{center}
		\caption{\deploy has a $100-t$ preference for \glspl{LWR} and a $t-99$ preference for SFRs.
		When there is a power undersupply, \deploy will deploy the reactor that has a
		larger preference at that time step.}
	\label{fig:prefplot}
\end{figure}

The user also has the option to specify percentage-share for facilities
that provide the same commodity.
For example, if there are two reactor types, \gls{MOX} \glspl{LWR} and SFRs, in a simulation,
the user can make use of percentage-share specifications to determine the
percentage of power supplied by each reactor.
When MOX \gls{LWR} has a share of $s\%$ and
\gls{SFR} has a share of $(100-s)\%$,
MOX \gls{LWR} deployment constrains to $s\%$ of total power demand
and SFR deployment constrains to $(100-s)\%$ of total power demand.

The transition year is selected by customizing facility
preferences to prefer advanced reactors at that year.
The fleet-share percentage determines the
share of each type of reactor to transition to.
Figure \ref{fig:deployflow} shows the logical flow of
which facility \deploy deploys when there are multiple facilities
offering the same commodity.

\begin{figure}[]
	\centering
	\resizebox{0.9\textwidth} {0.8\height}{
    \begin{tikzpicture}[node distance=3cm]
    \tikzstyle{every node}=[font=\large]
    \node (fs)[olblock]{\textbf{Are there fleet share constraints?}};
    \node (fsyes) [bbmlock, below of=fs, xshift = -3.5cm] {\textbf{Deploy facilities to meet fleet share $\%$}};
    \node (pref) [olblock, right of=fsyes, xshift = 3.5cm]{\textbf{Are there facility \\ preferences?}};
    \node (prefyes) [bbmmlock, below of=pref, xshift = -3cm] {\textbf{Deploy facilities in preference order to meet their fleet share \%}};
    \node (prefno) [bbmlock, right of=prefyes, xshift = 3cm, yshift=-0.05cm] {\textbf{Deploy facilities to minimize total no. of facilities and minimize oversupply.}};
	\draw [arrow] (fs) -- node[anchor=east] {yes} (fsyes);
    \draw [arrow] (fs) -- node[anchor=east] {no} (pref);
    \draw [arrow] (pref) -- node[anchor=east] {yes} (prefyes);
    \draw [arrow] (pref) -- node[anchor=east] {no} (prefno);
	\end{tikzpicture}}

    \caption{Logical flow of how \deploy
	selects which facility to deploy when there are multiple facilities
	offering the same commodity.}
	\label{fig:deployflow}
\end{figure}

\subsection{Prediction Methods}
\label{sec:pm}
\deploy records supply and demand at each time step for all
commodities. Time-series data informs \deploy's time series
forecasting methods which predict future supply and demand for each
commodity.
The time series forecasting methods investigated include non-optimizing,
deterministic-optimizing, and stochastic-optimizing methods.
Non-optimizing methods are techniques that harness
simple moving average and autoregression concepts which use
historical data to infer future supply and demand values.
Deterministic-optimizing and stochastic-optimizing
methods are techniques
that use an assortment of more sophisticated time series forecasting
concepts to predict future supply and demand values.
Deterministic-optimizing methods give deterministic solutions,
while stochastic-optimizing methods give stochastic solutions.

Depending on the scenario in question, each forecasting method
offers distinct benefits and disadvantages.
The various methods are compared for each type of simulation
to determine the most effective prediction method for
a given scenario.
The following sections describe the prediction methods.

\subsubsection{Non-Optimizing Methods}
Non-optimizing methods include: Moving Average (\texttt{MA}),
Autoregressive Moving Average (\texttt{ARMA}), and
Autoregressive Heteroskedasticity (\texttt{ARCH}).
The \texttt{MA} method calculates the average of
a user-defined number of previous entries in a commodity's
time series and returns it as the predicted value
(equation \ref{eq:ma}).

\begin{align}
	\label{eq:ma}
	PV &= \frac{\sum_{n=1}^N V_n}{n}
    \intertext{where:}
    PV &= \mbox{predicted value} \nonumber \\
	V_n &= \mbox{time series value} \nonumber\\
	N &= \mbox{length of time series} \nonumber
\end{align}

The \texttt{ARMA} method combines moving average and
autoregressive models (equation \ref{eq:arma}).
The first term is a constant, the second term is
white noise, the third term is the autoregressive
model, and the fourth term is the moving average
model.
The \texttt{ARMA} method is more accurate than the
\texttt{MA} method
because of the inclusion of the autoregressive term:
\begin{align}
	\label{eq:arma}
	X_t &= c + \epsilon_t +
	\sum_{i=1}^p\varphi_i X_{t-i} +
	\sum_{i=1}^q\theta_i\epsilon_{t-i}.
	\intertext{where:}
    c &= \mbox{a constant} \nonumber\\
    \epsilon_t &= \mbox{error terms (white noise)} \nonumber\\
    \varphi &= \mbox{the autoregressive model’s parameters} \nonumber\\
    \theta &= \mbox{the moving average model’s parameters} \nonumber \\
    p &= \mbox{order of the autoregressive polynomial} \nonumber \\
    q &= \mbox{order of the moving average polynomial} \nonumber
\end{align}

The \texttt{ARCH} method models time series data by describing the
variance of the current
error term as a function of the sizes of the previous time periods'
error terms \cite{engle_autoregressive_1982}.
This allows the method to support changes in the time dependent volatility,
such as increasing and decreasing volatility in the same series
\cite{engle_autoregressive_1982}.
The \texttt{ARCH} method is
better than the \texttt{ARMA} method for volatile
time-series data \cite{flanagan_methods_2019}.
The StatsModels \cite{seabold_statsmodels:_2010}
Python package is used to implement \texttt{ARMA} and
\texttt{ARCH} methods in \deploy.

\subsubsection{Deterministic-Optimizing Methods}
Deterministic methods include
Fast Fourier Transform (\texttt{FFT}),
Polynomial Fit (\texttt{POLY}),
Exponential Smoothing (\texttt{EXP-SMOOTHING}),
and Triple Exponential Smoothing (\texttt{HOLT-WINTERS}).
The \texttt{FFT} method uses the fast Fourier transform
algorithm to map a time series into the frequency domain.
The algorithm returns complex numbers from which frequency,
amplitude, and phase is extracted.
Future demand and supply values are predicted by summing
the significant components, then using the inverse
Fourier transform method to return it into a usable form.
The discrete Fourier transform (DFT) transforms a sequence of
N complex numbers ($X_k$) into another sequence of complex numbers
($x_n$) \cite{rao_fast_2011}:
\begin{align}
	\label{eq:fft}
	X_k &= \sum_{n=0}^{N-1}x_n e^{-i2\pi kn/N}.
    \intertext{where:}
    X &= \mbox{sequence of complex numbers} \nonumber \\
    k &= 0,...,N-1 \nonumber\\
    N &= \mbox{No. of complex numbers} \nonumber\\
    x &= \mbox{sequence of complex numbers} \nonumber \\
    n &= 0,...,N-1 \nonumber
\end{align}

\noindent
This method is implemented in \deploy using the
SciPy \cite{jones_scipy:_2016} Python package.

The \texttt{POLY} method fits the time series data
with a user-defined $n^{th}$ degree polynomial and uses
the fitted trend-line to determine future demand and
supply values:

\begin{align}
    Y_t &= \beta_0 + \sum_{n=1}^N \beta_n t^n + \varepsilon \\
    \intertext{where:}
    t &= \mbox{time index} \nonumber \\
    n &= \mbox{polynomial order} \nonumber \\
    \beta &= \mbox{fitted parameters} \nonumber \\
    \varepsilon &= \mbox{unobserved random error} \nonumber
\end{align}

\noindent
This method was implemented in \deploy using the
NumPy \cite{oliphant_guide_2006} Python package.

The \texttt{EXP-SMOOTHING} and \texttt{HOLT-WINTERS}
methods use a weighted average
of time-series data with exponentially decaying weights
for older time series values \cite{hyndman_forecasting:_2018}
to create a model to determine future demand and supply values.
The \texttt{EXP-SMOOTHING} method excels in
modeling univariate time series data without trend or seasonality
\cite{hyndman_forecasting:_2018}:

\begin{align}
    \label{eq:expsm}
    y_{t+1} &= \alpha y_i + (1-\alpha)y_t. \\
    \intertext{where:}
    y &= \mbox{timeseries value} \nonumber \\
    \alpha &= \mbox{smoothing factor } (0 < \alpha < 1) \nonumber
\end{align}

\noindent
The \texttt{HOLT-WINTERS} method applies triple exponential
smoothing, resulting in higher accuracy when
modeling seasonal time series data
\cite{sematech_engineering_2006}:

\begin{align}
    F_{t+m} &= (S_t +mb_t)I_{t-L+m} \\
    S_t &= \alpha \frac{y_t}{I_{t-L}}+(1-\alpha)(S_{t-1}+b_{t-1}) \nonumber \\
    b_t &= \gamma(S_t-S_{t-1})+)(1-\gamma)b_{t-1} \nonumber \\
    I_t &= \beta \frac{y_t}{S_t} + (1-\beta)I_{t-L} \nonumber \\
    \intertext{where:}
    F &= \mbox{forecast at m periods ahead} \nonumber \\
    t &= \mbox{time period index} \nonumber \\
    L &= \mbox{periods in a season} \nonumber \\
    S &= \mbox{smoothed observation} \nonumber \\
    y &= \mbox{the observation} \nonumber \\
    b &= \mbox{trend factor} \nonumber \\
    I &= \mbox{seasonal index} \nonumber \\
    \alpha, \beta, \gamma &= \mbox{constants} \nonumber
\end{align}

\noindent
The StatsModels \cite{seabold_statsmodels:_2010}
Python package was used to implement the \texttt{EXP-SMOOTHING}
and \texttt{HOLT-WINTERS} methods in \deploy.

\subsection{Stochastic-Optimizing Methods}
We implemented one stochastic-optimizing method: step-wise
seasonal method (\texttt{SW-SEASONAL}).
The method was implemented in \deploy by the \gls{ARIMA}
method in the pmdarima \cite{smith_pmdarima:_2017}
Python package.
The \gls{ARIMA} model is a dependent time series that is
modeled as a linear combination of its own past values
and past values of an error series \cite{institute_sas_1985}:

\begin{align}
    (1-B)^dY_t &= \mu + \frac{\theta(B)}{\phi(B)}a_t \\
    \intertext{where:}
    t &= \mbox{time index} \nonumber \\
    \mu &= \mbox{mean term} \nonumber \\
    B &= \mbox{backshift operator, such that } BX_t = X_{t-1} \nonumber \\
    d &= \mbox{no. of roots} \nonumber \\
    Y &= \mbox{timeseries data} \nonumber \\
    \phi(B) &= \mbox{autoregressive operator} \nonumber \\
    \theta(B) &= \mbox{moving average operator} \nonumber \\
    a_t &= \mbox{random error} \nonumber
\end{align}


\section{CurryVerify: A Tool to Support the Verification of Curry Programs}
\label{sec-curry2verify}

CurryVerify\index{CurryVerify}\index{verifying programs}\index{program!verification}
is a tool that supports the verification of Curry programs
with the help of other theorem provers or proof assistants.
Basically, CurryVerify extends CurryCheck (see Section~\ref{sec-currycheck}),
which tests given properties of a program,
by the possibility to verify these properties.
For this purpose, CurryVerify translates properties
into the input language of other theorem provers or proof assistants.
This is done by collecting all operations directly or indirectly
involved in a given property and translating them together with
the given property.

Currently, only Agda \cite{Norell09} is supported as
a target language for verification (but more target languages
may be supported in future releases).
The basic schemes to translate Curry programs into Agda programs
are presented in \cite{AntoyHanusLibby17EPTCS}.
That paper also describes the limitations of this approach.
Since Curry is a quite rich programming language,
not all constructs of Curry are currently supported
in the translation process (e.g., no case expressions,
local definitions, list comprehensions, do notations, etc).
Only a kernel language, where the involved rules
correspond to a term rewriting system, are translated into Agda.
However, these limitations might be relaxed in future releases.
Hence, the current tool should be considered as a first prototypical
approach to support the verification of Curry programs.

\subsection{Installation}

The current implementation of CurryVerify is a package
managed by the Curry Package Manager CPM
(see also Section~\ref{sec-cpm}).
Thus, to install the newest version of CurryVerify, use the following commands:
%
\begin{curry}
> cypm update
> cypm install verify
\end{curry}
%
This downloads the newest package, compiles it, and places
the executable \code{curry-verify} into the directory \code{\$HOME/.cpm/bin}.
Hence it is recommended to add this directory to your path
in order to execute CurryVerify as described below.

\subsection{Basic Usage}

To translate the properties of a Curry program stored
in the file \code{prog.curry} into Agda,
one can invoke the command\pindex{curry-verify}\pindex{verify}
%
\begin{curry}
curry-verify prog
\end{curry}
%
This generates for each property $p$ in module \code{prog}
an Agda program \ccode{TO-PROVE-$p$.agda}.
If one completes the proof obligation in this file,
the completed file should be renamed into
\ccode{PROOF-$p$.agda}.
This has the effect that CurryCheck does not test this property again
but trusts the proof and use this knowledge to simplify other tests.

As a concrete example, consider the following Curry module \code{Double},
shown in Figure~\ref{fig:double-curry},
which uses the Peano representation of natural numbers
(module \code{Nat}) to define an operation to double the value
of a number, a non-deterministic operation \code{coin}
which returns its argument or its incremented argument,
and a predicate to test whether a number is even.
Furthermore, it contains a property specifying that
doubling the coin of a number is always even.

\begin{figure}[t]
\begin{curry}

module Double(double,coin,even) where

import Nat
import Test.Prop

double x = add x x

coin x = x ? S x

even Z         = True
even (S Z)     = False
even (S (S n)) = even n

evendoublecoin x = always (even (double (coin x)))

\end{curry}
\caption{Curry program \code{Double.curry}\label{fig:double-curry}}
\end{figure}

In order to prove the correctness of this property,
we translate it into an Agda program by executing
%
\begin{curry}
> curry-verify Double
$\ldots$
Agda module 'TO-PROVE-evendoublecoin.agda' written.
If you completed the proof, rename it to 'PROOF-evendoublecoin.agda'.
\end{curry}
%
The Curry program is translated with
the default scheme (see further options below) based on
the ``planned choice'' scheme, described in \cite{AntoyHanusLibby17EPTCS}.
The result of this translation is shown in
Figure~\ref{fig:to-prove-evendoublecoin}.

\begin{figure}[t]
\begin{curry}
-- Agda program using the Iowa Agda library

open import bool

module TO-PROVE-evendoublecoin
  (Choice : Set)
  (choose : Choice $\to$ ${\mathbb B}$)
  (lchoice : Choice $\to$ Choice)
  (rchoice : Choice $\to$ Choice)
  where

open import eq
open import nat
open import list
open import maybe

---------------------------------------------------------------------------
-- Translated Curry operations:

add : ${\mathbb N}$ $\to$ ${\mathbb N}$ $\to$ ${\mathbb N}$
add zero x = x
add (suc y) z = suc (add y z)

coin : Choice $\to$ ${\mathbb N}$ $\to$ ${\mathbb N}$
coin c1 x = if choose c1 then x else suc x

double : ${\mathbb N}$ $\to$ ${\mathbb N}$
double x = add x x

even : ${\mathbb N}$ $\to$ ${\mathbb B}$
even zero = tt
even (suc zero) = ff
even (suc (suc x)) = even x

---------------------------------------------------------------------------

evendoublecoin : (c1 : Choice) $\to$ (x : ${\mathbb N}$) $\to$ (even (double (coin c1 x))) $\equiv$ tt
evendoublecoin c1 x = ?

\end{curry}
\caption{Agda program \code{TO-PROVE-evendoublecoin.agda}\label{fig:to-prove-evendoublecoin}}
\end{figure}

The Agda program contains all operations involved in the property
and the property itself.
Non-deterministic operations, like \code{coin}, have an additional
additional argument of the abstract type \code{Choice}
that represents the plan to execute some non-deterministic branch
of the program. By proving the property for all possible branches
as correct, it universally holds.

In our example, the proof is quite easy. First, we prove
that the addition of a number to itself is always even
(lemma \code{even-add-x-x}, which uses an auxiliary lemma
\code{add-suc}). Then, the property is an immediate consequence
of this lemma:
%
\begin{curry}
add-suc : $\forall$ (x y : ${\mathbb N}$) $\to$ add x (suc y) $\equiv$ suc (add x y)
add-suc zero    y = refl
add-suc (suc x) y rewrite add-suc x y = refl

even-add-x-x : $\forall$ (x : ${\mathbb N}$) $\to$ even (add x x) $\equiv$ tt
even-add-x-x zero    = refl
even-add-x-x (suc x) rewrite add-suc x x | even-add-x-x x = refl

evendoublecoin : (c1 : Choice) $\to$ (x : ${\mathbb N}$) $\to$ (even (double (coin c1 x))) $\equiv$ tt
evendoublecoin c1 x rewrite even-add-x-x (coin c1 x) = refl
\end{curry}
%
As the proof is complete, we rename this Agda program
into \code{PROOF-evendoublecoin.agda} so that the proof
can be used by further invocations of CurryCheck.

\subsection{Options}

The command \code{curry-verify} can be parameterized
with various options.
The available options can also be shown by executing
\begin{curry}
curry-verify --help
\end{curry}
The options are briefly described in the following.

\begin{description}
\item{\code{-h}, \code{-?}, \code{--help}}
These options trigger the output of usage information.

\item{\code{-q}, \code{--quiet}}
Run quietly and produce no informative output.
However, the exit code will be non-zero if some translation error occurs.

\item{\code{-v[$n$]}, \code{--verbosity[=$n$]}}
Set the verbosity level to an optional value.
The verbosity level \code{0} is the same as option \code{-q}.
The default verbosity level \code{1} shows the translation progress.
The verbosity level \code{2} (which is the same as omitting the level)
shows also the generated (Agda) program.
The verbosity level \code{3} shows also more details about
the translation process.

\item{\code{-n}, \code{--nostore}}
Do not store the translated program in a file but show it only.

\item{\code{-p $p$}, \code{--property=$p$}}
As a default, all properties occurring in the source program are
translated. If this option is provided, only property $p$ is translated.

\item{\code{-t $t$}, \code{--target=$t$}}
Define the target language of the translation.
Currently, only $t = \code{Agda}$ is supported, which is also the
default.

\item{\code{-s $s$}, \code{--scheme=$s$}}
Define the translation scheme used to represent Curry programs
in the target language.

For the target \code{Agda}, the following schemes are supported:
\begin{description}
\item[\code{choice}]
Use the ``planned choice'' scheme, see \cite{AntoyHanusLibby17EPTCS}
(this is the default).
In this scheme, the choices made in a non-deterministic computation
are abstracted by passing a parameter for these choices.
\item[\code{nondet}]
Use the ``set of values'' scheme, see \cite{AntoyHanusLibby17EPTCS},
where non-deterministic values are represented in a tree structure.
\end{description}

\end{description}

% LocalWords: CurryCheck


%!TEX root = main.tex
\chapter{Filters}
\label{chap:filters}

\begin{figure}[H]
	\begin{center}
		\includegraphics[width = 14cm]{img/Narciss_Caravaggio.jpg}
		\caption{Caravaggio, Narziss. ad Feedback: Echo liebt Narziss etc.}
		\label{fig:narziss}
	\end{center}
\end{figure}

\begin{center}
\begin{figure}[h!]
\tikzset{concept/.append style={fill={none}}}
\begin{tikzpicture}
  \path[mindmap,concept color=black,text=black]
    node[concept] {Filters}
    [clockwise from=0]
    child[concept color=red!50!black] {
      node[concept] {Systems}
      % }
      [clockwise from=90]
      child { node[concept] {Impulse Response} }
      child { node[concept] {Difference Equation} }
      child { node[concept] {Transfer Function} }
      % child { node[concept] {pro\-gramming languages} }
      % child { node[concept] {software engineer\-ing} }
    }
    child[concept color=blue] {
      node[concept] (IIR) {IIR}
      [clockwise from=-30]
    }
    child[concept color=red] { node[concept] (FIR){FIR} }
    child[concept color=orange] { node[concept] (sd) {Sound design Challenge} };

\begin{pgfonlayer}{background}
    \draw [circle connection bar]
      (fm) edge (sd)
      (fm) edge (pm);
  \end{pgfonlayer}

\end{tikzpicture}
\caption{Lecture Contents}
\end{figure}
\end{center}

What is a filter? We use filters a lot. We often need to shape the spectrum of a signal. Be it for technical reasons (DC-Offset removal, Anti-aliasing filters, crossovers, interpolation, ...) or for aesthetic ones (EQ-ing, subtractive synthesis)\\
Please take a moment and seriously ask yourself, knowing what you know about signals, knowing what we can do with a computer: How do we actually do this? What is a digital Filter? This is what this chapter will try to explain.\\

\section{Seeing Frequency Content in the Time Domain}

Let's first try to get a feel for how signals \textit{look}. It's a lot easier to understand how a filter works afterwards. This might be obvious but let's state clearly:

\begin{framed}
	High frequency signals have a short \textit{period}. That means the signal ``moves'' fast, or a lot in short time. Therefore: The more movement is in a signal or the more fluctuation or the faster the signal changes the more high frequency content it has.
\end{framed}

Three Questions in order to make you think about signals:

\begin{question}
	Please look at the image below. Can you draw an approximation of its spectrum? What signals could have been mixed to obtain this result? To help you think about this: How would you explain the graph to somebody who doesn't see it?
% subsection raetsel (end)
\begin{figure}[H]
	\begin{center}
		\includegraphics[width = 14cm]{raetsel_original.png}
		\caption{Original Signal}
		\label{fig:originalSignal}
	\end{center}
\end{figure}
\end{question}

\begin{Answer}
You should be able to see that there is a sinusoidal component in the signal. This sinusoid has a period of 10 ms, so a frequency of 100 Hz. But also you should see that it is not a clean sine wave, there is some noisy component in there. This is what you should have been able to infer from the image. In fact it is an (attenuated) 100Hz sinusoid mixed with (attenuated) white noise.
\end{Answer}

\begin{question}
	The signal in figure \ref{fig:originalSignal} was filtered. As a result we obtained the signal in figure \ref{fig:filtered1}. What kind of filter could have been used?
	\begin{figure}[H]
	\begin{center}
		\includegraphics[width = 14cm]{raetsel_highpass.png}
		\caption{Filtered Signal 1}
		\label{fig:filtered1}
	\end{center}
	\end{figure}
\end{question}

\begin{Answer}
	It could have been a notch or stopband filter at 100 Hz or a highpass. In fact, it was a highpass.
\end{Answer}

\begin{question}
	Again, the signal in figure \ref{fig:originalSignal} (so the original signal again) was filtered. As a result we obtained the signal in figure \ref{fig:raetsel_2} . What kind of filter could have been used?
\begin{figure}[H]
	\begin{center}
		\includegraphics[width = 14cm]{raetsel_lowpass.png}
		\caption{Filtered Signal 2}
		\label{fig:raetsel_2}
	\end{center}
\end{figure}

\end{question}

\begin{Answer}
	It could have been a bandpass at 100Hz, or a lowpass. In fact, it was a lowpass. We see that the signal got a lot smoother.
\end{Answer}

\section{Ways of Describing a Filter}
There are a couple of ways to \textit{fully} describe a linear time invariant system (LTI), filters typically\footnote{filters can be augmented with non-linear or time-varying elements, for example distortion or modulation. In sound design, this is actually very common. But describing such a system mathematically is out of the scope of this work.} are such systems.\\
Below is an (incomplete) list of methods that are all able to describe a filter. They offer very different possibilities of understanding and manipulating a filter.
\begin{itemize}
	\item Difference Equation
	\item Magnitude and Phase Response
	\item Impulse Response
	\item Code (graphical, such as Max/MSP, pure data, simulink)
	\item Code (text, such as C++)
	\item Block Diagram
	\item Transfer Function (Rational Function)
	\item Unit Step Response
\end{itemize}

\begin{figure}[htb]
  \centering
  \label{fig:conversions}

  \begin{tikzpicture}[auto, thick, node distance=2.3cm, >=triangle 45]

  % \draw node at (0,0) [input] (excitation) {};
  \draw node at (0,0) [block] (de) {difference Equation};
  \draw node [block, right of=de, node distance = 8cm] (tf) {transfer function};
  \draw node [block, below of= de] (ir) {impulse Response};
  \draw node [block, below of= ir] (sr) {step Response};
  \draw node [block, below of= tf] (fr) {frequency Response};
  \draw node [block, above of= de] (bd) {block diagram};

  % \draw node [block, below of=delay, node distance = 2cm] (loss) {\Large$G(z)$};
  % \draw node at (6.,-0.001) {\textbullet};

  % \draw node [output, right of=delay,node distance = 3cm] (out) {};
  \draw[<->] (de) -- node {by inspection}(bd);
  \draw[->] (de) -- node {\Large$z transform$}(tf);
  \draw[->] (tf) -- node {evaluate on unit circle}(fr);
  \draw[->] (de) -- node {set $x[n]=\delta[n]$}(ir);
  % \draw[->] (sum1) -- node {}(delay);
  % \draw[->] (loss.west) -| node {}(sum1.south);

  % \draw[->] (6., -0.001) |- node {}(loss.east);

  \draw[->] (ir) -- node {\Large$\int x dt$}(sr);
  \draw[->] (ir) -- node {\Large$\mathcal{F} $}(fr);
  % \draw[<-] (ir) -- node {\Large$\mathcal{F^{-1}} $}(fr);

  \end{tikzpicture}
  \caption{Ways of describing LTI systems and how to get from one to the other}
\end{figure}

While in practice, the transfer function is very important, we will mostly work with block diagrams, pd programs and difference equations.\\
It is an important skill to be able to switch between these representations, for example to calculate the impulse response from a difference equation or block diagram.

\subsection{Difference Equations}
\label{sub:diff}

A difference equation is of the form mentioned in the introduction. So for example
\begin{equation}
	y(n) = x(n)+x(n-1)
	\label{eq:simple}
\end{equation}
Here, $y$ is the output $x$ is the input and $n$ denotes indexing those two signals.\\
$y(n)=x(n)$ means: take the incoming sample and make it the output. $x(n-1)$ denotes a delay by one sample. Please note that the above equation describes a \textit{system}, a filter in this case. But it can be seen as using an input array (the input signal), indexed by $n$ and creating an output array.\\
Let's visualize this idea. Given the input signal in figure \ref{fig:diffImpResp}, we can create the output using the equation.

\begin{figure}[h]
	\centering
	\includegraphics[width=\textwidth]{diffEqViz1}
	\caption[shortCaption]
	{The input and corresponding output of the equation given above.}
	\label{fig:diffImpResp}
\end{figure}
 Also it becomes obvious that the $n-1$ expression is a delay, since it makes us look up the 3rd index for creating the 4th sample at the output in this case, or $y(4) = x(4)+x(4-1)$.\footnote{The impulse in this example input signal is at position $n=3$ so the third sample. This was chosen at random and has no meaning. It could just as well sit at $n=5$.}\\
 So for more clarity, let's see all the values at all $n$s (compare this with figure \ref{fig:diffImpResp}):

\begin{center}

\begin{tabular}{l|l|l|l}
	$n$ & $y(n)$ & $x(n)$ &$x(n-1)$\\
	\hline
	0 & 0 & 0 &0\\
	1 & 0 & 0 &0\\
	2 & 0 & 0 &0\\
	3 & 1 & 1 &0\\
	4 & 1 & 0 &1\\
	5 & 0 & 0 &0\\
\end{tabular}
\end{center}

\subsection{Block Diagrams} % (fold)
\label{sub:block}

Block diagrams are nice because they are very visual and sometimes easier to understand. Also, if we work in pure data, or a different graphical programming language (such as Max/MSP or MATLAB Simulink) it's very straight forward to implement a block diagram. Translating from a block diagram to text code or difference equations or vice versa can be hard sometimes.\\
In figure \ref{fig:diffImpResp}, we can see a block diagram representation of equation \ref{eq:simple}. This \textit{is} the same thing.

% subsection subsection_name (end)

\begin{figure}[H]
  \centering
  \label{fig:simpleLPdiag}
  \begin{tikzpicture}[auto, thick, node distance=2.5cm, >=triangle 45]
  \draw node at (0,0) [input] (inp) {};
  \draw node at (2.5,-0.001) (junct) {\textbullet};
  \draw node at (4,2) [block] (delay) {\Large$z^{-1}$};
  \draw node [sum, right of=inp, node distance = 5.cm] (sum1) {\Large$+$};

  \draw node [output, right of=sum1,node distance = 3cm] (out) {};
  \draw[->] (inp) -- node {}(sum1);
  % \draw[->] (junct) |- node {}(delay);
  \draw[->] (delay.east) -| node {}(sum1.north);

  \draw[->] (2.5, -0.001) |- node {}(delay.west);

  \draw[->] (sum1) -- node {\Large$y[n]$}(out);

  \node[text width=3cm] at (1.7,0.4)
    {\Large$x[n]$};

  \end{tikzpicture}
  \caption{A very simple lowpass filter.}
  \label{fig:blockDiagr}
\end{figure}

Don't be irritated by the $z^{-1}$ block. This notation stands for a delay by one sample. A block $z^{-m}$ would stand for a delay by $m$ samples. This is a convention we need to remember. This way of notating a delay might seem unnecessarily complex, but it has its reasons.

\bgInfo{This notation, $z^{-1}$, comes from the fact that analyzing the frequency response of a system is very easy when working with complex numbers (so compounds of real and imaginary numbers). Complex numbers are often denoted by $Z$, which is another convention. Not only do we work with complex numbers, but with complex sinusoids when analyzing such systems. We imagine complex sinusoids coming into our system. A multiplication by another complex sinusoid can cause a phase shift (a delay). Dividing ($z^{-1} = \frac{1}{z}$) an incoming complex sinusoid by the complex sinusoid at the same frequency causes a phase shift that is equals to a delay by 1 sample. If you want to understand all this and stop with mickey-mouse-explanations I can recommend reading \cite{miller_puckette_theory_2006} and \cite{smith_introduction_2007}. Both of these works can be found on-line for free.\

But let's quickly calculate the frequency response, so you've seen it once:
We take our difference equation (we could also start from the block diagram):
\begin{equation}
	y(n) = x(n)+x(n-1)
\end{equation}
We then do a process called the z-transform, that is, we get rid of all the indexing. We now think about applying the process of filtering to the whole signal at once and we denote the delay by a multipliaction with a complex sinusoid that causes a phase shift:
\begin{equation}
	Y = X + X \cdot Z^{-1}
\end{equation}

We then solve the equation for $Y/X$:

\begin{equation}
	Y = X \cdot (1 + Z^{-1})
\end{equation}
\begin{equation}
	\frac{Y}{X} = 1+Z^{-1}
\end{equation}

Typically we substitute $\frac{Y}{X}$ with a new name, typically $H$ and now make this a function of $Z$.

\begin{equation}
	H(Z) = 1 + Z^{-1}
\end{equation}
This is called a system's transfer function. This is the actual standard for talking about systems. Typically we do two things with this, either, we draw a so called \textit{Pole-Zero-Plot}.
\begin{figure}[H]
	\centering
	\includegraphics[width=\textwidth]{poleZero.png}
	\caption[pole zero plot]
	{a pole zero plot. This indicates where the function $H(z)$ has zeros(where its value is zero) or poles(where its value is infinity). Actually there is also a pole at $0+0i$ which is not shown here. This is because a pole at this position has no frequency dependent effect.}
	\label{fig:poleZero}
\end{figure}

We can also evaluate the function $H(z)$for complex sinusoids.\\
The absolute value of $H$ is the output amplitude, if we just plot this value for all complex numbers we see this:

\begin{figure}[H]
	\centering
	\includegraphics[width=\textwidth]{poleZero3dPlot.png}
	\caption[poles and zeros, 3D in the complex plane]
	{Evaluation of the Transfer function in the complex plane. The unit circle is visible as a dotted line. This plot is not too easy to read but if you look at the coordinate $-1+0i$, you can see that the value there is very low. This seems to indicate a lowpass. You can basically ignore the huge mountain in the middle. It sits at $0+0i$ and has therefore equal effect on all frequencies.}
	\label{fig:poleZero3d}
\end{figure}

It's OK if this plot doesn't tell you much. The really important thing is to evaluate this surface using complex sinusoids:
$cos(\omega) + i\cdot sin(\omega)$. This is the same as looking at the values along the dotted line. We can now plot the magnitude response over $\omega$. So we effectively evaluate the formula
\begin{equation}
	|H(\omega)| = |1 + (cos(\omega)+i \cdot sin(\omega))^{-1}|
\end{equation}
Where $\omega$ ranges from $0$ to $\pi$(sic!). This is the same as going along the dotted line, starting at $1+0i$ (lowest frequency) and ending at $-1+0i$ (the highest frequency). Then we finally get the magnitude response:

\begin{figure}[H]
	\centering
	\includegraphics[width=\textwidth]{magResp.png}
	\caption[Filter magnitude response]
	{Magnitude response, so $|H(\omega)| = |1 + (cos(\omega)+i \cdot sin(\omega))^{-1}|$}
	\label{fig:magResp}
\end{figure}

}

\subsection{pd Code} % (fold)
\label{sub:pd_code}
If we program the filter in pd (or any other programming language) we obviously also fully defined the filter. Try to build the filter from above in pd! Start from the difference equation or the block diagram, what ever is harder to understand for you.\\
In figure \ref{fig:pdSimpleFir} you can see the translation to pd.

\begin{figure}[H]
	\centering
	\includegraphics{simpleFir}
	\caption[FIR filter in pd]
	{A simple filter in pure data.}
	\label{fig:pdSimpleFir}
\end{figure}

% subsection pd_code (end)

\subsection{Impulse Response}

An impulse has the advantage that it contains all frequencies. It has a flat spectrum.  So recording how a filter reacts to the impulse gives us the magnitude of the spectrum at all frequencies.\\
We can see the impulse response of the filter we are describing in this section in  multiple ways in figure \ref{fig:diffImpResp}.

\bgInfo{
\subsection{Text Oriented Code} % (fold)
\label{sub:tcode}
Below, we can see a code implementation in the language MATLAB.

\lstinputlisting[label=code,
captionpos=b,
caption=A script that creates an impulse implements a vectorized filter and plots the result.]{code/FIRvectorized.m}
}

\section{Ways of Getting an Intuitive Understanding}

So now we learned some ways to define a filter, to talk about a filter. But what is this filter actually doing? It is a very simple lowpass filter. It cuts away high frequencies. But why is adding a signal to itself but one sample delayed making a lowpass? This certainly is a bit surprising, so let's try to understand what's happening.

\subsection{Combfilter to Lowpass}
First let's view the problem from another angle. We know what this structure from above is: It's a combfilter, right? It's taking a signal and adding a delayed version of it. Let's quickly review what a combfilter is:
The combfilter effect can come up if we record something with a microphone and we get the direct signal and a delayed (e.g. via a reflection) signal also. These two signals mix together and this is what we get in our recording.\\
The result is that some frequencies cancel out.\\
We can simply simulate this situation in Max using a delay and an addition.

\begin{figure}[H]
	\centering
	\includegraphics{simpleComb}
	\caption[simple comb filter]
	{A very simple comb filter}
	\label{fig:simpleComb}
\end{figure}

This canceling out of frequencies \footnote{also called destructive interference} can be imagined if we look at figure \ref{fig:destIntereference}.
\begin{figure}[H]
	\centering
	\includegraphics[width=\textwidth]{destInterference}
	\caption[Destructive Interference]
	{Destructive Interference. The two waves would cancel out completely if mixed together(=added).}
	\label{fig:destIntereference}
\end{figure}

Please note that the signal is a sine wave with a frequency of 100 Hz, so a period of 10 milliseconds. The delay is set to be 5 ms, so half of the period of the input signal in this case. It it was set to be equals the period, the two waves would \textit{interfere constructively}, so we would get out a higher amplitude. \\

\important{In a combfilter, the first frequency that cancels out is the one whose period is double the delay time. Or, to put it differently
\begin{equation}
	f_c = \frac{1}{2d}
\end{equation}
If $f_c$ is the first frequency that cancels out and d is the delay time in seconds. \\
How to calculate this fast, if you are given the delay time:
just calculate the frequency for the given delay, and then use half of that. For example, if given delay 1ms, the corresponding frequency would be 1000 Hz. Half of that (=double the period) is 500 Hz, and that's where the first trough in the spectrum would be.

}

In figure \ref{fig:combToLowpass} we can see the \textit{frequency response}\footnote{The impulse response is recorded a couple of times and the output's spectrum has been analyzed} of our combfilter. We see a couple of plots, it's always the same filter but the delay is different. We see that for delay times >1 sample, we observe our typical comb pattern. But at Delay = 1 sample, there is just a ramp left, leaving us with a lowpass.

\begin{figure}[H]
	\centering
	\includegraphics[width=\textwidth]{FromCombfilterToLowpass}
	\caption[From comb filter to lowpass]
	{Different amounts of delays result in different magnitude responses. The extreme case of a comb filter, a delay of 1 sample, is looking like a lowpass.}
	\label{fig:combToLowpass}
\end{figure}

\bgInfo{
	We can also calculate what's happening with our equation from above:
	The delay is $1/f_s$, so 1 over samplerate. This is called the sampling intervall, let's call it $I_s$, just to get rid of the fraction. The frequency that cancels out is then $1/2I$. By inspection we find that this means the frequency that has double the wavelength of the sampling frequency, so half the sampling frequency, so \textit{Nyquist}.
}

\subsection{Prolonging an Impulse}
We can also take a different route to understand why this is a lowpass. Let's recall what the spectrum of an impulse looks like and what the spectrum of DC offset looks like. Taking a look at figure \ref{fig:impToDc}, we see an impulse, the impulse response of our filter and a DC-Offset signal. Recalling from the introduction, and looking at the figure, we know that the DC-offset signal contains only energy at 0Hz. Now look at the time domain signals: Isn't making our impulse signal last for one sample longer a small step towards generating a DC-offset signal?

\begin{figure}[H]
	\centering
	\includegraphics[width=\textwidth]{impulseToDC}
	\caption[Spectrum Impulse, Lowpass, DC]
	{Impulse, impulse response and DC offset signal and their spectra. Note that there are very few samples here and the DC-Offset signal's spectrum seems to ramp down from 0Hz. In fact, there is a single high value at 0Hz.}
	\label{fig:impToDc}
\end{figure}

\subsection{A moving Average}
How is \textit{average} defined? There are a lot of different ways to compute an average, but typically we mean the \textit{arithmetic mean}, so adding all numbers and dividing by the count of items:
\begin{equation}
	A = \frac{1}{N} \sum_{n=1}^N x(n)
\end{equation}

Looking back at our filter, we will notice that we are adding up the current sample and the last sample. If we were to divide that sum by two (so the number of elements, since it's two samples we are adding up), we would arrive at the definition above. So we could say, that our lowpass is always outputting the average of the current and the last sample. It is therefore called a moving average filter. \\
Taking the average of something always reduces information and we get something that is fluctuating less than its input. If we would make a website or something that would always show the average temperature in Vienna of the last two weeks, this display wouldn't start jumping around if there was a single hot day in winter. It would remove high frequency data (jumps). It would be some kind of lowpass filter.

\subsection{A sine at Nyquist}
Here is yet another way of understanding why the structure we saw is a lowpass. Let's imagine a sine wave at Nyquist frequency, the highest frequency we can work with. We can see what such a sine looks like in Figure~\ref{fig:nyqSine}. If we apply this moving average filter, so that lowpass we have been talking about, what do you think comes out? Go ahead and calculate the average for each sample and its previous sample. We add $1 + -1 = 0$, $-1 + 1 = 0$, $1 + -1 = 0$, ... So you can see, if we feed a sine at nyquist into our lowpass, what we get is silence.

\begin{figure}[H]
	\centering
	\includegraphics[width=\textwidth]{sineWaveNyq.png}
	\caption[Sine wave at nyquist frequency]
	{Sine wave at nyquist frequency}
	\label{fig:nyqSine}
\end{figure}

\subsection{Highpass} % (fold)
\label{sub:Highpass}

You should already be familiar with the basic types of filters, so lowpass, highpass, bandpass etc. We now saw how we can build a lowpass filter, but what about a highpass, what about notching, peak, shelving filters? This is getting pretty involved quickly, but let's have a look at a highpass. Highpass filtering is the opposite of lowpass filtering. It emphasizes movement in the signal, since everything that moves fast must contain high frequencies. One simple form of a highpass is taking the difference between the current and the last sample, so:

\begin{figure}[H]
  \centering
  \label{fig:sipleHP}
  \begin{tikzpicture}[auto, thick, node distance=2.5cm, >=triangle 45]
  \draw node at (0,0) [input] (inp) {};
  \draw node at (2.5,-0.001) (junct) {\textbullet};
  \draw node at (4,2) [block] (delay) {\Large$z^{-1}$};
  \draw node [sum, right of=inp, node distance = 5.cm] (sum1) {\Large$+$};

  \draw node [output, right of=sum1,node distance = 3cm] (out) {};
  \draw[->] (inp) -- node {}(sum1);
  % \draw[->] (junct) |- node {}(delay);
  \draw[->] (delay.east) -| node {}(sum1.north);

  \draw[->] (2.5, -0.001) |- node {}(delay.west);

  \draw[->] (sum1) -- node {\Large$y[n]$}(out);

  \node[text width=3cm] at (1.7,0.4)
    {\Large$x[n]$};

\node[text width=3cm] at (6.7,0.9)
    {\Large$-$};

  \end{tikzpicture}
  \caption{A very simple highpass filter. Please compare to \ref{fig:blockDiagr}. }
  \label{fig:blockDiagrHigh}
\end{figure}

You will notice that figure \ref{fig:blockDiagrHigh} and figure \ref{fig:blockDiagr} are identical with oly one little exception. In this highpass filter we \textbf{subtract} the delayed signal from the input. This is denoted by the little $-$ sign next to one line leading to the addition. One might think, ``Why don't we just use a minus sign instead of the addition sign?'' Because order matters with subtraction, it makes a difference if we subtract 3 from 5 or 5 from 3.\\
The structure above is also called a differentiator, since it is a way of approximating the derivative of a signal.

% subsection filter_types (end)

\subsection{Video Filters}

\video{
	Filters in video work the same way and are as common as in audio. But in video we have another question to answer before we start filtering: Does our operation (adding two neighboring samples) apply to time, or to space? In other words: Do we want to add neighboring pixels to produce an output pixel or do we want to add whole frames over time to produce an output frame?\\
	Have a look at figure \ref{fig:v_origianl}. We will take this still from a video as a reference. We send the video through a couple of filters (one at a time, not in series) and watch the output. \\
	For each of the output frames, try to think about how this could have been generated from the input, what kind of a filter could have been used!?

	\begin{figure}[H]
		\begin{center}
			\includegraphics[width = 14cm]{vidFilters_o.png}
			\caption[Video Filters: Original]{Frame from the original video}
			\label{fig:v_origianl}
		\end{center}
	\end{figure}

\begin{figure}[H]
	\begin{center}
		\includegraphics[width = 14cm]{vidFiltersFIRs.png}
		\caption[Video Filters: Blur]{This effect is known as a \textit{blur} It is generalted by using a FIR lowpass in the space domain. That means, in the simplest case, each output pixel is the average of the input pixel at the same location and its neighbors. In practice, weighting functions are used to control, how much the input pixel and how much its neighbors contribute. These weighting functions are called kernels, (since this FIR filtering is the same as convolution). Typical kernels are: Gaussian, Box, the sinc function, etc. }
		\label{fig:v_blur}
	\end{center}
\end{figure}

\begin{figure}[H]
	\begin{center}
		\includegraphics[width = 14cm]{vidFilters_IIRt.png}
		\caption[Video Filters: IIR Lowpass, time domain]
		{Here we can see a kind of lowpass (IIR) in the time domain. The current input-frame and a mixture of past (output-)frames are added up to generate this output frame.}
		\label{fig:v_TLP}
	\end{center}
\end{figure}

\begin{figure}[H]
	\begin{center}
		\includegraphics[width = 14cm]{vidFiltersHPFIRs.png}
		\caption[Video Filters: FIR Highpass, space domain]
		{We can hardly see anything here, but if you look closely, edges from the original are still visible. What happened here is a FIR filtering in the space domain, so the opposite of blurring: Edge detection.}
		\label{fig:vidFiltHP}
	\end{center}
\end{figure}

\begin{figure}[H]
	\begin{center}
		\includegraphics[width = 14cm]{vidFiltersHPFIRt.png}
		\caption[Video Filters: FIR Highpass, time domain]
		{What we can see here is another highpass, but in the time domain. It computes the difference between the current and the last frame.}
		\label{fig:vidFilHPt}
	\end{center}
\end{figure}

}

\section{Filters in Max/MSP}
Please note that what we did so far was filtering signals, but we \textbf{built} the filters with very low level operations (Addition, multiplication and time shift = delay). This was in order to understand how filters work. Sometimes we need to build a filter, but often we can just \textit{use} filters, which are built in to Max or any other environment.\\
\subsection{Lowpass}
In pd, we can use \pd{lop\textasciitilde}, \pd{onepole\textasciitilde}, \pd{lores\textasciitilde} and \pd{vcf\textasciitilde}. \pd{lores\textasciitilde } has a resonance parameter. This emphasizes frequencies at the cutoff frequency of the filter. \pd{vcf\textasciitilde} also has this parameter and an additional bandpass output.

\subsection{Highpass}
There is \pd{hip\textasciitilde}, which is a highpass filter. But we can just use a structure that subtracts a lowpassed version from our original signal also. For example:
\begin{figure}[H]
	\begin{center}
		\includegraphics{pdhighpass.png}
		\caption{Highpass filter}
		\label{fig:pdHP}
	\end{center}
\end{figure}

\subsection{Bandpass} % (fold)
There are two bandpass filters in Max, \pd{reson\textasciitilde} and \pd{svf\textasciitilde}. Additionally \pd{biquad\textasciitilde} can be used in bandpass mode.
We can also make our own custom bandpass using a lowpass and a highpass in series:
\begin{figure}[H]
	\centering
	\includegraphics{bandpass}
	\caption[bandpass]
	{Bandpass Filter in pd}
	\label{fig:filterInPd}
\end{figure}

% subsection subsection_name (end)

More basic building blocks that can be used to realize a filter are \pd{rpole\textasciitilde }, \pd{rzero\textasciitilde }, \pd{cpole\textasciitilde }. \pd{czero\textasciitilde }. \pd{biquad\textasciitilde } is a very powerful filter that allows more or less arbitrary responses.\\

\section{Types of Digital Filters}

It is important to understand that there are two types of filters\footnote{We are going to ignore that one can also filter by using FFT approaches}.
\begin{itemize}
	\item Finite Impulse Response (FIR) Filters
	\item Infinite Impulse Response (IIR) Filters
\end{itemize}

We have been dealing with a FIR filter so far. An infinite impulse response filter does not have an infinite impulse response in practice, but it \textit{can} have one. How is this achieved? By using feedback. A FIR filter does not have feedback, an IIR filter does.

\begin{figure}[htb]
  \centering
  \label{fig:IIRlowpass}

  \begin{tikzpicture}[auto, thick, node distance=2.3cm, >=triangle 45]

  \draw node at (0,0) [input] (excitation) {};
  \draw node [sum, right of=excitation, node distance = 2.cm] (sum1) {\Large$+$};
  \draw node at (5,-2) [block ] (delay) {\Large$z^{-1}$};
  \draw node [mult,shape border rotate=180, left of=delay, node distance = 2cm] (loss) {$0.5$};
  \draw node at (6.,-0.001) {\textbullet};

  \draw node [output, right of=sum1,node distance = 5cm] (out) {};
  \draw[->] (excitation) -- node {\Large$x[n]$}(sum1);
  % \draw[->] (sum1) -- node {}(6., -0.001);
  \draw[->] (loss.west) -| node {}(sum1.south);

  \draw[->] (6., -0.001) |- node {}(delay.east);
  \draw[->] (delay) -- node {}(loss);

  \draw[->] (sum1) -- node {\Large$y[n]$}(out);

  \end{tikzpicture}
  \caption{A simple IIR filter. Note that the arrows are circling, there is feedback involved.}
\end{figure}

If we look at the impulse Response, we can see that it is  ``longer'' than what we had before. If you look closely, we can see that the output sample at which the impulse arrives(n=3), just has the value of the input(1). After that, we can see that the next value is always the sample before times 0.5, so the impulse respopnse is a \textit{geometric series}: $\{1,0.5,0.25,0.125,..\}$ or $\{1, \frac{1}{2}, \frac{1}{4}, \frac{1}{8}, ...\}$. This is the case since the coefficient in the feedback path is 0.5, so $\frac{1}{2}$.

\begin{figure}[H]
	\centering
	\includegraphics[width=\textwidth]{IIR1}
	\caption[Impulse Response of $y(n)=x(n)+\frac{1}{2}y(n-1)$]
	{Impulse Response of $y(n)=x(n)+\frac{1}{2}y(n-1)$}
	\label{fig:iir2}
\end{figure}

Let's translate the above diagram to a difference equation, so we see another representation of the same system.
\begin{equation}
 	y(n) = x(n)+y(n-1) \cdot 0.5
 \end{equation}

Finally, let's quickly summarize some of the differences between the two filter types:
\begin{center}

\begin{tabular}{l|l|l}

& \textbf{IIR} & \textbf{FIR} \\
\hline
stability & possibly unstable & always stable \\
Real time Efficiency & Very efficient & inefficient \\
topology & Feedback & no feedback \\

\end{tabular}
\end{center}

\subsection{IIR Filters in Max}
There are several ways to use IIR filters in Max (\pd{biquad\textasciitilde}, \pd{onepole\textasciitilde}, \pd{cascade\textasciitilde}, ... ). If we want to \textit{create} an IIR filter from scratch, we should use \pd{gen\textasciitilde}. After creating a \pd{gen\textasciitilde} object, we can double click it to edit it. In there we are allowed to do signal processing on a sample-by-sample level. This is necessary in order to use feedback with a single sample delay. A simple IIR lowpass filter would look like depicted in Figure \ref{fig:iirGen}.

\begin{figure}[H]
	\centering
	\includegraphics{img/genIIR.PNG}
	\caption[IIR lowpass filter made in gen.]
	{IIR lowpass filter made in gen. $y(n)=x(n)+0.99 \cdot y(n-1)$}
	\label{fig:iirGen}
\end{figure}

% \section{Convolution}
% Convolution is a very important concept in DSP. We already encountered it in chapter \ref{Modulation}. We know that convolution reverbs use impulse responses of rooms to simulate these rooms. But how is this done? It \textit{can} be done using a FIR filter.

\section{Key Points}
\begin{itemize}
	\item Make sure you understood the differences between a FIR and an IIR filter.
	\item Make sure you can make an educated guess what kind of a filter we see if you encounter a block diagram.
	\item Make sure you can do simple translations between Max, blockdiagrams and difference equations.
	\item Make sure you know when a combfilter turns into a lowpass.
	\item Make sure you know and understand the formula to calculate the first phase cancellation in a combfilter.
\end{itemize}

\section{Homework}

Build the structure depicted in Figure~\ref{fig:genFx} in Max/MSP.

\begin{figure}[H]
	\centering
	\includegraphics[width=\textwidth]{img/effect.png}
	\caption[Generalized Effects Structure proposed by Dattoro]
	{Effects Structure proposed by Dattoro}
	\label{fig:genFx}
\end{figure}

% Notizen aus erster UE:\\
% Viellt. mit IR anfangen?
% Vielleicht davor noch: das beispiel mit noise + sinus.

% IR, bypass system, hall system.

% garnicht faltung. Moving average zu long FIR.
% Impuls antworten anhand beispielen besprechen.

% \begin{enumerate}
% 	\item FIR!

% kammfilter(FF)

% dann FIR kammfilter

% chorus
% flanger

% LFO

% ->index/tiefe, offset, frequenz wdh.

% -frequenzgang
% ausl\"oschungen, rechnen..

% \item
% FIR one sample delay\\

% FIR bauen, vllt. an tafel blockdiagramm.\\

% FIR hipass\\

% \item

% mehrere Samples delay
% IR
% differenzen gleichung

% eventuell Faltung(faltungs hall connection herstellen)

% faltung als multiplikation d. spektra
% multiplikation als faltung d spektra.

% M4L faltungs hall herzeigen

% LTI?

% differentiator, akkumulator?

% \item
% IIR\\

% notizen POlyphonie
% was separat, was einmal

% \end{enumerate}

% \section{einfuehrung} % (fold)
% \label{sub:einfuehrung}

% Ziel der LV:\\
% \begin{enumerate}
% 	\item Gefühl dafür bekommen was die häufigsten Operationen der DSV eigentlich tun.
% 	\item Gefühl dafür bekommen, dass es günstig ist, zwischen verschiedenen repräsentationen hin und her zu wechseln (time und frequency domain, aber auch system repräsentationen)
% 	\item Sich in professioneller literatur(DSP lehrbücher) nicht völlig verloren fühlen.
% 	\item schönheit zu sehen dass alles das \glqq{}gleiche\grqq{} ist.(Delay, filter, reverb, chorus, flanger etc)
% \end{enumerate}

% Wozu?:\\
% \begin{enumerate}
% 	\item Wir arbeiten ständig mit Operationen der DSV. Filter sind nicht nur in synthesizern. Ein tieferes verständnis erleichtert die arbeit. Wie funktioniert zum beispiel ein blur?
% 	\item Was ist ein FeedForward compressor?
% \end{enumerate}

% Nachdenken über filter allgemein. Was ist ein filter im gespür d. studenten. \\
% Bekannt was ein LTI system ist?\\

% \newpage
% -Wie könnte ein filter realisiert werden?\\
% -Ein digitales signal ist eine reihe von zahlen, eine sequenz von werten. (über bildliche darstellungen sprechen)\\
% -Echtzeit fall: ich bekomme in ein system ein signal(also ständig werte) und soll ein zb. lowpass gefilteretes signal ausgeben.\\
% \textbf{Was kann ich mit dem signal machen? Zum beispiel addieren, multiplizieren, verzögern.}\\

% Einfacher moving average. Zunächst nur an der tafel!
% Impulsantowrt ausrechnen!
% Was ist ein impuls.\\
% Was ist eine impulsantwort? Beispiele.. untit impulse ( = dirac impuls, dirac gunktion, delta function)\\

% Diagramm aufmalen:

% impuls \(\rightarrow\) Raum \(\rightarrow\) Impulsantwort\\
% oderr \\
% impuls \(\rightarrow\) beliebiges system \(\rightarrow\) Impulsantwort\\
% \textbf{anwendugsbeispiel:} tontechnik bei okto; mischpult ausmessen, dbmax ausmessen(fragwürdige sache! Wieso?)

% \textbf{FRAGE}\\
% Ein system(zB. ein Filter) hat folgende Eigenschft:\\
% Wenn zwei signale getrennt (d.h. unabhängig voneinander, zB. nacheinander.) in das system geschickt werden, und die Ergebnisse summiert werden, entsteht das signal \(P\). Wenn andererseits die signale zuvor summiert werden und dann in das system geschickt werden entsteht ebenfalls \(P\). Welche gleichung etspricht einer beschreibung dieser eigenschaft?

% \begin{enumerate}
% 	\item \(f(x)+f(y) = f (x * y) = P\)
% 	\item \(f(x)+f(y) = f (x + y) = P\)
% 	\item \(f(x)+f(x) = f (x + y) = P\)
% 	\item \(f(x)+f(y) = f (x + x) = P\)
% 	\item nichts von alledem.
% \end{enumerate}

% \newpage
% richtig : nr.2 \\
% \\

% Erklärung eines LTI systems:

% \begin{itemize}
% 	\item Linear:
% 		\begin{itemize}
% 			\item Superpositionsprinzip \(f(x)+f(y) = f (x + y)\)
% 			\item Homogenität \(a*f(x) = f(a*x)\)
% 		\end{itemize}
% 	\item Time Invariant (zeit-invariant)
% \end{itemize}

% Zurück zu filter:
% was glauben sie wie er funktioniert. \\
% \\

% \section {kammfilter}

% Wiederum fragen was sich die studenten vorstellen.\\

% \glqq{}Wir bauen ein delay.\grqq{}
% nicht vergessen: block~, subpatcher.

% \begin{figure}[h]
% 	\begin{center}
% 		\includegraphics[width = 14cm]{simpleDelay.png}
% 		\caption{SimpleDelay}
% 		\label{fig:simpleDelay}
% 	\end{center}
% \end{figure}

% Studenten sollen ausprobieren. Verschiedene inputs f. kammfilter. \\

% Modulation des kammfilters. Studenten sollen LFO an den kammfilter dran bauen.\\
% \(\rightarrow\) Flager \\
% \(\rightarrow\) Chorus \\

% \textbf{index/tiefe, offset, frequenz wiederholen.}

% \begin{figure}[h]
% 	\begin{center}
% 		\includegraphics[width = 14cm]{generalizedEffect.png}
% 		\caption{generalized Effect structure}
% 		\label{fig:genEffect}
% 	\end{center}
% \end{figure}

% über name sprechen, sowohl spectrum als auch Impulsantwort(IIR variante) sind kammförmig. \\
% Eigentlich einfach ein delay, ein delay mit feedback im falle von IIR.\\

% \begin{figure}[h]
% 	\begin{center}
% 		\includegraphics[width = 14cm]{img/combFIR_patch.png}
% 		\caption{Der Patch 01\_combFilter.pd}
% 		\label{fig:01_combFilter}
% 	\end{center}
% \end{figure}

% Zunächst nicht wichtig die versch. representationen zu verstehen. \\
% Patch representation kurz durchbesprechen. Sollte verständlich sein.\\

% Unterschiedliche representationen durchbesprechen.
% Fragen, abstimmen?, was die studenten für die angenehmste representation halten.

% \begin{itemize}
% 	\item Patch: vorteile: interaktiv, allgemein, reinfolge der events nachvollziehbar. Nachteil: nicht sehr übersichtlich. Nicht sehr konzis, nicht kompakt.
% 	\item Block Diagramm: übersichtlich, allgemein. Reinfolge der events klar, pfeile! Fluss, richtung, eindeutig. Nachteile: Nicht kompakt.
% 	\item differenzen gleichung: Vorteil: kompakt, konzis. Nachteil: reinfolge der events nicht klar ersichtlich: kein rezept, eher eine beschreibung. (nicht imperativ sondern deklarativ, va. im Fall von Feedback)
% 	\item Impulsantwort: \textbf{Frage: was ist ein Impuls?}  Vor/Nachteil: Nicht allgemein, nur ein spezieller zustand des systems beschrieben. Nicht kompakt, aber kann sehr intuitiv sein. Beispiele an tafel: IR von bypass-system, IR mit viel hall, IR von bandpass filter mit hoher resonanz, eventuell: differentiator, accumulator.
% 	\item andere representationen: text-code, transfer funktion, frequency response(magnitude + phase response/group delay)
% \end{itemize}

% \newpage

% \section {Moving Average}

% \textbf{Wo hat der kammfilter immer sein erstes Tal im spectrum?}
% Sinus an tafel malen.
% Antwort:
% bei

% \(\lambda =  (2* \Delta t) \)
% (wobei \(\Delta t\) die delay zweit in sekunden. und \(\lambda\)  die periodendauer der gesuchten frequenz.) Daher:\\
% \(
% f_c = 1/(2* \Delta t)
% \)

% Nun wird das delay auf ein sample reduziert. Ein lowpass entsteht der seine grenzfrequenz bei sr/2 hat.\\

% Frage: was macht ein lowpass filter in der timedomain?

% \begin{figure}[h]
% 	\begin{center}
% 		\includegraphics[width = 14cm]{movingAverage.png}
% 		\caption{movingAverage}
% 		\label{fig:movingAverage}
% 	\end{center}
% \end{figure}

% \textbf{EXKURS: VIDEO FILTER, lowpass, time domain erkennen.}

% \newpage
% \textbf{Frage:} Vergleiche original und die gefilterte variante (01.mov) . Was für ein filter könnte angewandt worden sein:
% \begin{enumerate}
%  	\item lowpass
%  	\item bandpass
%  	\item hipass
%  	\item notch
%  	\item nichts von alledem
%  \end{enumerate}

% wie könnte ein highpass realisiert werden? Wie schaut der effekt eines highpass filters in der frequenz- und wie in der timedomain aus?

% \section{convolution, Faltung}

% Video (unten) zeigen, vorher erklären: \\

% conv theorem.

% http://youtu.be/\_vyke3vF4Nk?t=25m16s \\
% start bei min 25.

% \textbf{maxpatch}

% %%--------------------------------------------------------------------------
% %% IIR/FIR
% %%--------------------------------------------------------------------------
% \section {IIR/FIR}

% Je steiler die Filterflanke sein, je komplexer der filter sein soll, desto mehr delays werden benötigt.\\

% Wieso: einfache Erklärung: Um aus einem signal, das alle frequenzen enthält (zB dirac impuls) ein signal zu machen, das hauptsächlich sehr tiefe frequenzen enthält wird ein system benötigt das \glqq{}lange wellen\grqq{} zu produzieren im stande ist.

% An tafel zeichnen: dirac impuls und unit step/ DC. Frage nach spectrum.\\

% frage nach FIR der diesen IR haben könnte.

% \textbf{Patch: lomgSimpleFir}

% Grenzfall: integrator macht aus unit impulse, \(delta [n]\), unit step signal\(u[n]\)(DC).

% Integrator an tafel malen.\\

% Daher:
% Es kann gezeigt werden dass ein feedback pfad einer unendlichen menge an delays gleichkommt, siehe IR.

% \textbf{Patch: 02\_combFilterIIR}

% nebenbei:
% linear phase = symmetrischer IR, immer FIR, daher weniger performant.
% Linear phase filter sind notwendig wenn die timedomain wellenform möglichst unbeeinträchtigt bleiben soll.

% \subsection{Onepole} % (fold)
% \label{ssub:onepole}

% % subsubsection subsubsection_name (end)
% onepole an tafel beschreiben. Block diagramm, malen, nach differenzengleichung fragen. Patch herzeigen.\\

% \textbf{patch: IIRtest} \\
% danach:\\
% \textbf{patch: IIRtest2} \\

% Fragwürdig aber falls interesse:
% onepole coeff berechnung zB:\\

% \begin{equation}
% a_0 = \frac{2 \pi f_c} {sr}
% \end{equation}

% oder

% \begin{equation}
% a_0 = sin(\frac{2 \pi f_c} {sr})
% \end{equation}

% \section{Hausübung}

% hausübung: Baue einen einen chorus. TESTSIGNAL AUSBESSERN! nicht noise!!


\documentclass{spec}

\usepackage{amsfonts,bm,amsmath}
\usepackage{verbatim}
\usepackage{algorithm, algpseudocode}
\usepackage{caption}

\input{nlls_header.tex}
\newcommand{\scalarinteger}[1]{\itt{int #1}}
\newcommand{\scalarreal}[1]{\itt{double #1}}
\newcommand{\scalarlogical}[1]{\itt{bool #1}}
\newcommand{\ronearrayreal}[2]{\itt{double *#1}}
\newcommand{\scalarcharacter}[2]{
  % need to advance the size by one for the c version compared to the fortran version...
  \newcount\charsize
  \charsize=#2
  \advance\charsize by 1 %
  \itt{character #1[\the\charsize]}
}
\newcommand{\mainroutine}{{\tt nlls\_solve}}
\newcommand{\onestep}{{\tt ral\_nlls\_iterate}}
\newcommand{\ct}{.}
\newcommand{\vecentry}[2]{\texttt{#1[#2]}}
\newcommand{\fortranonly}[1]{}
\newcommand{\conly}[1]{#1}
\begin{document}

\hslheader

\begin{center}
\huge \sc  C Interface
\end{center}

\hslsummary

\input{summary.tex}

%!!!!!!!!!!!!!!!!!!!!!!!!!!!!
\hslattributes
\hslversions{\versionum\ (\versiondate)}.
\hslIRDCZ Real (single, double).
\hsllanguage Fortran 2003 subset (F95+TR155581).
\hsldate January 2016.
\hslorigin The Numerical Analysis Group, Rutherford Appleton Laboratory.
\hslremark The development of this package was
partially supported by EPSRC grant EP/M025179/1.

%!!!!!!!!!!!!!!!!!!!!!!!!!!!
\newpage
\hslhowto

\subsection{Calling sequences}

Functions signatures are defined in a header file
\begin{verbatim}
   #include "ral_nlls.h"
\end{verbatim}
\medskip

\noindent The user callable subroutines are:
\vspace{-0.1cm}
\begin{description}
   \item[\texttt{ral\_nlls\_default\_options()}] initializes solver options to default values.
   \item[\texttt{nlls\_solve()}]  solves the non-linear least squares problem (Section~\ref{eq:nlls_problem}).
   \item[\texttt{ral\_nlls\_init\_workspace()}] initialises a workspace for use with \texttt{ral\_nlls\_iterate()}.
   \item[\texttt{ral\_nlls\_iterate()}] performs a single iteration of the solver algorithm.
   \item[\texttt{ral\_nlls\_free\_workspace()}] frees memory allocated by a call to \texttt{ral\_nlls\_init\_workspace()}.
\end{description}

%%%%%%%%%%%%%%%%%%%%%% derived types %%%%%%%%%%%%%%%%%%%%%%%%

\hsltypes
\label{derived types}
For each problem, the user must employ the derived types defined by the
module to declare scalars of the types {\tt struct ral\_nlls\_options}, and
{\tt ral\_nlls\_inform}.
The following pseudocode illustrates this.
\begin{verbatim}
   #include "ral_nlls.h"
   ...
   struct ral_nlls_options options;
   struct ral_nlls_inform inform;
   ...
\end{verbatim}
The members of these structs are explained
in Sections~\ref{typeoptions} and \ref{typeinform}.

%%%%%%%%%%%%%%%%%%%%%% argument lists %%%%%%%%%%%%%%%%%%%%%%%%
\hslarguments

\subsubsection{Integer and package types}
%{\tt INTEGER} denotes default {\tt INTEGER} and
%{\tt INTEGER(long)} denotes {\tt INTEGER(kind=selected\_int\_kind(18))}.
The term {\bf package type} is used to mean \texttt{float}
if the single precision version is being used and
\texttt{double} for the double precision version.

\subsubsection{To initialise members of \texttt{struct nlls\_options} to default values}

To initialise the value of \texttt{struct nlls\_options}, the user \textbf{must} make a
call to the following suboutine (failure to do so will result in undefined behaviour):
\begin{verbatim}
   void ral_nlls_default_options(struct ral_nlls_options *options);
\end{verbatim}

\begin{description}
   \itt{*options} will be initialised to default values on return.
\end{description}

\subsubsection{To solve the non-linear least squares problem}
\label{sec:solve}

To solve the non-linear least squares problem make a call of the following
subroutine:

\begin{verbatim}
   void nlls_solve( int n, int m, double X[], ral_nlls_eval_r_type eval_r,
      ral_nlls_eval_j_type eval_j, ral_nlls_eval_hf_type eval_hf,
      void* params, struct nlls_options const* options, struct nlls_inform* inform,
      double weights[])
\end{verbatim}

\begin{description}
\itt{n} holds the number $n$ of
variables to be fitted; i.e., $n$ is the length of the unknown vector $\bm x$.

\itt{m} holds the number $m$ of
data points available; i.e., $m$ is the number of functions $f_i$.
\textbf{Restriction:} \texttt{m},\texttt{n}$>$\texttt{0}

\itt{x} must hold the initial guess for $\bm x$, and on
successful exit it holds the solution to the non-linear least squares problem.

\itt{eval\_r} specifies a callback function that, given a point $\iter{\vx}$,
returns the vector $\vr(\iter{\vx})$. Details of the function signature and
requirements are are given in Section~\ref{sec::function_eval}.

\itt{eval\_j} specifies a callback function that, given a point $\iter{\vx}$,
returns the $m \times n$ Jacobian matrix, $\iter{\vJ}$, of $\vr$ at $\iter{\vx}$. Details of the function signature and requirements are are given in
Section~\ref{sec::function_eval}.

\itt{eval\_hf} is a {\tt PROCEDURE} that, given a point $\iter{\vx}$
and function $\vr(\iter{\vx})$, returns the second-order terms of the Hessian at $\iter{\vx}$.
Further details of the format required are given in Section~\ref{sec::function_eval}.

\itt{params} is a pointer to user data that is passed unaltered to the callback
functions {\tt eval\_r}, {\tt eval\_J}, and {\tt eval\_Hf}.

\itt{inform} provides information about the execution
of the subroutine, as explained in Section~\ref{typeinform}.

\itt{options} specifies options that control the execution of the subroutine,
see Section~\ref{typeoptions}.

\itt{weights} may be {\tt NULL}, otherwise it is a rank-1 array of size {\tt m}. If present, {\tt weights} holds the square-roots of the
diagonal entries of the weighting matrix, $\vW$, in (\ref{eq:nlls_problem}).  If absent, then the norm in (\ref{eq:nlls_problem}) is taken to be the 2-norm, that is, $\vW = I$.
\end{description}

\subsubsection{To initialise a workspace for use with \texttt{ral\_nlls\_iterate()}}

Prior to the first call of \texttt{ral\_nlls\_iterate()}, the workspace must be
initialised by a call to the following subroutine:
\begin{verbatim}
   void ral_nlls_init_workspace(void **workspace);
\end{verbatim}

\begin{description}
   \itt{*workspace} will, on return, be allocated and initialised using Fortran intrinsics.
      To avoid a memory leak, it must be freed through a call to \texttt{ral\_nlls\_free\_workspace()}.
\end{description}

\subsubsection{To iterate once}
\label{sec:iterate}
Alternatively, the user may step through the solution process one iteration at
a time by making a call of the following form:

\begin{verbatim}
   void ral_nlls_iterate( int n, int m, double X[], void* workspace,
      ral_nlls_eval_r_type eval_r, ral_nlls_eval_j_type eval_j, ral_nlls_eval_hf_type eval_hf,
      void* params, struct nlls_options const* options, struct nlls_inform* inform,
      double weights[])
\end{verbatim}

\begin{description}

\item[\normalfont \texttt{n}, \texttt{m}, \texttt{eval\_F}, \texttt{eval\_J}, \texttt{eval\_HF}, \texttt{params}, \texttt{options}, \texttt{inform}, and \texttt{weights}] are as described in Section~\ref{sec:solve}.

\itt{X} is an array of size {\tt n}. On the first call, it must hold the initial guess for
$\bm x$. On return it holds the value of $\bm x$ at the current iterate, and
must be passed unaltered to any subsequent call to \texttt{ral\_nlls\_iterate()}.

\itt{w} is workspace allocated and initialised through a previous call to
\texttt{ral\_nlls\_init\_workspace()}.

\end{description}

\subsubsection{To free a workspace when it is no longer required}

Memory allocated during the call to \texttt{ral\_nlls\_init\_workspace()} may be freed
by a call to the following subroutine:
\begin{verbatim}
   void ral_nlls_free_workspace(void **workspace);
\end{verbatim}

\begin{description}
   \itt{*workspace} is the workspace to be freed. On exit it will be set to \texttt{NULL}.
\end{description}

\subsection{User-supplied function evaluation routines}
\label{sec::function_eval}
In order to evaluate the function, Jacobian and Hessian at a point, the user
must supply callback functions that perform this operation that the code
{\tt ral\_nlls} will call internally.

In order to pass user-defined data into the evaluation calls, the parameter
\texttt{params} is passed unaltered to the callback functions. Typically this
will be a pointer to a user defined structure that stores the data to be fitted.

\subsubsection{For evaluating the function $\vr(\vx)$}

A subroutine must be supplied to calculate $\vr(\vx)$ for a given vector $\vx$.
It must have the following signature:
\begin{verbatim}
  int eval_r (int n, int m, void const* params, double const* x, double* r);
\end{verbatim}

\input{eval_r.tex}

\subsubsection{For evaluating the function $J = \nabla \vr(\iter{\vx})$}
A subroutine must be supplied to calculate $J = \nabla \vr(\iter{\vx})$ for a given vector $\vx$. It must have the following signature:

\begin{verbatim}
   int eval_j (int n, int m, void const* params, double const* x, double* J);
\end{verbatim}

\input{eval_j.tex}

\subsubsection{For evaluating the function $Hf = \sum_{i=1}^m r_i(\vx) \vW  \nabla^2 \vr_i(x)$}
A subroutine must be supplied to calculate $Hf = \sum_{i=1}^m (\vr)_i \nabla^2 r_i(\vx)$ for given vectors $\vx \in \mathbb{R}^n$ and $\vr \in \mathbb{R}^m$; here \((\vr)_i\) denotes the $i$th component of the vector $\vr$.
It must have the following signature

\begin{verbatim}
int eval_hf (int n, int m, void const* params, double const* x, double const* r, double* Hf);
\end{verbatim}

\input{eval_hf.tex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{The options derived data type}
\label{typeoptions}

\input{options_type.tex}

\subsection{The derived data type for holding information}
\label{typeinform}

\input{info_type.tex}

%%%%%%%%%%%%%%%%%%%%%% Warning and error messages %%%%%%%%%%%%%%%%%%%%%%%%

\hslerrors

A successful return from a subroutine in the package is indicated by
{\tt inform.status} having the value zero.
A non-zero value is associated with an error message that by default will
be output on the Fortran unit {\tt inform.error}.  This string is also passed to the
calling routine in {\tt inform.error\_message}.

\input{errors.tex}

\hslgeneral

\hslrestrictions {\tt m$\ge$n$\ge$1}.

\hslmethod
\label{method}

\input{method.tex}

\hslexample

\input{example_text.tex}

\verbatiminput{../example/C/nlls_example.c}

\end{document}