\section{GPU-enabled parallel Schr\"odinger simulations}
\label{sec:3D_Stirap_parallel_Schrodinger_simulations}

Here, we will introduce the problem of atomic transport in cold atomic systems, present the resulting model system, and give all the essential physics. Controlling the centre-of-mass movement of atoms has recently become a popular topic of investigation \cite{AO:SAP_REVIEW_2016}. One family of techniques that aim to solve this are those of \textit{spatial adiabatic passage}. In the following section we will describe the motivation, physical system, and the numerical implementation for the solution of the problem of transporting a single atom among three trapping potential wells. The fully three-dimensional numerical solution of this problem will then be provided using GPU computing methods, and the results discussed for both the physical and computing aspects.

For performance metrics, we will discuss the use of a GPU-enabled Schr\"odinger equation integrator developed by myself, based on and compared with the results of a multi-core MPI enabled version by T.~Morgan and N.~Crowley. The solution of the Schr\"odinger equation for a fully three-dimensional potential, will demonstrate the effectiveness and improved performance compared to standard HPC methods.

\subsection{Spatial adiabatic passage}
Controlling the internal degrees of freedom of atoms is well understood and many spectroscopic techniques exist. External degrees of freedom have, however, only recently become interesting due to the advancements in atom trapping, and techniques for controlling the centre of mass state of a single atom are still in development. One promising group of techniques for the generation of spatial superposition states or high fidelity transfer relies on ideas from spatial adiabatic passage (SAP) \cite{AO:SAP_REVIEW_2016}, which are analogous to STIRAP in optical systems~\cite{AO:Bergmann_jcp_2015}. These techniques are highly robust against variation in the system parameters \cite{Eckert:04}, but suffer from being slow due to the adiabatic requirement. The use of SAP has recently been experimentally demonstrated in Lieb lattices \cite{AO:Taie_oist_2016}, and many other accessible systems have been proposed \cite{Eckert:06,Morgan:11,Kohler:13}.

To describe the method for SAP, we will first consider the case of a two-state system, which can be realised using two separated harmonic potential traps, with ground states $| L \rangle$ and $| R \rangle$. A reduction of the distance between the traps will increase the coupling, and hence tunneling rate, between them. This can be modelled with a two-level Hamiltonian as
\begin{equation}
    H = -\frac{\hbar}{2}
    \begin{pmatrix}
        0 & J_{LR} \\
        J_{RL} & -2\Delta
    \end{pmatrix},
\end{equation}
where $J_{LR} = J_{RL}$ are the couplings between states, and $\Delta$ is the detuning of state $| R \rangle$, relative to $| L \rangle$. Assuming an atom initially localised in $| L \rangle$, and with an increase in coupling strength between the levels, the localised atom will tunnel from $| L \rangle$ to $| R \rangle $. However, this processes is difficult to control, as Rabi oscillations introduce an explicit time-dependence as
\begin{subequations}
\begin{align}
    |c_L(t)|^2 &\propto \sin^2 \frac{\omega t}{2} ,\\
    |c_R(t)|^2 &\propto \cos^2 \frac{\omega t}{2},
\end{align}
\end{subequations}
where the $|c_{L,R}(t)|^2$ are the populations of the respective states. This time dependence causes the atomic population to continuously tunnel between both traps. It will therefore require precise timing and control to ensure a full, robust transfer of population. From this we see that a double-well potential is a difficult system in which to realise coherent control, though methods such as rapid adiabatic passage (RAP) exist and can allow for this~\cite{AO:Vitanov_arpc_2001}. A more robust method, using three adjacent harmonic traps and the aforementioned matter-wave SAP process, can improve upon the standard double-well system. For this SAP technique, we model the trapping potentials arranged in a single line and coupled with their nearest neighbour only. For three equivalent potentials, $L,M,R$, with degenerate states $\{|L \rangle,|M\rangle,|R\rangle\}$, the system can be described by the Hamiltonian
\begin{equation}\label{eqn:sap_ham}
    H = -\frac{\hbar}{2}
    \begin{pmatrix}
        0 & J_{LM} & 0 \\
        J_{LM} & 0 & J_{MR} \\
        0 & J_{MR} & 0
    \end{pmatrix},
\end{equation}
where $J_{LM},~J_{MR}$ describe the left-middle and middle-right couplings respectively. Diagonalising this Hamiltonian gives three distinct eigenstates,

\begin{subequations}
\begin{align}
    | \pm \rangle &= \frac{J_{LM} |L\rangle \pm \sqrt{J_{LM}^2 + J_{MR}^2}|M\rangle + J_{MR} |R\rangle  }{\sqrt{2(J_{LM}^2 + J_{MR}^2)}}, \\
    | D \rangle &= \frac{J_{MR} |L\rangle }{\sqrt{J_{LM}^2 + J_{MR}^2}} - \frac{J_{LM} |R\rangle}{\sqrt{J_{LM}^2 + J_{MR}^2}},
\end{align}
\end{subequations}
with respective eigenvalues $E_{\pm} = \pm {\sqrt{J_{LM}^2 + J_{MR}^2}}$, $E_D = 0$.
Here, only one eigenstate is of interest. For the zero-valued eigenstate of this Hamiltonian, $|D \rangle$, known as the \textit{dark state}, the dependence on the middle potential vanishes. The state can be written as
\begin{equation}
 | D \rangle = \cos\ \Theta| L \rangle - \sin \Theta | R \rangle,
\end{equation}
where $\tan \Theta=J_{LM}/J_{MR}$ is the mixing angle, following directly from the trigonometric identities $\cos (\arctan (x)) = 1/\sqrt{1+x^2}$, $\sin (\arctan (x)) = x/\sqrt{1+x^2}$. From the adiabatic theorem of quantum mechanics, it is known that if a system has its Hamiltonian perturbed slowly enough, then we can follow its evolution ensuring that it always remains in an eigenstate of the Hamiltonian. By preparing the system in state $| L \rangle$, and varying $\Theta$ slowly, we can shift the population from the leftmost harmonic potential to the rightmost, without populating the center. To ensure full transfer from $|L \rangle$ to $| R \rangle$, the mixing angle must change smoothly from $\Theta = 0 \rightarrow \pi/2$. From the properties of $\arctan$, this can be achieved by applying the same spatial variation between $|M \rangle$ and $| R\rangle$, as between $|L \rangle$ and $| M\rangle$, with the latter coupling pulse following a delay, $\tau$. A diagram of this is given by Fig.~\ref{fig:ch3_stirap}. Due to the robustness of this process a variety of coupling profiles can be used \cite{AO:Bergmann_jcp_2015}, as long as they have a smoothly varying background envelope $p$ given by \cite{AO:Fewell_ausjp_1997}
\begin{subequations}
\begin{align}
    J_{LM}(t) &= J_0 p(t-\tau), \\
    J_{MR}(t) &= J_0 p(t).
\end{align}
\end{subequations}

Varying the couplings between the trapping potentials, and hence controlling this mixing angle, can be achieved by either lowering the barrier height of adjacent potentials, or decreasing the distance between them. Here, we will discuss varying the spatial separation of the traps.

\begin{figure}
    \centering
    \includegraphics[width=0.65\textwidth]{./ch3_numerics/stirap_delay}
    \caption{Three trapping potential model for matter-wave SAP. The atom (green) is initially localised in the leftmost potential, $|L\rangle$, at $t=0$, with the couplings between adjacent traps controlled by varying the distance dependent parameters $J_{LM}$, $J_{MR}$. By varying the couplings between traps in the manner shown, with $J_{MR}$ increasing initially, followed by $J_{LM}$ after a delay $\tau$, the atom is transferred completely from $|L\rangle$ to $| R \rangle$.}
    \label{fig:ch3_stirap}
\end{figure}

%With the rate of transfer between trapping potentials controlled by the couplings between potentials, any adjustment of the spatial separation between traps will adjust the tunneling rate, and hence couplings, as shown by Fig.~\ref{fig:ch3_stirap}.
Typically, any method to adjust the couplings would be performed with time-dependent potentials. However, a static potential variant can be considered using parallel atomic waveguides, where the separation varies as a function of distance along the parallel axis. If we consider an atom that travels along such a waveguide, the couplings, and hence tunneling rates, seen by the atom in the waveguide are altered as the atom propagates. Such work has been discussed and considered in a realistic system for two spatial dimensions \cite{OSullivan:10}. Although a two dimensional model is effective at describing much of the relevant dynamics, the realism of the model is reduced by the lack of a third dimension. This is due to the lack of effects stemming from dispersion, curvature of the waveguides, as well as the absence of any such eigenstates along this dimension.

\subsection{Atom-chip model}

As discussed previously, to fully understand ultracold atom dynamics in appropriately shaped waveguide systems we must investigate the fully three-dimensional model. One method of creating the required potential landscape in experiments is through the use of atom-chips \cite{AO:Bartenstein_ieee_2000,AO:Folman_prl_2000}. These systems consist of micro-fabricated current-carrying wires, and can be used to create a variety of trapping potential shapes for controlled guidance of the atomic centre-of-mass \cite{AO:Denschlag_prl_1999}. The currents produce a magnetic field around individual wires, each of which has a minima at the wire core. Assuming the wire thickness to be negligible, this magnetic field at position $\mathbf{r}$ can be calculated using the Biot--Savart law
\begin{equation}
    \mathbf{B}(\mathbf{r}) = \frac{\mu_0}{4\pi}\oint I \frac{\text{d}\mathbf{l}\times \hat{\mathbf{r}}^{'}}{|\mathbf{r^{'}}|^2},
\end{equation}
where $I$ is the current through the wire, $\mu_0$ is the vacuum permeability, $\text{d}\mathbf{l}$ is the differential wire length, and $\hat{\mathbf{r}}^{'}$ is the unit vector along $\mathbf{r^{'}} = \mathbf{r} - \mathbf{l}$. To be able to trap atoms the minima must be raised to a position above the wire surface. This can be done using an orthogonally applied bias field, ${B}_b$, which raises the minima to a height of
\begin{equation}
    \mathbf{r}_0 = \frac{\mu_0 I}{2\pi {B}_b},
\end{equation}
above the surface. Though, an issue still remains with the presence of the magnetic minima. If the field drops to zero at the centre of the trap, the atoms can be lost due to Majorana spin flips~\cite{AO:Brink_pra_2006}. This can be prevented with the application of an additional field, ${B}_{ip}$, parallel to the wire direction, lifting the degeneracy of the atomic states, and ensuring they remain trapped. Spatial and temporal adjustments of the potentials are possible, with a fine degree of control, either during the production process, or by using time-dependent currents. These have been studied extensively in recent years for highly controllable trapping potentials \cite{AO:Yun_optexp_2006,AO:Gallego_optlett_2009}, and as atomic manipulators \cite{AO:Bensky_qip_2011}.

For this work, we model the system as three adjacent wires on the atom-chip surface. The direction of propagation is along $z$, and an additional harmonic oscillator potential, $V_z = m\omega_z^2 (z-z_0)^2/2$, is applied in the same direction to impart motion to the atom, which is initially at the $z=0$ position of the atom-chip. We set $z_0 = (\max z)/2$ to ensure the oscillator potential is symmetric around the centre of the atomchip. This potential also conveniently guarantees that the wavefunction refocuses after the transition at the opposite side of the atom-chip. A schematic of the atom-chip device and the respective potentials is given by Fig.~\ref{fig:schematic_atom-chip}.

\begin{figure}[tb]
    \centering
  \includegraphics[width=0.45\textwidth]{ch3_numerics/MWSTIRAP/Schematic3}
  \includegraphics[width=0.45\textwidth]{ch3_numerics/MWSTIRAP/3dpot_schem}
  \caption{Schematic of the atom-chip and the resulting potentials. Reprinted from Morgan {\textit{et al}.}~\cite{AO:Morgan_pra_2013}.}
  \label{fig:schematic_atom-chip}
\end{figure}

The initial state is created by localising the atom with the help of a barrier at one end of the potential ($z=0$), and in the leftmost waveguide using an additional barrier potential. After finding the ground state, the barriers are removed, and the atom is allowed to propagate along the length of the waveguide. The populations in each waveguide $|c_{X}|^2$ are tracked at each step of the process as
\begin{equation}
    |c_X|^2 = \int\limits_{\mathcal{V}_X} d\mathbf{r}  \Psi^{*} \Psi
\end{equation}
where $\mathcal{V}_X$ is the volume encompassing each waveguide $X \in \{L,M,R\}$, and $\Psi$ is the state of the system.
The final populations were taken as the atom approached the other classical turning point of the harmonic oscillator along $z$. The fidelity of the process could then be calculated by comparing the initial populations in $| L \rangle$ and final ones in $|R \rangle$, as well as any ones left in $| M \rangle$.

Given that fully three-dimensional simulations of the Schr\"odinger equation are numerically expensive, the use of GPU computing methods were ideal for accelerating the simulation \cite{Num:Bauke_cpc_2011}. At the time of writing, as far as we had been aware, no other work using GPU computing to solve a three dimensional Schr\"odinger equation had been presented. We will now discuss the data and metadata of the simulations.

\subsection{3D Simulations}
\label{sec:Results}

Simulations of the proposed system assumed a single $^{6}$Li atom localised in the left \mbox{waveguide}. A localised harmonic oscillator potential was added along $z$, with the transverse guiding potential, and the resulting ground state solution found numerically. The harmonic oscillator width was chosen to closely match the expected size in the transverse direction. The atom was then allowed to propagate along the waveguide potential ($z$).

As the shift in magnetic moment of the atoms is given by $\Delta E = -\mu\cdot\mathbf{B}$, for regions with a larger magnetic field the atom will experience a greater energy shift, and thus the assumption of all traps being on resonance (degenerate) has to be carefully checked. In fact, the simulations showed that the addition of the magnetic fields stemming from the different wires at the center of the atom-chip leads to the central potential moving out of resonance with the outer two. To make SAP work, it therefore required adjusting the current in the central wire, such that the magnetic minima were in resonance within the tunneling region near the atom-chip centre. The resulting potentials for non-optimal (left) and optimal (middle) currents are shown in Fig.~\ref{fig:equaloptcurrent}, which also depicts a three dimensional isosurface of the potential minima along the chip surface for both situations (right).

\begin{figure}[tb]
    \centering
  \includegraphics[width=0.55\textwidth]{ch3_numerics/MWSTIRAP/potentials2.pdf}
  \includegraphics[width=0.3\textwidth]{ch3_numerics/MWSTIRAP/3dpot.pdf}
  \caption{(Left) Two dimensional slices through the potential centre along $x-z$ (top) and tunneling region in $x-y$ (bottom). The out of resonance middle trapping potential can be seen where all three currents are the same. (Middle) Optimised currents which allow the same field value in the tunneling region ensure that the potentials are in resonance with each other. (Right) 3D isosurface plots of the numerically calculated magnetic minima potentials showing the out of resonance (a) and optimal (b) fields. Adapated from Morgan {\textit{et al}.}~\cite{AO:Morgan_pra_2013}.}
  \label{fig:equaloptcurrent}
\end{figure}
The populations for both the direct tunneling case, and the matter-wave SAP processes are shown in Fig.~\ref{fig:mwsVsDT}. The direct tunneling case can be seen to show Rabi-type oscillations between the waveguides, while the matter-wave SAP process shows a much cleaner transfer, and only a minor occupation of the central potential. The dependence of the transfer probability on the current in the central wire is shown in Fig.~\ref{fig:DIRVSMWSTIRAP}.

\begin{figure}[tb]
    \centering
  \includegraphics[width=0.47\textwidth,trim=2cm 5cm 2cm 5cm]{ch3_numerics/MWSTIRAP/STIRAP_CINT_POP.pdf}
  \includegraphics[width=0.47\textwidth,trim=2cm 5cm 2cm 5cm]{ch3_numerics/MWSTIRAP/STIRAP_INT_POP.pdf}
  \caption{Transfer fidelities for the three trapping potentials are given over time for both the matter-wave SAP process (left, particle starting in $ |L\rangle$) and direct tunneling (right, particle starting in $ |L\rangle$). Matter-wave SAP clearly shows greater population transfer in comparison with a direct tunneling approach. Reprinted from Morgan {\textit{et al}.}~\cite{AO:Morgan_pra_2013}.}
  \label{fig:mwsVsDT}
\end{figure}

\begin{figure}[tb]
    \centering
  \includegraphics[width=0.45\textwidth]{ch3_numerics/MWSTIRAP/SAPvsDirect.pdf}
  \caption{The final state population versus middle wire current for direct tunneling and matter-wave SAP. The robustness of the SAP technique can be seen, and gives a large range of currents with population transfer fidelity $\approx 99 \%$. The oscillations in the direct tunneling regime are due to the presence of time-dependent Rabi couplings. Reprinted from Morgan {\textit{et al}.}~\cite{AO:Morgan_pra_2013}.}
  \label{fig:DIRVSMWSTIRAP}
\end{figure}

\subsection{GPU computing performance}
Given the large parameter space over which this system could be evaluated (e.g wire current, spatial separations, trap frequencies), a large number of simulations were required to determine optimal system behaviour. As discussed in Sec.~\ref{sec:cuda_prog}, one example where GPU computing offers large performance gains are FFTs, which makes the Fourier split operator method an ideal candidate for GPU systems \cite{Num:Bauke_cpc_2011}. The body of work for implementing this algorithm was using C, CUDA and Nvidia's CUFFT libraries for the Fourier transforms, whereas the MPI-enabled code was implemented using C.

To demonstrate the performance offered by GPU computing we compared it to using FFTW with MPI, a well used parallel programming library and paradigm. The MPI implementation allows code to be run across multiple machines, benefiting from the parallelism which may be offered by a supercomputing cluster. Although MPI-enabled FFTW is fast and supports extremely large grid sizes, it requires cluster access of a significant size to be a viable option for this type of system. The MPI work on this project was carried out on the Irish Center for High-End Computing (ICHEC) supercomputer system ``Stoney'' \cite{Ichec_stoney} over the period 2011 to 2012, with all performance metrics data calculated therefrom. This cluster system had 64 available compute nodes, each housing two 2.8GHz Intel Xeon X5560 processors with 4-cores each, and a total of 48GB of RAM per node with inter-node communication using double data rate Infiniband.

Due to the hardware limited memory on the GPU, and because the dynamics along the $x-z$ plane were of most importance, the grid-size of the simulations were scaled as $256\times 64\times1024$ ($x\times y\times z$). Of next importance were the choice of timesteps for the simulations. To ensure minimal loss in accuracy, the timesteps were chosen as $\Delta t = 10^{-6}$ s. By approximating the waveguides as harmonic oscillators, the relevant timescales of the dynamics are of the order $T_{\textrm{t}}\approx 10^{-4}$ s, and so we can accurately capture all relevant dynamics in the transverse direction. The timescales in the longitudinal direction, which requires a large oscillation period compared to the transverse plane to ensure the adiabaticity condition ($T_{\textrm{l}}\approx 10^{-1}$ s), are also fulfilled. For the GPU simulations, the test system was an Intel Core i7 2600K CPU at stock frequency, 8GB DDR3 memory operating at 1600 MHz, 7200 RPM HDD, Nvidia GeForce GTX 580 with 3GB of onboard memory running at 783 MHz GPU core frequency, 1566 MHz shader processor frequency, and 2010 MHz memory frequency. For all simulations the desktop was running Ubuntu 11.10 64-bit operating system and all calculations were performed in double precision (64-bit floating point) where applicable.

Table \ref{tbl:timing} shows the approximate timings for the completion of runs using GPU and CPU codes. Not only does GPU computing offer a 6-fold improvement over a single CPU, it also allows us to achieve a performance level which is comparable to an 8-node 8-core (64 cores) core MPI enabled CPU calculation. Even for a modest choice of gaming GPU this offers substantial performance gains. Higher performance was achieved by using specific compute accelerators designed for double precision arithmetic. Making use of eight Nvidia M2090 GPUs available at OIST, terabytes of numerical results were generated, and allowed the problem to become tractable on a short timescale.

\begin{table}[tb]
  \begin{center}
    \begin{tabular}{|c||c|c|c|}
      \hline
      Device & Num. Devices & Timing  & Rel. Improvement \\ \hline
      CPU (MPI) & 8 & $\sim$6 Hr & 1.0$\times$ \\
      & 16 & $\sim$4 Hr & 1.5$\times$ \\
      & 32 & $\sim$1.5 Hr & 4.0$\times$ \\
      & 64 & $\sim$1 Hr & 6.0$\times$ \\ \hline
      GPU & 1 & $\sim$1 Hr & 6.0$\times$ \\ \hline
    \end{tabular}
  \end{center}
   \caption{The approximate times taken to simulate the propagation of an atom through the atom chip system on both GPU and CPU. Reprinted from Morgan {\textit{et al}.}~\cite{AO:Morgan_pra_2013}.}
   \label{tbl:timing}
\end{table}


% Created 2020-09-21 lun 18:01
% Intended LaTeX compiler: pdflatex
\documentclass[presentation,aspectratio=169, usenames, dvipsnames]{beamer}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{graphicx}
\usepackage{grffile}
\usepackage{longtable}
\usepackage{wrapfig}
\usepackage{rotating}
\usepackage[normalem]{ulem}
\usepackage{amsmath}
\usepackage{textcomp}
\usepackage{amssymb}
\usepackage{capt-of}
\usepackage{hyperref}
\usepackage{khpreamble}
\usepackage{amssymb}
\usepgfplotslibrary{groupplots}
\usepackage{pgfplotstable}
\newcommand*{\shift}{\operatorname{q}}
\definecolor{ppc}{rgb}{0.1,0.1,0.6}
\definecolor{iic}{rgb}{0.6,0.1,0.1}
\definecolor{ddc}{rgb}{0.1,0.6,0.1}
\usetheme{default}
\author{Kjartan Halvorsen}
\date{2020-09-21}
\title{Process Automation Laboratory - Anti windup}
\hypersetup{
 pdfauthor={Kjartan Halvorsen},
 pdftitle={Process Automation Laboratory - Anti windup},
 pdfkeywords={},
 pdfsubject={},
 pdfcreator={Emacs 26.3 (Org mode 9.3.6)},
 pdflang={English}}
\begin{document}

\maketitle

\section{Context}
\label{sec:orgd19de8a}
\begin{frame}[label={sec:org69a135a}]{Two -tank model}
\begin{center}
\includegraphics[width=\linewidth]{../../figures/two-tanks-shutoff-valve}
\end{center}
\end{frame}

\section{Repetition PID}
\label{sec:org795dfcf}
\begin{frame}[label={sec:org9f8e291}]{Feedback control}
   \begin{center}
   \begin{tikzpicture}[node distance=22mm, block/.style={rectangle, draw, minimum width=15mm}, sumnode/.style={circle, draw, inner sep=2pt}]
  {
  \node[coordinate] (input) {};
  \node[sumnode, right of=input] (sum) {\tiny $\sum$};
  \node[block, right of=sum, node distance=2.6cm] (reg) {$F(s)$};
  \node[block, right of=reg, node distance=2.6cm] (plant) {$G(s)$};
  \node[coordinate, right of=plant, node distance=2cm] (output) {};
  \node[coordinate, below of=plant, node distance=12mm] (feedback) {};

  \draw[->] (plant) -- node[coordinate, inner sep=0pt] (meas) {} node[near end, above] {$y(t)$} (output);
  \draw[->] (meas) |- (feedback) -| node[very near end, left] {$-$} (sum);
  \draw[->] (input) -- node[very near start, above] {$r(t)$} (sum);
  \draw[->] (sum) -- node[above] {$e(t)$} (reg);
  \draw[->] (reg) -- node[above] {$u(t)$}(plant);
}
\end{tikzpicture}
\end{center}
\end{frame}

\begin{frame}[label={sec:org99d6d2f}]{The PID - practical form}
\definecolor{ppc}{rgb}{0.1,0.1,0.6}
\definecolor{iic}{rgb}{0.6,0.1,0.1}
\definecolor{ddc}{rgb}{0.1,0.5,0.1}

\begin{center}
  \begin{tikzpicture}[node distance=22mm, block/.style={rectangle, draw, minimum width=15mm}, sumnode/.style={circle, draw, inner sep=2pt}]

    \node[coordinate] (input) {};
    \node[sumnode, right of=input, node distance=16mm] (sum) {\tiny $\Sigma$};
    \node[color=iic,block, right of=sum, node distance=28mm] (ii)  {$\frac{1}{\tau_is}$};
    \node[color=ppc, coordinate, above of=ii, node distance=10mm] (pp)  {};
    \node[color=ddc,block, below of=ii, node distance=13mm] (dd)  {$\frac{\tau_ds}{\frac{\tau_d}{N}s + 1}$};
    \node[sumnode, right of=ii, node distance=20mm] (sum2) {\tiny $\Sigma$};
    \node[block, right of=sum2, node distance=20mm] (gain)  {$k_c$};
    \node[coordinate, below of=sum, node distance=12mm] (feedback) {};
    \node[coordinate, right of=gain, node distance=20mm] (output) {};

    \draw[->] (input) -- node[above, pos=0.3] {$r(t)$} (sum);
    \draw[->] (sum) -- node[above, pos=0.2] {$e(t)$} node[coordinate] (mm) {}  (ii);
    \draw[->] (gain) -- node[above, near end] {$u(t)$} (output);
    \draw[->] (feedback) -- node[left, near start] {$y(t)$} node[right, pos=0.95] {-} (sum);
    \draw[->, color=ppc] (mm) |- (pp) -| node[right,] {$u_P(t)$} (sum2);
    \draw[->, color=ddc] (feedback |- dd) -- node[above, pos=0.95] {-} (dd);
    \draw[->, color=ddc] (dd) -| node[right,] {$u_D(t)$} (sum2)  ;
    \draw[->, color=iic] (ii)  -- node[above,] {$u_I(t)$} (sum2);
    \draw[->] (sum2) -- node[above, near end] {} (gain);

  \end{tikzpicture}
\end{center}

The parameter \(N\) is chosen to limit the influence of noisy measurements. Typically,
\[  3 < N < 20 \]
\end{frame}

\begin{frame}[label={sec:org879c25a}]{The PID - practical aspects}
{\footnotesize Åström \& Hägglund (1988) \emph{PID controllers: Theory, design and tuning, 2nd ed} Instrument Society of America.}

\begin{block}{Approximating nonlinear systems with linear models}
\begin{itemize}
\item Model is accurate only in neighborhood of operating point for which system is approximated.
\item Solution: Divide operating range into many regions, with separate PID parameters for each region
\end{itemize}
\end{block}

\begin{block}{Approximating high-order systems with low-order models}
\begin{itemize}
\item Only accurate for low frequencies
\item Beware of behavior for high-frequency input to the closed-loop system
\end{itemize}
\end{block}
\end{frame}

\begin{frame}[label={sec:org2090f62}]{The PID - practical aspects, contd}
\begin{block}{When do PID controllers work well?}
\begin{itemize}
\item The plant dynamics can be well approximated with low-order model
\item Demands on performance not too high
\end{itemize}
\end{block}
\begin{block}{More sophisticated control needed when}
\begin{itemize}
\item Higher order dynamics
\item Oscillatory modes
\item Long deadtime
\end{itemize}
\end{block}
\end{frame}

\begin{frame}[label={sec:org2acf1f0}]{The PID - practical aspects, contd}
\begin{block}{Choice of controller}
\begin{enumerate}
\item P-controller if damping and steady-state error satisfied
\item PI-controller if steady-state error must be zero (often 1st order dynamics)
\item PID-controller if PI does not give sufficient damping (often 2nd order dynamics)
\item Tuning parameter \(\tau_c\) for SIMC tuning method:
\begin{itemize}
\item Smaller (=faster) than \(\tau\) if sufficiently damped and limitations on input signal not violated.
\item larger (=slower) than \(\tau\) if more damping required or smaller input signal required.
\end{itemize}
\end{enumerate}
\end{block}
\end{frame}

\begin{frame}[label={sec:orgf21026c}]{The PID - Parallel form, solution}
\(u(t) = k_c\Big( \textcolor{ppc}{e(t)} + \textcolor{iic}{\overbrace{\frac{1}{\tau_i} \int_0^{t} e(\xi) d\xi}^{u_I(t)}} + \textcolor{ddc}{ \underbrace{\tau_d \frac{d}{dt} \big(-y(t)\big)}_{u_D(t)}} \Big)\)
   \begin{center}
   \def\TT{1}
   \begin{tikzpicture}
   \begin{axis}[
    clip=false,
    width=14cm,
    height=5cm,
    ylabel={},
    xlabel={$t$},
    ymax = 2,
    ]
      \addplot[black, no marks, domain=-0.1:8, samples=200] {(x>0)*(1 - (1+x/\TT)*exp(-x/\TT)} node[coordinate, pin=-20:{$y(t)$}, pos=0.4] {};
      \addplot[magenta!70!black, no marks, domain=-0.1:8, samples=200] coordinates {(-0.1, 0) (0,0) (0,1) (8,1)} node[coordinate, pin=90:{$r(t)$}, pos=0.21] {};
      \addplot[color=ppc, no marks, domain=0:8, samples=200] {(x>=0)*( (1+x/\TT)*exp(-x/\TT)} node[coordinate, pin=20:{$e(t)$}, pos=0.7] {};
      \addplot[color=iic, no marks, domain=-0.1:8, samples=200] {(x>0)*(2*(1-exp(-x/\TT)) - \x/\TT*exp(-x/\TT))} node[coordinate, pin=-20:{$u_I(t)$}, pos=0.6] {};
      \addplot[color=ddc, no marks, domain=-0.1:8, samples=200] {(x>0)*(-\x/\TT*exp(-x/\TT))} node[coordinate, pin=-20:{$u_D(t)$}, pos=0.4] {};
    \end{axis}

 \end{tikzpicture}
\end{center}
\end{frame}

\begin{frame}[label={sec:org432862f}]{The PID - Integral signal}
\begin{center}
  \begin{tikzpicture}[node distance=22mm, block/.style={rectangle, draw, minimum width=15mm}, sumnode/.style={circle, draw, inner sep=2pt}, scale=0.6, every node/.style={scale=0.6}]

    \node[coordinate] (input) {};
    \node[sumnode, right of=input, node distance=16mm] (sum) {\tiny $\Sigma$};
    \node[color=iic,block, right of=sum, node distance=28mm] (ii)  {$\frac{1}{\tau_is}$};
    \node[color=ppc, coordinate, above of=ii, node distance=10mm] (pp)  {};
    \node[color=ddc,block, below of=ii, node distance=10mm] (dd)  {$\tau_ds$};
    \node[sumnode, right of=ii, node distance=20mm] (sum2) {\tiny $\Sigma$};
    \node[block, right of=sum2, node distance=20mm] (gain)  {$k_c$};
    \node[coordinate, below of=sum, node distance=12mm] (feedback) {};
    \node[coordinate, right of=gain, node distance=20mm] (output) {};

    \draw[->] (input) -- node[above, pos=0.3] {$r(t)$} (sum);
    \draw[->] (sum) -- node[above, pos=0.2] {$e(t)$} node[coordinate] (mm) {}  (ii);
    \draw[->] (gain) -- node[above, near end] {$u(t)$} (output);
    \draw[->] (feedback) -- node[left, near start] {$y(t)$} node[right, pos=0.95] {-} (sum);
    \draw[->, color=ppc] (mm) |- (pp) -| node[right,] {$u_P(t)$} (sum2);
    \draw[->, color=ddc] (feedback |- dd) -- node[above, pos=0.95] {-} (dd) -| node[right,] {$u_D(t)$}   (sum2);
    \draw[->, color=iic] (ii)  -- node[above,] {$u_I(t)$} (sum2);
    \draw[->] (sum2) -- node[above, near end] {} (gain);

  \end{tikzpicture}
  \small
  \(  u(t) = k_c\Big( \textcolor{ppc}{e(t)} + \textcolor{iic}{\overbrace{\frac{1}{\tau_i} \int_0^{t} e(\xi) d\xi}^{u_I(t)}} + \textcolor{ddc}{ \underbrace{\tau_d \frac{d}{dt} \big(-y(t)\big)}_{u_D(t)}} \Big)\)
\end{center}

   \begin{center}
   \def\wn{2}
   \def\zz{0.3}
   \pgfmathsetmacro{\wwd}{\wn*sqrt(1-\zz*\zz)}
   \pgfmathsetmacro{\zwn}{\zz*\wn}
  \pgfmathsetmacro{\thangle}{acos(\zz)}
   \begin{tikzpicture}
   \begin{axis}[
    clip=false,
    width=14cm,
    height=4.5cm,
    ylabel={},
    xlabel={$t$},
    ymax = 2,
    ymin = -0.5,
    ]
      \addplot[black, no marks, domain=-0.4:8, samples=200] {(x>0)*(1 - exp(-x * \zwn)/sqrt(1-\zz*\zz) * sin(deg(\wwd*x) + \thangle))} node[coordinate, pin=20:{$y(t)$}, pos=0.3] {};
      \addplot[magenta!70!black, no marks, domain=-0.4:8, samples=200] coordinates {(-0.4, 0) (0,0) (0,1) (8,1)} node[coordinate, pin=90:{$r(t)$}, pos=0.2] {};
    \end{axis}

 \end{tikzpicture}
\end{center}

\alert{Activity} Sketch the error signal \(e(t)\) and the integral signal \(u_I(t)\) (use \(\tau_i=1\))
\end{frame}

\begin{frame}[label={sec:org642bfac}]{The PID - Integral signal - Solution}
   \def\wn{2}
   \def\zz{0.3}
   \pgfmathsetmacro{\wwd}{\wn*sqrt(1-\zz*\zz)}
   \pgfmathsetmacro{\zwn}{\zz*\wn}
  \pgfmathsetmacro{\thangle}{acos(\zz)}
\pgfplotstablenew[ create on use/x/.style={ create col/expr={\pgfplotstablerow/50} },    create on use/y/.style={ create col/expr={ exp(-\thisrow{x} * \zwn)/sqrt(1-\zz*\zz) * sin(deg(\wwd*\thisrow{x}) + \thangle)} }, create on use/int/.style={       create col/expr={\pgfmathaccuma+(\thisrow{y}+\prevrow{y})/2*(\thisrow{x}-\prevrow{x})} }, columns={x,y,int}]{400} \pidtable

\begin{center}
  \begin{tikzpicture}[node distance=22mm, block/.style={rectangle, draw, minimum width=15mm}, sumnode/.style={circle, draw, inner sep=2pt}, scale=0.6, every node/.style={scale=0.6}]

    \node[coordinate] (input) {};
    \node[sumnode, right of=input, node distance=16mm] (sum) {\tiny $\Sigma$};
    \node[color=iic,block, right of=sum, node distance=28mm] (ii)  {$\frac{1}{\tau_is}$};
    \node[color=ppc, coordinate, above of=ii, node distance=10mm] (pp)  {};
    \node[color=ddc,block, below of=ii, node distance=10mm] (dd)  {$\tau_ds$};
    \node[sumnode, right of=ii, node distance=20mm] (sum2) {\tiny $\Sigma$};
    \node[block, right of=sum2, node distance=20mm] (gain)  {$k_c$};
    \node[coordinate, below of=sum, node distance=12mm] (feedback) {};
    \node[coordinate, right of=gain, node distance=20mm] (output) {};

    \draw[->] (input) -- node[above, pos=0.3] {$r(t)$} (sum);
    \draw[->] (sum) -- node[above, pos=0.2] {$e(t)$} node[coordinate] (mm) {}  (ii);
    \draw[->] (gain) -- node[above, near end] {$u(t)$} (output);
    \draw[->] (feedback) -- node[left, near start] {$y(t)$} node[right, pos=0.95] {-} (sum);
    \draw[->, color=ppc] (mm) |- (pp) -| node[right,] {$u_P(t)$} (sum2);
    \draw[->, color=ddc] (feedback |- dd) -- node[above, pos=0.95] {-} (dd) -| node[right,] {$u_D(t)$}   (sum2);
    \draw[->, color=iic] (ii)  -- node[above,] {$u_I(t)$} (sum2);
    \draw[->] (sum2) -- node[above, near end] {} (gain);

  \end{tikzpicture}
  \small
  \(  u(t) = k_c\Big( \textcolor{ppc}{e(t)} + \textcolor{iic}{\overbrace{\frac{1}{\tau_i} \int_0^{t} e(\xi) d\xi}^{u_I(t)}} + \textcolor{ddc}{ \underbrace{\tau_d \frac{d}{dt} \big(-y(t)\big)}_{u_D(t)}} \Big)\)
\end{center}

   \begin{center}
   \def\wn{2}
   \def\zz{0.3}
   \pgfmathsetmacro{\wwd}{\wn*sqrt(1-\zz*\zz)}
   \pgfmathsetmacro{\zwn}{\zz*\wn}
  \pgfmathsetmacro{\thangle}{acos(\zz)}
   \begin{tikzpicture}
   \begin{axis}[
    clip=false,
    width=14cm,
    height=4.5cm,
    ylabel={},
    xlabel={$t$},
    ymax = 2,
    ymin = -0.5,
    ]
      \addplot[black, no marks, domain=-0.4:8, samples=200] {(x>0)*(1 - exp(-x * \zwn)/sqrt(1-\zz*\zz) * sin(deg(\wwd*x) + \thangle))} node[coordinate, pin=20:{$y(t)$}, pos=0.3] {};
      \addplot[color=ppc, no marks, domain=-0.4:8, samples=600] {(x>0)*(exp(-x * \zwn)/sqrt(1-\zz*\zz) * sin(deg(\wwd*x) + \thangle))} node[coordinate, pin=200:{$e(t)$}, pos=0.3] {};
      \addplot [color=iic, thick] table [y=int] {\pidtable};
      \addplot[magenta!70!black, no marks, domain=-0.4:8, samples=200] coordinates {(-0.4, 0) (0,0) (0,1) (8,1)} node[coordinate, pin=90:{$r(t)$}, pos=0.2] {};
    \end{axis}

 \end{tikzpicture}
\end{center}
\end{frame}

\section{Windup}
\label{sec:orgdc284b6}

\begin{frame}[label={sec:org744d11d}]{Integral windup}
\href{https://tecdemonterrey.instructuremedia.com/embed/6fb197b1-38a6-4938-b622-b25d4a45efcc}{Video by Tomás Alejandro Lugo Salinas (MTY)}
\end{frame}

\section{Anti-windup}
\label{sec:org744d659}

\begin{frame}[label={sec:org60c71b8}]{Anti-windup using back-calculation}
\begin{center}
\includegraphics[width=1.02\linewidth]{../../figures/anti-windup-back-calculation.png}
\end{center}
\end{frame}
\end{document}


\newpage
\section{Variables}

\begin{Variable}[assumptions]{ASSUMPTIONS}
\index{solve}
After solving a linear or polynomial equation system
with parameters, the variable \name{assumptions} contains a list
of side relations for the parameters. The solution is valid only
as long as none of these expression is zero.
\begin{Examples}
solve({a*x-b*y+x,y-c},{x,y});&
\{\{x=\rfrac{b*c}{a + 1},y=c\}\} \\
assumptions; & \{a + 1\}
\end{Examples}
\end{Variable}

\begin{Variable}[card_no]{CARD_NO}
\index{FORTRAN}\index{output}
\name{card_no} sets the total number of cards allowed in a Fortran
output statement when \name{fort} is on.  Default is 20.

\begin{Examples}
on fort; \\
card_no := 4;                &         CARD_NO=4. \\
z := (x + y)**15;            &
\begin{multilineoutput}{6cm}
      ANS1=5005.*X**6*Y**9+3003.*X**5*Y**10+1365.*X**4*Y**
     . 11+455.*X**3*Y**12+105.*X**2*Y**13+15.*X*Y**14+Y**15
      Z=X**15+15.*X**14*Y+105.*X**13*Y**2+455.*X**12*Y**3+
     . 1365.*X**11*Y**4+3003.*X**10*Y**5+5005.*X**9*Y**6+
     . 6435.*X**8*Y**7+6435.*X**7*Y**8+ANS1
\end{multilineoutput}
\end{Examples}

\begin{Comments}
Twenty total cards means 19 continuation cards.  You may set it for more
if your Fortran system allows more.  Expressions are broken apart in a
Fortran-compatible way if they extend for more than \name{card_no}
continuation cards.
\end{Comments}
\end{Variable}

\begin{Constant}[e]{E}
The constant \name{e} is reserved for use as the base of the natural
logarithm.  Its value is approximately 2.71828284590, which REDUCE gives
to the current decimal precision when the switch \nameref{rounded} is on.

\begin{Comments}
\name{e} may be used as an iterative variable in a \nameref{for} statement,
or as a local variable or a \nameref{procedure}.  If \name{e} is defined
as a local
variable inside the procedure, the normal definition as the base of the
natural logarithm would be suspended inside the procedure.
\end{Comments}
\end{Constant}

\begin{Variable}[eval\_mode]{EVAL\_MODE}
\index{algebraic}\index{symbolic}
The system variable \name{eval\_mode} contains the current mode, either
\nameref{algebraic} or \nameref{symbolic}.

\begin{Examples}
EVAL\_MODE;                  &        ALGEBRAIC
\end{Examples}

\begin{Comments}
Some commands do not behave the same way in algebraic and symbolic modes.
%You can determine what mode you are in without using this command by noting
%that the numbered prompt in algebraic mode contains a colon (\name{:}), while
%the numbered prompt in symbolic mode contains an asterisk (\name{*}).
\end{Comments}
\end{Variable}

\begin{Variable}[fort\_width]{FORT\_WIDTH}
\index{output}\index{FORTRAN}
The \name{fort\_width} variable sets the number of characters in a line of
Fortran-compatible output produced when the \nameref{fort} switch is on.
Default is 70.

\begin{Examples}
fort_width := 30;            &         FORT\_WIDTH := 30  \\
on fort; \\
df(sin(x**3*y),x);           &         \begin{multilineoutput}{3cm}
      ANS=3.*COS(X
     . **3*Y)*X**2*
     . Y
\end{multilineoutput}
\end{Examples}

\begin{Comments}
\name{fort\_width} includes the usually blank characters at the beginning
of the card.  As you may notice above, it is conservative and makes the
lines even shorter than it was told.
\end{Comments}
\end{Variable}

\begin{Variable}[high_pow]{HIGH\_POW}
\index{polynomial}\index{degree}
The variable \name{high\_pow} is set by \nameref{coeff} to the highest power
of the variable of interest in the given expression.  You can access this
variable for use in further computation or display.

\begin{Examples}
coeff((x+1)^5*(x*(y+3)^2)^2,x); &
\begin{multilineoutput}{6cm}
\{0,
 0,
 Y^{4} + 12*Y^{3} + 54*Y^{2} + 108*Y + 81,
 5*(Y^{4} + 12*Y^{3} + 54*Y^{2} + 108*Y + 81),
 10*(Y^{4} + 12*Y^{3} + 54*Y^{2} + 108*Y + 81),
 10*(Y^{4} + 12*Y^{3} + 54*Y^{2} + 108*Y + 81),
 5*(Y^{4} + 12*Y^{3} + 54*Y^{2} + 108*Y + 81),
 Y^{4} + 12*Y^{3} + 54*Y^{2} + 108*Y + 81\}
\end{multilineoutput} \\
high_pow;                    &        7
\end{Examples}
\end{Variable}

\begin{Constant}{I}
\index{complex}
REDUCE knows \name{i} is the square root of -1,
 and that \IFTEX{$i^2 = -1$}{i^2 = -1}.

\begin{Examples}
(a + b*i)*(c + d*i);         &      A*C + A*D*I + B*C*I - B*D \\
i**2;                        &      -1
\end{Examples}

\begin{Comments}
\name{i} cannot be used as an identifier.  It is all right to use \name{i}
as an index variable in a \name{for} loop, or as a local (\name{scalar})
variable inside a \name{begin...end} block, but it loses its definition as
the square root of -1 inside the block in that case.

Only the simplest properties of \IFTEX{$i$}{i} are known by REDUCE unless
the switch \nameref{complex} is turned on, which implements full complex
arithmetic in factoring, simplification, and functional values.
\name{complex} is ordinarily off.
\end{Comments}
\end{Constant}

\begin{Constant}[infinity]{INFINITY}
The name \name{infinity} is used to represent the infinite positive number.
However, at the present time, arithmetic in terms of this operator reflects
finite arithmetic, rather than true operations on infinity.

\end{Constant}

\begin{Variable}[low\_pow]{LOW\_POW}
\index{degree}\index{polynomial}
The variable \name{low\_pow} is set by \nameref{coeff} to the lowest power
of the variable of interest in the given expression.  You can access this
variable for use in further computation or display.

\begin{Examples}
coeff((x+2*y)**6,y);        &
\begin{multilineoutput}{6cm}
\{X^{6},
 12*X^{5},
 60*X^{4},
 160*X^{3},
 240*X^{2},
 192*X,
 64\}
\end{multilineoutput}\\
low_pow;                    &      0 \\
coeff(x**2*(x*sin(y) + 1),x);
			    &      \{0,0,1,SIN(Y)\} \\
low_pow;                    &      2
\end{Examples}

\end{Variable}

\begin{Constant}[nil]{NIL}
\index{false}
\name{nil} represents the truth value {\it false} in symbolic mode, and is
a synonym for 0 in algebraic mode.  It cannot be used for any other
purpose, even inside procedures or \nameref{for} loops.
\end{Constant}

\begin{Constant}[pi]{PI}
The identifier \name{pi} is reserved for use as the circular constant.
Its value is given by 3.14159265358..., which REDUCE gives to the current
decimal precision when REDUCE is in a floating-point mode.

\begin{Comments}
\name{pi} may be used as a looping variable in a \nameref{for} statement,
or as a local variable in a \nameref{procedure}.  Its value in such cases
will be taken from the local environment.
\end{Comments}
\end{Constant}

\begin{Variable}[requirements]{REQUIREMENTS}
\index{solve}
After an attempt to solve an inconsistent equation system
with parameters, the variable \name{requirements} contains a list
of expressions. These expressions define a set of conditions implicitly
equated with zero. Any solution to this system defines a setting for
the parameters sufficient to make the original system consistent.
\begin{Examples}
solve({x-a,x-y,y-1},{x,y}); & \{\}\\
requirements;&\{a - 1\}
\end{Examples}
\end{Variable}

\begin{Variable}[root\_multiplicities]{ROOT\_MULTIPLICITIES}
\index{root}\index{solve}\index{polynomial}
The \name{root\_multiplicities} variable is set to the list of the
multiplicities of the roots of an equation by the \nameref{solve} operator.

\begin{Comments}
\nameref{solve} returns its solutions in a list.  The multiplicities of
each solution are put in the corresponding locations of the list
\name{root\_multiplicities}.
\end{Comments}
\end{Variable}

\begin{Constant}[t]{T}
The constant \name{t} stands for the truth value {\it true}.  It cannot be used
as a scalar variable in a \nameref{block}, as a looping variable in a
\nameref{for} statement or as an \nameref{operator} name.

\end{Constant}


\hypertarget{structIir_1_1Butterworth_1_1HighShelf}{}\doxysubsection{Iir\+::Butterworth\+::High\+Shelf$<$ Filter\+Order, State\+Type $>$ Struct Template Reference}
\label{structIir_1_1Butterworth_1_1HighShelf}\index{Iir::Butterworth::HighShelf$<$ FilterOrder, StateType $>$@{Iir::Butterworth::HighShelf$<$ FilterOrder, StateType $>$}}

{\ttfamily \#include $<$Butterworth.\+h$>$}

Inheritance diagram for Iir\+::Butterworth\+::High\+Shelf$<$ Filter\+Order, State\+Type $>$\+:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[height=2.400000cm]{structIir_1_1Butterworth_1_1HighShelf}
\end{center}
\end{figure}
\doxysubsubsection*{Public Member Functions}
\begin{DoxyCompactItemize}
\item
void \mbox{\hyperlink{structIir_1_1Butterworth_1_1HighShelf_a19a78cb96c9b2454ccb48745ed50500d}{setup}} (double sample\+Rate, double cutoff\+Frequency, double gain\+Db)
\item
void \mbox{\hyperlink{structIir_1_1Butterworth_1_1HighShelf_aa7fecdca7646acf8962c5d0106fb8b3c}{setup}} (int req\+Order, double sample\+Rate, double cutoff\+Frequency, double gain\+Db)
\item
void \mbox{\hyperlink{structIir_1_1Butterworth_1_1HighShelf_af63e4f43001ae2d9faf44ba6496db562}{setupN}} (double cutoff\+Frequency, double gain\+Db)
\item
void \mbox{\hyperlink{structIir_1_1Butterworth_1_1HighShelf_a7df553be87ce22541c6ffa8af7508898}{setupN}} (int req\+Order, double cutoff\+Frequency, double gain\+Db)
\end{DoxyCompactItemize}

\doxysubsubsection{Detailed Description}
\subsubsection*{template$<$int Filter\+Order = 4, class State\+Type = Direct\+Form\+II$>$\newline
struct Iir\+::\+Butterworth\+::\+High\+Shelf$<$ Filter\+Order, State\+Type $>$}

\mbox{\hyperlink{namespaceIir_1_1Butterworth}{Butterworth}} high shelf filter. Above the cutoff the filter has a specified gain and below it has 0 dB.
\begin{DoxyParams}{Parameters}
{\em Filter\+Order} & Reserves memory for a filter of the order Filter\+Order \\
\hline
{\em State\+Type} & The filter topology\+: \mbox{\hyperlink{classIir_1_1DirectFormI}{Direct\+FormI}}, \mbox{\hyperlink{classIir_1_1DirectFormII}{Direct\+Form\+II}}, ... \\
\hline
\end{DoxyParams}

\doxysubsubsection{Member Function Documentation}
\mbox{\Hypertarget{structIir_1_1Butterworth_1_1HighShelf_a19a78cb96c9b2454ccb48745ed50500d}\label{structIir_1_1Butterworth_1_1HighShelf_a19a78cb96c9b2454ccb48745ed50500d}}
\index{Iir::Butterworth::HighShelf$<$ FilterOrder, StateType $>$@{Iir::Butterworth::HighShelf$<$ FilterOrder, StateType $>$}!setup@{setup}}
\index{setup@{setup}!Iir::Butterworth::HighShelf$<$ FilterOrder, StateType $>$@{Iir::Butterworth::HighShelf$<$ FilterOrder, StateType $>$}}
\doxyparagraph{\texorpdfstring{setup()}{setup()}\hspace{0.1cm}{\footnotesize\ttfamily [1/2]}}
{\footnotesize\ttfamily template$<$int Filter\+Order = 4, class State\+Type  = Direct\+Form\+II$>$ \\
void \mbox{\hyperlink{structIir_1_1Butterworth_1_1HighShelf}{Iir\+::\+Butterworth\+::\+High\+Shelf}}$<$ Filter\+Order, State\+Type $>$\+::setup (\begin{DoxyParamCaption}\item[{double}]{sample\+Rate,  }\item[{double}]{cutoff\+Frequency,  }\item[{double}]{gain\+Db }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}}

Calculates the coefficients with the filter order provided by the instantiation
\begin{DoxyParams}{Parameters}
{\em sample\+Rate} & Sampling rate \\
\hline
{\em cutoff\+Frequency} & Cutoff \\
\hline
{\em gain\+Db} & Gain in dB of the filter in the passband \\
\hline
\end{DoxyParams}
\mbox{\Hypertarget{structIir_1_1Butterworth_1_1HighShelf_aa7fecdca7646acf8962c5d0106fb8b3c}\label{structIir_1_1Butterworth_1_1HighShelf_aa7fecdca7646acf8962c5d0106fb8b3c}}
\index{Iir::Butterworth::HighShelf$<$ FilterOrder, StateType $>$@{Iir::Butterworth::HighShelf$<$ FilterOrder, StateType $>$}!setup@{setup}}
\index{setup@{setup}!Iir::Butterworth::HighShelf$<$ FilterOrder, StateType $>$@{Iir::Butterworth::HighShelf$<$ FilterOrder, StateType $>$}}
\doxyparagraph{\texorpdfstring{setup()}{setup()}\hspace{0.1cm}{\footnotesize\ttfamily [2/2]}}
{\footnotesize\ttfamily template$<$int Filter\+Order = 4, class State\+Type  = Direct\+Form\+II$>$ \\
void \mbox{\hyperlink{structIir_1_1Butterworth_1_1HighShelf}{Iir\+::\+Butterworth\+::\+High\+Shelf}}$<$ Filter\+Order, State\+Type $>$\+::setup (\begin{DoxyParamCaption}\item[{int}]{req\+Order,  }\item[{double}]{sample\+Rate,  }\item[{double}]{cutoff\+Frequency,  }\item[{double}]{gain\+Db }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}}

Calculates the coefficients
\begin{DoxyParams}{Parameters}
{\em req\+Order} & The actual order which can be less than the instantiated one \\
\hline
{\em sample\+Rate} & Sampling rate \\
\hline
{\em cutoff\+Frequency} & Cutoff \\
\hline
{\em gain\+Db} & Gain in dB of the filter in the passband \\
\hline
\end{DoxyParams}
\mbox{\Hypertarget{structIir_1_1Butterworth_1_1HighShelf_af63e4f43001ae2d9faf44ba6496db562}\label{structIir_1_1Butterworth_1_1HighShelf_af63e4f43001ae2d9faf44ba6496db562}}
\index{Iir::Butterworth::HighShelf$<$ FilterOrder, StateType $>$@{Iir::Butterworth::HighShelf$<$ FilterOrder, StateType $>$}!setupN@{setupN}}
\index{setupN@{setupN}!Iir::Butterworth::HighShelf$<$ FilterOrder, StateType $>$@{Iir::Butterworth::HighShelf$<$ FilterOrder, StateType $>$}}
\doxyparagraph{\texorpdfstring{setupN()}{setupN()}\hspace{0.1cm}{\footnotesize\ttfamily [1/2]}}
{\footnotesize\ttfamily template$<$int Filter\+Order = 4, class State\+Type  = Direct\+Form\+II$>$ \\
void \mbox{\hyperlink{structIir_1_1Butterworth_1_1HighShelf}{Iir\+::\+Butterworth\+::\+High\+Shelf}}$<$ Filter\+Order, State\+Type $>$\+::setupN (\begin{DoxyParamCaption}\item[{double}]{cutoff\+Frequency,  }\item[{double}]{gain\+Db }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}}

Calculates the coefficients with the filter order provided by the instantiation
\begin{DoxyParams}{Parameters}
{\em cutoff\+Frequency} & Normalised cutoff frequency (0..1/2) \\
\hline
{\em gain\+Db} & Gain in dB of the filter in the passband \\
\hline
\end{DoxyParams}
\mbox{\Hypertarget{structIir_1_1Butterworth_1_1HighShelf_a7df553be87ce22541c6ffa8af7508898}\label{structIir_1_1Butterworth_1_1HighShelf_a7df553be87ce22541c6ffa8af7508898}}
\index{Iir::Butterworth::HighShelf$<$ FilterOrder, StateType $>$@{Iir::Butterworth::HighShelf$<$ FilterOrder, StateType $>$}!setupN@{setupN}}
\index{setupN@{setupN}!Iir::Butterworth::HighShelf$<$ FilterOrder, StateType $>$@{Iir::Butterworth::HighShelf$<$ FilterOrder, StateType $>$}}
\doxyparagraph{\texorpdfstring{setupN()}{setupN()}\hspace{0.1cm}{\footnotesize\ttfamily [2/2]}}
{\footnotesize\ttfamily template$<$int Filter\+Order = 4, class State\+Type  = Direct\+Form\+II$>$ \\
void \mbox{\hyperlink{structIir_1_1Butterworth_1_1HighShelf}{Iir\+::\+Butterworth\+::\+High\+Shelf}}$<$ Filter\+Order, State\+Type $>$\+::setupN (\begin{DoxyParamCaption}\item[{int}]{req\+Order,  }\item[{double}]{cutoff\+Frequency,  }\item[{double}]{gain\+Db }\end{DoxyParamCaption})\hspace{0.3cm}{\ttfamily [inline]}}

Calculates the coefficients
\begin{DoxyParams}{Parameters}
{\em req\+Order} & The actual order which can be less than the instantiated one \\
\hline
{\em cutoff\+Frequency} & Normalised cutoff frequency (0..1/2) \\
\hline
{\em gain\+Db} & Gain in dB of the filter in the passband \\
\hline
\end{DoxyParams}

The documentation for this struct was generated from the following file\+:\begin{DoxyCompactItemize}
\item
iir/Butterworth.\+h\end{DoxyCompactItemize}


\section{Results}
\paragraph{Modeling Allele Frequency Trajectories in Small Populations.}
We first tested the goodness of fit of the discrete versus Brownian motion (a
continuous-state model) in modeling allele frequency trajectories, under
general E\&R
parameters.  For this purpose, we conducted $100$K simulations with
two time samples $\Tc=\{0,\tau\}$ where $\tau\in \{1,10,100\}$ is the
parameter controlling the density of sampling in time.  In addition,
we repeated simulations for different values of starting frequency
$\nu_0\in\{0.005,0.1\}$ (i.e., hard and soft sweep) and selection
strength $s\in\{0,0.1\}$ (i.e., neutral and selection). Then, given
initial frequency $\nu_0$, we computed the expected distribution of
the frequency of the next sample $\nu_\tau$ under two models to make a
comparison.  \ref{fig:markov}A-F shows that Brownian motion
(continuous model) is inadequate when $\nu_0$ is far from $0.5$, or
when sampling times are sparse ($\tau>1$). If the favored allele
arises from standing variation in a neutral population, it is unlikely
to have frequency close to $0.5$, and the starting frequencies are
usually much smaller (see \ref{fig:sfs}). Moreover, in typical \dmel
experiments for example, sampling is sparse. Often, the experiment is
designed so that $10\le\tau\le100$~\cite{kofler2013guide,
  orozco2012adaptation, zhou2011experimental,franssen2015patterns}.

% XXX Not sufficient to say 'in contrast to brownian motion, markov...
% Please check the rewrite of this part
In contrast to the Brownian motion approximation, discrete Markov
chain predictions (Eq.~\ref{eq:Qt}) are highly consistent with
empirical data for a wide range of simulation parameters
(\ref{fig:markov}A-M). Moreover, the discrete markov chain can be
modified to model the case when the the allele is under
selection.

\begin{figure*}
	\centering
	\includegraphics[width=\textwidth]{{markovDists}.pdf}
	\caption{{\bf Comparison of empirical distributions of allele
			frequencies (red) versus predictions from Brownian
			Motion (green), and Markov chain (blue).}\\
		Comparison of empirical and theoretical distributions under
		neutral evolution (panels A-F) and selection (panels G-M)
		with different starting frequencies $\nu_0\in\{0.005,0.1\}$
		and sampling times of $\Tc=\{0,\tau\}$, where $\tau \in
		\{1,10,100\}$ and $N=1000	$.  For each panel, the empirical
		distribution
		was computed over 100,000 simulations.  Brownian motion
		(Gaussian approximation) provides poor approximations when
		initial frequency is far from 0.5 (A) or sampling is sparse
		(B,C,E,F). In addition, Brownian motion can only provide
		approximations under neutral evolution. In contrast, Markov
		chain consistently provides a good approximation in all
		cases.}
	\label{fig:markov}
\end{figure*}

\paragraph{Detection Power.}
We compared the performance of \comale\ against other methods for
detecting selection. For each method we calculated detection power as
the percentage of true-positives identified with false-positive rate
$\le 0.05$. For each configuration (specified with values for
selection coefficient $s$, starting allele frequency $\nu_0$ and
coverage $\lambda$), power of each method is evaluated over $2000$
distinct simulations, half of which modeled neutral evolution and the
rest modeled positive selection.

We compared the power of \comale\ with Gaussian process
(GP)~\cite{Terhorst2015Multi}, FIT~\cite{feder2014Identifying}, and
CMH~\cite{agresti2011categorical} statistics.  FIT and GP convert read
counts to allele frequencies prior to computing the test statistic.
\comale\ shows the highest power in all cases and the power stays
relatively high even for low coverage (\ref{fig:power} and
\ref{tab:power}). In particular, the difference in performance of
\comale\ with other methods is pronounced when starting frequency is
low.  The advantage of \comale\ stems from the fact that favored
allele with low starting frequency might be missed by low coverage
sequencing. In this case, incorporating the signal from linked sites
becomes increasingly important. We note that methods using only two
time points, such as CMH, do relatively well for high selection values
and high coverage. However, the use of time-series data can increase
detection power in low coverage experiments or when starting frequency
is low. Moreover, time-series data provide means for estimating
selection parameters $s,h$ (see below). Finally, as \comale\ is robust
to change of coverage, our results (\ref{fig:power}B,C) suggest that
taking many samples with lower coverage is preferable to sparse
sampling with higher coverage. For comparison purposes, we also tested
\comale\ using the single locus statistic ($L=1$). For the most part,
\comale\ showed an improvement over other methods even with $L=1$, or
showed similar performance. The performance improved with higher $L$.

\begin{figure*}
	\centering
	\includegraphics[width=\textwidth]{power.pdf}
	\caption{ {\bf Power calculations for detection of selection.}\\
		Detection power for \comale ($\Hc$), Frequency Increment
		Test (FIT), Gaussian Process (GP), and CMH under hard (A-C)
		and soft sweep (D-F) scenarios. $\lambda$, $s$ denote the
		mean coverage and selection coefficient, respectively.
		Orange hexagons represent the performance of \comale\ when
		the maximum of the single-locus statistic is used to make a
		decision for the genomic region, while the red circle
		corresponds to the performance of \comale\ when single locus
		statistics are averaged over the region.  The $y$-axis
		measures power -- sensitivity with false positive rate FPR
		$\le 0.05$ -- for $2,000$ simulations with $N=1,000$,
		$L=50$Kbp. The horizontal line reflects the power of a
		random classifier.  In all simulations, 3 replicates are
		evolved and sampled at generations
		$\Tc=\{0,10,20,30,40,50\}$.}
	\label{fig:power}
\end{figure*}
\paragraph{Site-identification.}
In general, localizing the favored variant, using pool-seq data is a
nontrivial task due to extensive linkage
disequilibrium~\cite{tobler2014massive}.  To measure performance, we
sorted variants by their $H$ scores and computed rank of the favored
allele for each method. For each setting of $\nu_0$ and $s$, we
conducted $1000$ simulations and computed the rank of the favored
mutation in each simulation. The cumulative distribution of the rank
of the favored allele in 1000 simulation for each setting
(\ref{fig:rank}) shows that \comale\ outperforms other statistics.

An interesting observation is revisiting the contrast between
site-identification and
detection~\cite{long2013massive,tobler2014massive}.  When selection
strength is high, detection is easier (\ref{fig:power}A-F), but
site-identification is harder, due to the high LD between flanking
variants and the favored allele (\ref{fig:rank}A-F).  Moreover,
site-identification becomes more difficult whenever the initial
frequency of the favored allele is low, i.e., at the onset of
selection, LD between favored allele and its nearby variants is
high. For example, when coverage $\lambda=100$ and selection
coefficient $s=0.1$, the detection power is 75\% for hard sweep, but
100\% for soft sweep (\ref{fig:power}B-E). In contrast, the favored
site was ranked as the top in 14\% of hard sweep cases, compared to
and 95\% of soft sweep simulations.

\begin{figure*}
	\centering
	\includegraphics[trim=.2in 0 .2in 0,
	clip,width=\textwidth]{{rank100.0}.pdf}
	\caption{{\bf Ranking performance for 100$\times$ coverage.}\\
		Cumulative Distribution Function (CDF) of the distribution
		of the rank of the favored allele in 1000 simulations for
		\comale\ ($H$), Gaussian Process (GP), CMH, and Frequency
		Increment Test (FIT), for different values of selection
		coefficient $s$ and initial carrier frequency. Note that the
		individual variant \comale\ score ($H$) is used to rank
		variants.  The Area Under Curve (AUC) is computed as an overall
		quantitative measure to compare the performance of methods
		for each configuration. In all simulations, 3 replicates with $N=1000$
		are evolved and
		sampled at generations
		$\Tc=\{0,10,20,30,40,50\}$.}
	\label{fig:rank}
\end{figure*}

\paragraph{Estimating Parameters.}
\comale\ estimates effective population size $\hN$ and selection
parameters, $\hat{s}$ and $\hat{h}$, as a byproduct of the hypothesis
testing. We computed bias of selection fitness ($s-\hat{s}$) and
dominance ($h-\hat{h}$) for of \comale\ and GP for 1000 simulations in
each setting. The distribution of the error (bias) for 100$\times$
coverage is presented in \ref{fig:bias100} for different
configurations.  \ref{fig:bias30} and \ref{fig:biasinf} provide the
distribution of estimation errors for 30$\times$, and 300$\times$
coverage, respectively.  For hard sweep, \comale\ provides estimates
of $s$ with lower variance of bias (\ref{fig:bias100}A and
\ref{fig:biasNull}). In soft sweep, GP and \comale\ both provide unbiased
estimates of $s$ with low variance
(\ref{fig:bias100}B). \ref{fig:bias100}~C-D shows that \comale\
provides unbiased estimates of $h$ as well when $h\in\{0,0.5,1,2\}$
and $s=0.1$.  We also tested if \comale\ provide unbiased estimates of
$N$, by estimating population size on 1000 simulations when $N\in
\{200,600,1000\}$. As shown in~\ref{fig:estimateNMLE}-A
and~\ref{fig:estimateN}A-C, maximum
likelihood is attained at true value of the parameter.

\begin{figure*}
	\centering
	\includegraphics[width=0.7\textwidth]{{bias.100}.pdf}
	\caption{{\bf Distribution of bias for 100$\times$ coverage.}\\ The
		distribution of bias ($s-\hat{s}$) in estimating selection
		coefficient over 1000 simulations using Gaussian Process (GP) and
		\comale\ ($H$) is shown for a range of choices for the selection
		coefficient $s$ and starting carrier frequency $\nu_0$, when
		coverage $\lambda=100$ (Panels A,B). GP and \comale\ have similar
		variance in estimates of $s$ for soft sweep, while \comale\ provides
		lower variance in hard sweep. Also see \ref{tab:biasdist}. Panels C,D
		show the variance in the estimation of $h$.
		In all simulations, 3 replicates are evolved and sampled at generations
		$\Tc=\{0,10,20,30,40,50\}$.}
	\label{fig:bias100}
\end{figure*}

\paragraph{Running Time.}
As \comale\ does not compute exact likelihood of a region (i.e., does
not explicitly model linkage between sites), the complexity of
scanning a genome is linear in number of polymorphisms.  Calculating
score of each variant requires and $\Oc(TRN^3)$ computation
for $\Hc$. However, most of the operations
are can be vectorized for all replicates to make the effective running
time for each variant.  We
conducted $1000$ simulations and measured running times for computing site
statistics $H$, FIT, CMH and GP with different number of linked-loci.  Our
analysis reveals (\ref{fig:runTime}) that \comale\ is orders of
magnitude faster than GP, and comparable to FIT. While slower than CMH
on the time per variant, the actual running times are comparable after
vectorization and broadcasting over variants (see below).

These times can have a practical consequence. For instance, to run GP
in the single locus mode on the entire pool-seq data of the \dmel genome from a
small sample ($\approx$1.6M variant sites), it would take 1444 CPU-hours
($\approx$ 1 CPU-month). In contrast, after vectorizing and
broadcasting operations for all variants operations using
\texttt{numba} package, \comale\ took 75 minutes to perform an
scan, including precomputation, while the fastest method, CMH, took 17 minutes.

\begin{figure*}
	\centering
	\includegraphics[width=0.75\textwidth]{{runTime.pdf}}
	\caption{{\bf Running time.}\\ Box plots of running time per
		variant (CPU-secs.) of \comale ($\Hc$), CMH, FIT, and
		GP with single, 3, 5, 7, and 10 loci over 1000 simulations
		conducted on a workstation with Intel Core i7
		processor. The average running time for each method is shown
		on the x-axis.
		In all simulations, 3 replicates are evolved and sampled at generations
		$\Tc=\{0,10,20,30,40,50\}$.}
	\label{fig:runTime}
\end{figure*}

\subsection{Analysis of a \dmel Adaptation to Alternating
Temperatures}\label{sec:dmel}
We applied \comale\ to the
\datadm~\cite{orozco2012adaptation,franssen2015patterns}, where
3 replicate samples were chosen from a population of \dmel for 59
generations under alternating 12-hour cycles of  hot stressful (28$^{\circ}$C)
and non-stressful (18$^{\circ}$C) temperatures and sequenced.  In this dataset,
sequencing coverage is different across replicates and generations
(see S2 Fig of~\cite{Terhorst2015Multi}) which makes variant depths
highly heterogeneous (\ref{fig:depthHetero}).

We first filtered out heterochromatic, centromeric and telomeric
regions~\cite{fiston2010drosophila}, and those variants that have
collective coverage of more that 1500 in all 13 populations: three
replicates at the base population, two replicates at generation 15,
one replicate at generation 23, one replicate at generation 27, three
replicates at generation 37 and three replicates at generation
59. After filtering, we ended up with 1,605,714 variants.

Next, we estimated genome-wide population size $\hN=250$
(\ref{fig:estimateNMLE}-B and \ref{fig:estimateN}-E) which is consistent with
previous
studies~\cite{orozco2012adaptation,jonas2016estimating}. The
likelihood curves of \comale\ are sharper around the optimum compared
to that of Bollback et. al~\cite{bollback2008estimation}'s method (see
Supplementary Fig. 1 in~\cite{orozco2012adaptation}).  Also,
chromosomes 3L and 3R appear to have smaller population
size, $\hN=200,150$, respectively.
Others have
made similar observations on this data. In particular,
J\'{o}n\'{a}s~\emph{et al.}~\cite{jonas2016estimating} shown that the
chromosome-wise population
size varies even more when it is computed for each replicate
separately (see Table 1 in~\cite{jonas2016estimating}). For instance,
$\hN$ is 131 for chromosome 3R replicate 1, while it is 328 for chromosome X
replicate 2.

\begin{figure*}
	\centering
	\includegraphics[width=\textwidth]{estimateNMLE.pdf}
	\caption{{\bf Estimating population size.}  (A) Distribution
		of bias in estimating $N$, computed on 1000 neutral
		simulations for each $N\in\{200,600,1000\}$ when $W=10$Mbp and
		$r=2\times10^{-8}$. (B)
		Estimates
		of population size for \datadm. For each case, the
		distribution of estimator is computed by 100 bootstrap
		computations using 1000 variants each. The multiple modes
		are an artifact of grid search used to speed up
		computation. (C) Distribution of the population 	size
		estimates on the yeast dataset.  Despite large census
		population size ($10^6-10^7$~\cite{burke2014standing}), this
		dataset exhibits much smaller effective population size
		($\hN=2000$). }
	\label{fig:estimateNMLE}
\end{figure*}

While it would be ideal to compute \comale\ statistic for each
replicate and chromosome separately, computing empirical $p$-values
and significant regions become computationally intensive as empirical
null distribution of each replicate and each chromosome needs to be
computed.  Hence, we use a single genome-wide estimate $\hN=250$ in
all analyses, but we normalize statistic $\Hc^*$ separately for each
chromosome.

We use a heuristic calculation (See~\ref{sec:winSize}) to choose the
sliding window size $L$ as the distance where the LD between the
favored mutation and a site $L/2$bp away remains strong. For \dmel
parameters, we obtained $L=30$Kbp. We computed the normalized test
statistic $\Hc^*$ on sliding windows of size of 30Kbp and step size of
5Kbp over the genome (See~\ref{fig:man-dmel-region}-A).

Empirical null distribution of $\Hc^*$ was estimated by creating 100
whole genome simulations (400K statistic values) as described in
Section~\ref{sec:sims}. Then, $p$-value of the test statistic in each
region in the experimental data was calculated as the fraction of the
null statistic values that are greater than or equal to the test
statistic(see~\ref{fig:null-alt}).  After correcting for multiple
testing, we identified $5$ contiguous
intervals~(\ref{fig:man-dmel-region}) satisfying FDR$\le0.05$, and
covering $2,829$ polymorphic sites. We further performed single-locus
hypothesis testing on the $2,829$ sites to identify $174$ individual
variants with FDR $\le0.01$~(\ref{fig:man-dmel-region}-B).

The final set of 174 variants fall within 32 genes(\ref{tab:genes})
including many Serine inhibitory proteases (serpins), and other genes
involved in endocytosis. Recycling of synaptic vesicles is seen to be
blocked at high temperature in temperature sensitive Drosophila
mutants~\cite{kosaka1983reversible}. This is also supported by GO
enrichment analysis, where a single GO term `inhibition of
proteolysis' is found to enriched (corrected $p$-value:0.0041).  To
test for dominant selection, we computed $D$ statistic on simulated
neutral and experimental data, and computed $p$-values accordingly.
After correcting for multiple testing, 96 variants were discovered
with FDR$\le 0.01$~(\ref{fig:man-dmel-snp}).

\subsection{Analysis of Outcrossing Yeast Populations}
We also applied \comale\ to  $12$ replicate samples of
outcrossing yeast populations~\cite{burke2014standing}, where samples are
taken at
generations $\Tc=\{0,180,360,540\}$. We observed a significant
variation in the genome-wide site frequency spectrum of certain
populations over different time points for some
replicates~(\ref{fig:yeast-sfs}). The variation does not have an
easily identifiable cause. Therefore, we focused analysis on seven
replicates $r\in\{3,7,8,9,10,11,12\}$ with genome-wide site-frequency
spectrum over the time range~(\ref{fig:yeast-pca}).

We estimated population size to be $\hN=2000$ haplotypes
(\ref{fig:estimateNMLE}-C and \ref{fig:estimateN}-F), and computed
$\hs$, $\hh$ and $H$ statistic accordingly. To compute $p$-values, we
created 1M single-locus neutral simulations according to experimental
data's initial frequency and coverage. By setting FDR cutoff to
$0.05$, only 18 and 16 variants show significant signal for
directional and dominant selection,
respectively~(\ref{fig:man-dmel-snp}).  Selected variants for
directional selection are clustered in two regions, which match $2$ of
the $5$ regions (regions C and E in Fig. 2-a
in~\cite{burke2014standing}) identified by Burke~\emph{et al.} in
their preliminary analysis.

\begin{figure*}
	\centering
	\begin{tabular}{c}
		(A)\\
		\includegraphics[trim=0.4in 0.in 0.6in
		0in,clip,width=0.9\textwidth]{man-dmel-region.pdf}\\
		(B)\\
		\includegraphics[trim=0.3in 0.in 0.6in
		.0in,clip,width=0.9\textwidth]{{topVariants.dmel.dir}.pdf}
	\end{tabular}
	\caption{{\bf Scan of \comale\ statistic on \datadm.}
		(A)         Manhattan plot of scan for $\Hc^*$ statistic using sliding
		window of
		size $L=3000$ over the
		genome.  The dashed line represents cutoff for genome-wide
		FDR$\le0.05$, and identifies 5 contiguous intervals, I1-I5,
		which are shaded in blue. (B) Trajectories of the selected
		variants within
		intervals I1-I5.}
	\label{fig:man-dmel-region}
\end{figure*}

\begin{figure*}
	\centering
	\begin{tabular}{cc}
		\includegraphics[trim=0.4in 0.in 0.6in
		0.0in,clip,width=0.65\textwidth]{man-yeast-snp.pdf}&
		\raisebox{0.2in}{
			\includegraphics[trim=0in 0.in 0in
			0.0in,clip,width=0.35\textwidth]{{topVariants.yeast}.pdf}}
	\end{tabular}
	\caption{{\bf Single locus analysis of the yeast outcrossing
			populations.}\\ Manhattan plot
		of scan single locus \comale\ statistic ($L=1$) for testing directional
		selection (A) and dominant
		selection
		(C).
		The dashed line represents cutoff for  genome-wide FDR$\le0.05$.
		Trajectories of the selected variants are depicted in panels (B) and
		(D).}
	\label{fig:man-yeast-snp}
\end{figure*}


\mainsection{User Defined Local Functions}
\label{sec:Local}
As you write complex applications you will soon see the
need to execute local operations on each player which are
rather complex. For example this might be formatting data,
or performing some local arithmetic which does not need
to be done securely.
Prior to v1.5 there was two ways of doing this:
\begin{enumerate}
\item Write the local function in MAMBA or SCALE byte-codes
directly. This is often both a pain from a programming point
of view, and also produced highly inefficient code.
\item Use the calling application to execute the local
operations, and then use the I/O class to interact
between the two. This requires people to have calling
applications, which any deployed application will have),
but which a quick experimental setup is unlikely to
bother with.
But it also requires expensive interaction between the
SCALE engine and the external application via the I/O
class.
\end{enumerate}
Having implemented the user defined circuits for Garbling
we decided to also, in a similar manner, add a third method
of implementing local functions; namely via user-defined
C++-code.
To see this in operation we suggest looking at the directory
\verb|src/Local/|, and looking at the files there. Here
we implement some basic linear algebra routines.
Look at those files whilst reading this explanation.

\subsection{Defining Local Functions in C++}
Every local function is one which involves no interaction
between the parties.
It can thus be {\em any} function on clear data, and
only a {\em linear} function on private data.
A local function is defined using the C++ signature
\begin{lstlisting}
    void apply_Function(int instr);
\end{lstlisting}
Where the variable \verb|instr| is the instruction number; which is akin to the
earlier circuit number for garbled circuits.
We reserve all numbers less than 65536 for use by the developers, leaving
you to define numbers greater than 65536.
Once again, if you have a good function which might be useful to others
please let us know.

The local function is registered with an instruction number in the
system by adding the function pointer to the \verb|functions| map
in the file \verb|src/Local/Local_Functions.cpp|.
Must like user defined Garbled Circuits were added into the
system earlier.

Each local function obtains it arguments by popping any required
data off the stacks, the functions outputs are then placed on the
stacks in a similar manner.
See the \verb|BLAS.cpp| example linear algebra routines for
some examples.

\subsection{Defining Local Functions in the MAMBA/byte-code Language}
On the byte-code side of system we have one instruction
\verb|LF| which takes a single argument, namely the
number of the local function being called.

\subsection{Floating Point Examples}
These functions (in most cases) load in values from the
\verb|regint| stack, treat them as floating point values,
process the operation, and then push them back to the \verb|regint|
stack.
The first ones mirror the equivalent functions in the
\verb|GC| routines, and thus have the same numbers.
\begin{center}
\begin{tabular}{c|l}
Number & Function \\
\hline
120 & IEEE floating point (double) addition \\
121 & IEEE floating point (double) multiplication \\
122 & IEEE floating point (double) division \\
123 & IEEE floating point (double) equality \\
124 & IEEE floating point (double) to sregint \\
125 & sregint to IEEE floating point (double) \\
126 & IEEE floating point (double) sqrt \\
127 & IEEE floating point (double) lt \\
128 & IEEE floating point (double) floor \\
129 & IEEE floating point (double) ceil \\
\hline
200 & IEEE floating point (double) acos \\
201 & IEEE floating point (double) asin \\
202 & IEEE floating point (double) atan \\
203 & IEEE floating point (double) cos \\
204 & IEEE floating point (double) cosh \\
205 & IEEE floating point (double) sin \\
206 & IEEE floating point (double) sinh \\
207 & IEEE floating point (double) tanh \\
208 & IEEE floating point (double) exp \\
209 & IEEE floating point (double) log \\
210 & IEEE floating point (double) log10 \\
211 & IEEE floating point (double) fabs \\
\hline
\end{tabular}
\end{center}

\subsection{Floating Point Conversion}
We also have local routines that convert between IEEE format
and \verb|cfix| and \verb|cfloat| format.
In the following table we mark the types of the arguments
and outputs with `i' for \verb|regint| and `p' for \verb|cint|.
The left most argument is at the bottom of the stack
in each case.
\begin{center}
\begin{tabular}{c|l|l}
Number & Function & Args \\
\hline
	500 & IEEE $\rightarrow$ cfix & (x: i, k: i, f: i) $\rightarrow$ (a: p) \\
	501 & cfix$\rightarrow$IEEE & (x: p, k: i, f: i) $\rightarrow$ (a: i) \\
	502 & IEEE$\rightarrow$cfloat & (x: i, vlen: i, plen: i) $\rightarrow$ (v: p, p: p, z: p, s: p, err: p) \\
	503 & cfloat$\rightarrow$IEEE & (v: p, p: p, z: p, s: p, err: p) $\rightarrow$ (x: i) \\
\hline
\end{tabular}
\end{center}

\subsection{BLAS Examples}
In our Basic Linear Algebra System (BLAS) we provide currently four
routines
\begin{center}
\begin{tabular}{c|l}
Instruction Number & Function \\
\hline
0 & cint n-by-k matrix A by cint k-by-m matrix B \\
1 & sint n-by-k matrix A by cint k-by-m matrix B \\
2 & cint n-by-k matrix A by sint k-by-m matrix B \\
3 & Row Reduction of a n-by-m cint matrix A \\
\end{tabular}
\end{center}
In these examples the dimensions are passed via
pushing to the \verb|regint| stack, with data
being passed by pushing to the \verb|cint| (resp.
\verb|sint|) stack.
The matrices are packed using a standard row-wise configuration.
In the following code example (given in \verb|Programs/Local_test/|)
we illustrate this with the matrices
\[
  A = \left( \begin{array}{ccc}
  1 & 2 & 3 \\
  4 & 5 & 6 \end{array} \right) \quad \quad
  B = \left( \begin{array}{cc}
  7 & 8 \\
  9 & 10 \\
  11 & 12
  \end{array} \right).
\]
\begin{lstlisting}
def push_Cint_matrix(A,n,m):
  regint.push(regint(n))
  regint.push(regint(m))
  for i in range(n):
    for j in range(m):
       cint.push(A[i][j])

def push_Sint_matrix(A,n,m):
  regint.push(regint(n))
  regint.push(regint(m))
  for i in range(n):
    for j in range(m):
       sint.push(A[i][j])

def pop_Cint_matrix(A,n,m):
  mm=regint.pop()
  nn=regint.pop()
  if_then(nn!=n or m!=mm)
  print_ln("Something wrong")
  print_ln("%s %s",nn,mm)
  end_if()
  for i in range(n-1,-1,-1):
    for j in range(m-1,-1,-1):
       A[i][j]=cint.pop()

def pop_Sint_matrix(A,n,m):
  mm=regint.pop()
  nn=regint.pop()
  if_then(nn!=n or m!=mm)
  print_ln("Something wrong")
  print_ln("%s %s",nn,mm)
  end_if()
  for i in range(n-1,-1,-1):
    for j in range(m-1,-1,-1):
       A[i][j]=sint.pop()

n=2
l=3
m=2

# Mult the two matrices
#  A = [1,2,3;4,5,6]
#  B = [7,8;9,10;11,12]
# which should give us
#  C = [58,64; 139, 154]

Cp_A=cint.Matrix(n,l)
Cp_B=cint.Matrix(l,m)
Cp_out=cint.Matrix(n,m)
CpGE_out=cint.Matrix(n,l)
Sp_A=sint.Matrix(n,l)
Sp_B=sint.Matrix(l,m)
Sp_out=sint.Matrix(n,m)

cnt=1
for i in range(n):
  for j in range(l):
     Cp_A[i][j]=cint(cnt)
     Sp_A[i][j]=sint(cnt)
     cnt=cnt+1

for i in range(l):
  for j in range(m):
     Cp_B[i][j]=cint(cnt)
     Sp_B[i][j]=sint(cnt)
     cnt=cnt+1

push_Cint_matrix(Cp_A,n,l)
push_Cint_matrix(Cp_B,l,m)
LF(0)
pop_Cint_matrix(Cp_out,n,m)

print_ln("Final CC Product is...")
for i in range(n):
  for j in range(m):
    print_str('%s ', Cp_out[i][j])
  print_ln('')

push_Sint_matrix(Sp_A,n,l)
push_Cint_matrix(Cp_B,l,m)
LF(1)
pop_Sint_matrix(Sp_out,n,m)

print_ln("Final SC Product is...")
for i in range(n):
  for j in range(m):
    print_str('%s ', Sp_out[i][j].reveal())
  print_ln('')

push_Cint_matrix(Cp_A,n,l)
push_Sint_matrix(Sp_B,l,m)
LF(2)
pop_Sint_matrix(Sp_out,n,m)

print_ln("Final CS Product is...")
for i in range(n):
  for j in range(m):
    print_str('%s ', Sp_out[i][j].reveal())
  print_ln('')

push_Cint_matrix(Cp_A,n,l)
LF(3)
pop_Cint_matrix(CpGE_out,n,l)

print_ln("Final Gauss Elim on A is...")
for i in range(n):
  for j in range(l):
    print_str('%s ', CpGE_out[i][j])
  print_ln('')
\end{lstlisting}


\chapter{Using PEA in end user mode}
\label{ch:pea_user_mode}
When set to end user mode, the PEA component of Ginan will process each station separately. This mode will allow the estimation of parameters available to users with single receivers.
\begin{itemize}
	\item Receiver position
	\item Receiver clock offset
	\item Tropospheric delay at receiver location
	\item Ionospheric delay at the receiver location (not yet available)
	\item Carrier phase ambiguities
\end{itemize}
In order to use the PEA in end-user mode, the \textit{ processing\_options : process\_modes : user} parameter needs to be set to \textit{true}.
The results of PEA run in end user mode are printed in the trace files.
Trace file outputs can be activated by setting the \textit{ output\_files : output\_trace} parameter to \textit{true}.
The most commonly used outputs from the PEA used in end-user mode are expected to be: the receiver position, receiver velocity, receiver clocks and tropospheric delays.

\textbf{Receiver position}  results are preceded by the "\$POS" label and thus, in Linux, can be extracted using the command:
 \begin{lstlisting}
$ grep "$POS" <path_to_trace_file>
\end{lstlisting}
the output line for the for receiver position will have 10 comma separated fields with the following format:
\begin{lstlisting}
$POS,2166,278015.000,6,-4052053.0060,4212836.8682,-2545105.0796,0.0245227,0.0231919,0.0163678
\end{lstlisting}
the fields represent, from left to right:
\begin{enumerate}
	\item  "\$POS" label
	\item  GPS week
	\item  GPS TOW in seconds
	\item  Solution type (6 for float PPP, 1 for ambiguity fixed PPP)
	\item  Receiver ECEF X position in meters
	\item  Receiver ECEF Y position in meters
	\item  Receiver ECEF Z position in meters
	\item  Standard deviation of ECEF X positions in meters
	\item  Standard deviation of ECEF X positions in meters
	\item  Standard deviation of ECEF X positions in meters
\end{enumerate}

\textbf{Receiver clock} offset results are preceded by the "\$CLK" label and thus, in Linux, can be extracted using the command:
 \begin{lstlisting}
$ grep "$CLK" <path_to_trace_file>
\end{lstlisting}
the output line for the for receiver position will have 13 comma separated fields with the following format:
\begin{lstlisting}
$CLK,2166,278015.000,6,14,3.1902,0.0000,1.1924,0.0000,0.0860,0.0000,0.0953,0.0000
\end{lstlisting}
the fields represent, from left to right:
\begin{enumerate}
	\item  "\$CLK" label
	\item  GPS week
	\item  GPS TOW in seconds
	\item  Solution type (6 for float PPP, 1 for ambiguity fixed PPP)
	\item  Number of satellites used in the solution
	\item  Receiver clock offset for with respect to GPS clock, in nanoseconds
	\item  Receiver clock offset for with respect to GLONASS clock, in nanoseconds
	\item  Receiver clock offset for with respect to Galileo clock, in nanoseconds
	\item  Receiver clock offset for with respect to Beidou clock, in nanoseconds
	\item  Standard deviation of clock offset wrt. GPS, in nanoseconds
	\item  Standard deviation of clock offset wrt. GLONASS, in nanoseconds
	\item  Standard deviation of clock offset wrt. Galileo, in nanoseconds
	\item  Standard deviation of clock offset wrt. Beidou, in nanoseconds
\end{enumerate}
If clock offsets for a particular constellation are not available both the offset and its variance will be set to 0.

\textbf{Tropospheric delays} at the receiver position are preceded by the "\$TROP" label and thus, in Linux, can be extracted using the command:
 \begin{lstlisting}
$ grep "$TROP" <path_to_trace_file>
\end{lstlisting}
the tropospheric delay solutions will be represented to either a single line, with the "\$TROP" or three lines, as follows:
\begin{lstlisting}
$TROP,2166,278015.000,6,14,2.294950,0.0030977
$TROP_N,2166,278015.000,6,14,-0.174797,0.0181385
$TROP_E,2166,278015.000,6,14,-0.223868,0.0250276
\end{lstlisting}
each of the troposphere output line will contain 7 comma separated field, of which the first five are:
\begin{enumerate}
	\item  Label, "\$TROP", "\$TROP\_N" or "\$TROP\_E"
	\item  GPS week
	\item  GPS TOW in seconds
	\item  Solution type (6 for float PPP, 1 for ambiguity fixed PPP)
	\item  Number of satellites used in the solution
\end{enumerate}
The line starting with "\$TROP" contain the Zenith Tropospheric Delay (ZTD) and its standards deviation, both in meters, as their last two fields.  The line starting with "\$TROP\_N" contains the tropospheric delay gradient in north-south direction, and  the line starting with "\$TROP\_E" contains the tropospheric delay gradient in east-west direction.

Configuration files for specific examples have been added to the \textit{examples} folder in the repository. Examples corresponding to end user processing are explained bellow. In order to

\subsection{Dual frequency PPP with floating ambiguities}
As the end-user processing mode cannot calculate satellite states, the satellite position and clock offset needs to be provided externally.
The PEA supports SP3 formatted satellite position inputs, specified in \textit{input\_files : sp3files}, and RINEX clock files, \textit{input\_files : clkiles}, as satellite clock inputs.
ANTEX files, with antenna information for both stations and satellites should be provided in  \textit{input\_files : atxfiles}
SINEX files, with station antennas should be provided in  \textit{input\_files : snxfiles}
RINEX 3.XX navigation files, with broadcast clocks should be provided in  \textit{input\_files : navfiles}
BLQ formatted ocean tide  loading parameters for each station should be provided in \textit{input\_files : blqfiles} if available to correct for OTL, otherwise \textit{processing\_options : tide\_otl} should be set to \textit{false}.
RINEX 3.XX observation files for the network stations should be provided in \textit{station\_data : rnxfiles} (* can be used as a wildcard).\\

The configuration files named \textit{examples/ex11\_pea\_pp\_user\_gps.yaml} and \textit{examples/ex12\_pea\_pp\_user\_gnss.yaml} set the PEA to calculate a post-process end user solution for a static receiver.
The constellations to be used in processing can be specified in the \textit{processing\_options : process\_sys} field.
The tracking of a moving receiver can be done by setting the \textit{default\_filter\_parameters : stations : pos : proc\_noise} parameter to the maximum expected velocity.
Receiver velocity can also be estimated by setting  \textit{default\_filter\_parameters : stations : pos\_rate : estimate} to \textit{true}.\\

Tropospheric delays are estimated as a combination of hydrostatic and wet components, each component is in turn estimated as the products of the zenith delay and a mapping function.
 If \textit{default\_filter\_parameters : stations : trop : estimate} is set to \textit{true}, the PEA estimates the zenith wet delay.
 If \textit{default\_filter\_parameters : stations : trop\_grad : estimate} is set to \textit{true}, the PEA also estimates azimutal components of tropospheric mapping functions.
The hydrostatic zenith delays and elevation dependent component of mapping functions are calculated based on pre-defined models.
Available models, whic can be selected using the \textit{processing\_options : troposphere : model} parameter, are the GPT2 and VMF3 models.
If using the GPT2 model the path to the necessary grid file needs to be specified in  \textit{processing\_options : troposphere : gpt2grid}
If using the VMF3 model, the tropospheric parameters corresonding to the observatin times need to be provided in a directory specified by \textit{processing\_options : troposphere : vmf3dir}, and the orography file for atmospheric circulation models need to be specified in \textit{processing\_options : troposphere : orography}.\\

\subsection{Single frequency PPP}
It is possible to perform end user PPP processing using single frequency data (although at reduced accuracy) by providing extenal Ionospheric delay data.
The configuration files named \textit{examples/ex13\_pea\_pp\_user\_gps\_sf.yaml} set an example to process single frequency observations.
The PEA currently uses IONEX formatted VTEC maps as Ionosphere delay data.
The path to the IONEX file needs to be specified  in  \textit{input\_files : ionfiles}.
In order for the PEA to use the VTEC maps, the \textit{processing\_options : ionosphere : corr\_mode} parameter should to be set to \textit{total\_electron\_content}.
If provided separatelly, files containing the satellite DCB (either RINEX DCB or bias SINEX) should be specified in \textit{input\_files :dcbfiles} \\

\subsection{Dual frequency PPP with ambiguity resolution}
The PEA (in both network and user processing modes) can be specified to perform ambiguity resolution in an attempt to improve accuracy and convergence times.
In aside from the requirements for floating PPP ambiguities, information on satellite hardware biases needs to be provided order to allow correct ambiguity resolution in end user PEA processing.
For post-process, the PEA use bias SINEX formatted files as input channels for satellite hardware biases.
The bias SINEX file can be specified in \textit{input\_files :bsxfiles}.

The ambiguity resolution process is controlled by the \textit{ambiguity\_resolution\_options} field.
Currently ambiguity resolution is only supported for GPS and Galileo satellited.
Ambiguity resolution for GPS satellites can be activated by setting the \textit{GPS\_amb\_resol} parameter to \textit{true}.
Ambiguity resolution for Galileo satellites can be activated by setting the \textit{GAL\_amb\_resol} parameter to \textit{true}.
In addition the ambiguity resolution algorithm needs to be specified for both the wide-lane ambiguity (\textit{WL\_mode}) and narrow-lane ambiguities (\textit{NL\_mode}.
For best results, \textit{round} or \textit{iter\_rnd} are recommended for Wide-lane ambiguities and  \textit{lambda\_alt} or \textit{lambda\_bie} is recommended for narrow-lane ambiguities.\\

\subsection{Real-time PPP}
The PEA can also be used to process GNSS data in real-time.
Real-time processing will make use of RTCM formatted streams for receiver observables and satellite data.
Currently the PEA can only get real-time data by connecting to an NTRIP caster.
An example of such a caster, can be accessed by registering at \href{https://www.auscors.ga.gov.au/}.
The host name, user name and password corresponding to the NTRIP can shold be specified under \textit{station\_data : stream\_root} using the format \textit{http(s)://user:password@hostname/}.
The mountpoint corresponding to station observables need to be listed under \textit{station\_data : obs\_streams}.
Ephemeris streams (broadcast ephemeris and SSR corrections) shold be listed under \textit{station\_data : nav\_streams}.
The PEA support MSM4, MSM5, MSM6 and MSM7 messages for observations, and orbit and clock messages, code bias messages and phase bias messages for GPS and Galileo.\\

Real-time outputs are not yet defined for PEA, the processed receiver solution are printed in real time on the TRACE files.\\