\section{Flattening}
\label{sec:flattening}
\index{stack!flattening|(}

Let us design a function~\fun{flat/1}\index{flat@\fun{flat/1}} such
that the call \(\fun{flat}(s)\), where \(s\)~is a stack, is rewritten
into a stack containing only the non\hyp{}stack items found in~\(s\),
in the same order. If \(s\)~contains no stack, then \(\fun{flat}(s)
\equiv s\). Let us review some
examples\index{stack!flattening!example} to grasp the concept:
\begin{equation*}
\fun{flat}(\el) \twoheadrightarrow \el; \quad
\fun{flat}([\el,[\el]]) \twoheadrightarrow \el;\quad
\fun{flat}([\el,[1,[2,\el],3],\el]) \twoheadrightarrow [1,2,3].
\end{equation*}
First, let us focus on designing the left\hyp{}hand sides of the
rules, in order to ensure that our definition is \emph{complete} (all
valid inputs are matched). A stack is either empty or not and, in the
latter case, the specific issue at hand appears clearly: we need to
distinguish the items which are stacks themselves from those which are
not. This is very simply achieved by ordering the patterns so that
\(\el\) and \(\cons{x}{s}\) \emph{as items} appear
first:\index{flat@\fun{flat/1}|(}
\begin{equation*}
\begin{array}{r@{\;}l@{\;}l}
\fun{flat}(\el)                   & \xrightarrow{\smash{\psi}}   & \fbcode{CCCCCCC}\,;\\
\fun{flat}(\cons{\el}{t})         & \xrightarrow{\smash{\omega}} & \fbcode{CCCCCCC}\,;\\
\fun{flat}(\cons{\cons{x}{s}}{t}) & \xrightarrow{\smash{\gamma}} & \fbcode{CCCCCCC}\,;\\
\fun{flat}(\cons{y}{t})           & \xrightarrow{\smash{\delta}} & \fbcode{CCCCCCC}\,.
\end{array}
\end{equation*}
We know that \(y\)~in the last line is not a stack, otherwise the
penultimate or antepenultimate pattern would have matched. Almost all
the right\hyp{}hand sides are easy to guess now:
\begin{equation*}
\begin{array}{r@{\;}l@{\;}l}
\fun{flat}(\el)                   & \xrightarrow{\smash{\psi}}   & \el;\\
\fun{flat}(\cons{\el}{t})         & \xrightarrow{\smash{\omega}} & \fun{flat}(t);\\
\fun{flat}(\cons{\cons{x}{s}}{t}) & \xrightarrow{\smash{\gamma}} & \fbcode{CCCCCCC}\,;\\
\fun{flat}(\cons{y}{t})           & \xrightarrow{\smash{\delta}} & \cons{y}{\fun{flat}(t)}.
\end{array}
\end{equation*}
\index{flat@\fun{flat/1}|)}The design of the remaining right\hyp{}hand
side can be guided by two slightly different principles. If we look
back at the definitions of~\fun{rev\(_0\)/1}
\index{rev0@\fun{rev\(_0\)/1}|(}
and~\fun{rev/1}\index{rev@\fun{rev/1}} in section~\ref{sec:reversal},
we see that the former was designed with the result in mind, as if the
arrows would reach a value, which is then decomposed in terms of the
variables of the corresponding left\hyp{}hand side:
\begin{equation*}
\begin{array}{r@{\;}l@{\;}l}
\fun{rev}_0(\el) & \rightarrow & \el;\\
\fun{rev}_0(\cons{x}{s}) & \rightarrow &
\fun{cat}(\fun{rev}_0(s),[x]).
\end{array}
\end{equation*}
\index{rev0@\fun{rev\(_0\)/1}|)}By contrast,
\fun{rev/1}\index{rev@\fun{rev/1}} relies on another function,
\fun{rcat/2}\index{rcat@\fun{rcat/2}}, to accumulate partial results,
as if each arrow covered a short distance, only contributing minimally
to the final value:
\begin{equation*}
\begin{array}{r@{\;}l@{\;}l}
\fun{rev}(s) & \smashedrightarrow{\epsilon} & \fun{rcat}(s,\el).\\
\fun{rcat}(\el,t) & \smashedrightarrow{\zeta} & t;\\
\fun{rcat}(\cons{x}{s},t) & \smashedrightarrow{\eta} &
\fun{rcat}(s,\cons{x}{t}).
\end{array}
\end{equation*}
The first approach might be called \emph{big\hyp{}step
  design}\index{design!big-step $\sim$}, and the other
\emph{small\hyp{}step design}\index{design!small-step $\sim$}. Another
vantage point is to see that the former uses the context of the
recursive call to build the value, whilst the latter relies
exclusively on an argument (the accumulator\index{functional
  language!accumulator}) and is in tail form\index{functional
  language!tail form}. For example, in section~\ref{sec:skipping}, we
may find that the definition of \fun{sfst/2}\index{sfst@\fun{sfst/2}}
follows a big\hyp{}step design, while
\fun{sfst\(_0\)/2}\index{sfst@\fun{sfst/2}} illustrates a
small\hyp{}step design.

\paragraph{Big-step design}
\index{design!big-step $\sim$}
\index{divide and conquer}
\label{big-step}

Abstractly, a big\hyp{}step design means that the right\hyp{}hand
sides are made up of recursive calls on substructures, for instance,
in the case of rule~\(\gamma\), the substructures of
\(\cons{\cons{x}{s}}{t}\) are~\(x\), \(s\), \(t\) and
\(\cons{x}{s}\). By thinking how to make up the value by means of
\(\fun{flat}(\cons{x}{s})\)\index{flat@\fun{flat/1}} and
\(\fun{flat}(t)\), we obtain a new version,
\fun{flat\(_0\)/1}\index{flat0@\fun{flat$_0$/1}}, in
\fig~\vref{fig:flat0}.
\begin{figure}
\begin{equation*}
\boxed{%
\begin{array}{r@{\;}l@{\;}l}
\fun{flat}_0(\el)                   & \xrightarrow{\smash{\psi}}
                                    & \el;\\
\fun{flat}_0(\cons{\el}{t})         & \xrightarrow{\smash{\omega}}
                                    & \fun{flat}_0(t);\\
\fun{flat}_0(\cons{\cons{x}{s}}{t}) & \xrightarrow{\smash{\gamma}}
        & \fun{cat}(\fun{flat}_0(\cons{x}{s}),\fun{flat}_0(t));\\
\fun{flat}_0(\cons{y}{t})           & \xrightarrow{\smash{\delta}}
                                    & \cons{y}{\fun{flat}_0(t)}.
\end{array}}
\end{equation*}
\caption{Flattening a stack with \fun{flat\(_0\)/1}
\label{fig:flat0}\index{stack!flattening!definition}}
\end{figure}

Let us consider an example in \fig~\vref{fig:flat0_ex}, where the call
to be rewritten next is underlined in case of ambiguity.
\begin{figure}
\begin{equation*}
\boxed{%
\begin{array}{r@{\;}l@{\;}l}
\fun{flat}_0([\el,[[1],2],3])
& \xrightarrow{\smash{\omega}}
& \fun{flat}_0([[[1],2],3])\\
& \xrightarrow{\smash{\gamma}}
& \fun{cat}(\underline{\fun{flat}_0([[1],2])},\fun{flat}_0([3]))\\
& \xrightarrow{\smash{\gamma}}
& \fun{cat}(\fun{cat}(\underline{\fun{flat}_0([1])},\fun{flat}_0([2])),\fun{flat}_0([3]))\\
& \xrightarrow{\smash{\delta}}
& \fun{cat}(\fun{cat}([1|\underline{\fun{flat}_0(\el)}],\fun{flat}_0([2])),\fun{flat}_0([3]))\\
& \xrightarrow{\smash{\psi}}
& \fun{cat}(\fun{cat}([1],\underline{\fun{flat}_0([2])}),\fun{flat}_0([3]))\\
& \xrightarrow{\smash{\delta}}
& \fun{cat}(\fun{cat}([1],[2|\underline{\fun{flat}_0(\el)}]),\fun{flat}_0([3]))\\
& \xrightarrow{\smash{\psi}}
& \fun{cat}(\fun{cat}([1],[2]),\underline{\fun{flat}_0([3])})\\
& \xrightarrow{\smash{\delta}}
& \fun{cat}(\fun{cat}([1],[2]),[3|\underline{\fun{flat}_0(\el)}])\\
& \xrightarrow{\smash{\psi}}
& \fun{cat}(\fun{cat}([1],[2]),[3])\\
& \twoheadrightarrow & [1,2,3].
\end{array}
}
\end{equation*}
\caption{\(\fun{flat}_0([\el,[[1],2],3]) \twoheadrightarrow [1,2,3]\)
\label{fig:flat0_ex}\index{stack!flattening!example}}
\end{figure}
Note that the call\hyp{}by\hyp{}value\index{functional
  language!call-by-value} strategy (section~\ref{sec:functional}) does
not specify the order of evaluation of the arguments of a function
call: in our example, we delayed the evaluation of
\(\fun{cat}([1],[2])\) \index{cat@\fun{cat/2}|(} after that of the
calls to \fun{flat\(_0\)/1}\index{flat0@\fun{flat$_0$/1}}. When
deriving complicated recurrences or traces, we may try instead
counting the number of times each rule is used in any
evaluation. Calling \fun{flat\(_0\)/1}\index{flat0@\fun{flat$_0$/1}}
results in
\begin{itemize*}

  \item using rule~\(\omega\) once for each empty stack originally in
    the input;

  \item using rule~\(\psi\) once when the end of the input is reached
    \emph{and} once for each empty stack \(t\) in rule~\(\gamma\);

  \item using rule~\(\delta\) once for each item which is not a stack;

  \item using rule~\(\gamma\) once for each non\hyp{}empty embedded
    stack;

  \item calling \fun{cat/2}\index{cat@\fun{cat/2}|)} once for each
    non\hyp{}empty embedded stack.

\end{itemize*}
We now know the parameters which the cost depends upon:
\begin{enumerate*}

  \item the length of\index{flat0@\fun{flat$_0$/1}}
    \(\fun{flat}_0(s)\), noted~\(n\);

  \item the number of non\hyp{}empty stacks embedded in the input,
    say~\(\Gamma\);

  \item the number of embedded empty stacks, denoted by~\(\Omega\).

\end{enumerate*}
The dependence upon the size of the output, \(n\), is an instance of
\emph{output\hyp{}dependent cost}\index{cost!output-dependent
  $\sim$}. We can reformulate the above analysis in the following
terms: rule~\(\psi\) is used \(1 + \Gamma\)~times, rule~\(\omega\) is
used \(\Omega\)~times, rule~\(\gamma\) is used \(\Gamma\)~times,
rule~\(\delta\) is used \(n\)~times. So the cost due to the rules of
\fun{flat\(_0\)/1}\index{flat0@\fun{flat$_0$/1}} alone is \(1 + n +
\Omega + 2\Gamma\). For instance, in the case of
\(\fun{flat}_0([\el,[[1],2],3])\), we correctly find \(1 + 3 + 1 + 2
\cdot 2 = 9 = \len{\omega\gamma^2(\delta\psi)^3}\).

As far as the costs of the calls to \fun{cat/2} are concerned, their
associativity\index{cat@\fun{cat/2}} was proved on
page~\pageref{proof:assoc_cat} and equation~\eqref{ineq:cat_assoc}
\vpageref{ineq:cat_assoc} suggests that there are configurations of
the input to \fun{flat\(_0\)/1}\index{flat0@\fun{flat$_0$/1}} that
lead to greater costs, when the parameters \(n\), \(\Omega\)
and~\(\Gamma\) are fixed. A similar pattern of calls to
\fun{cat/2}\index{cat@\fun{cat/2}} with a quadratic cost is generated
from the definition of
\fun{rev\(_0\)/1}\index{rev0@\fun{rev\(_0\)/1}}, as seen in
\fig~\vref{fig:rev0_321}, after the first application of
rule~\(\alpha\). The right\hyp{}hand side of rule~\(\gamma\) is
\(\fun{cat}(\fun{flat}_0(\cons{x}{s}),\fun{flat}_0(t))\)
\index{flat0@\fun{flat$_0$/1}} and it implies that the arguments of
\fun{cat/2}\index{cat@\fun{cat/2}} may be empty stacks.

Given \(\Gamma\) \fun{cat}\hyp{}nodes, \(n\)~non\hyp{}stack nodes
(\(x_1\), \dots, \(x_n\)), what are the abstract syntax trees with
minimum and maximum costs? We found that the minimum cost for
\fun{cat/2}\index{cat@\fun{cat/2}} is achieved when all the
\fun{cat}\hyp{}nodes make up the rightmost
\emph{branch}\index{tree!branch} of the abstract syntax tree. (A
branch is a series of nodes such that one is the parent of the next,
from the root to a leaf.)
\begin{itemize}

  \item If \(\Omega \geqslant \Gamma\), the minimum configuration is
  shown in \fig~\ref{fig:cat_min1}
\begin{figure}[b]
\centering
\subfloat[If \(\Omega \geqslant \Gamma\), the minimum is \(\Gamma\).
\label{fig:cat_min1}]{\includegraphics[bb=66 660 191 722]{cat_min1}}
\quad
\subfloat[If \(\Omega < \Gamma\), the minimum is \(2\Gamma-\Omega\).
\label{fig:cat_min2}]{\includegraphics[bb=70 643 230 721]{cat_min2}}
\caption{Minimum costs for the catenations in \fun{flat\(_0\)/1}
\label{fig:cat_min}}
\end{figure}
  (at least one empty stack must be placed in any non\hyp{}empty stack
  whose flattening results in an empty stack).

\item Otherwise, the abstract syntax tree of minimum cost is found in
  \fig~\ref{fig:cat_min2}, where all the available empty stacks
  (\(\Omega\)) are used for the bottommost \fun{cat}\hyp{}nodes. We
  draw that the minimum cost\index{stack!flattening!minimum cost}
  is\index{flat0@$\B{\fun{flat}_0}{n}$}
  \(\B{\fun{flat}_0}{n,\Omega,\Gamma} = 1 + n + \Omega + 3\Gamma +
  \min\{\Omega,\Gamma\}\).

\end{itemize}

The maximum cost\index{stack!flattening!maximum cost} in
\fig~\ref{fig:cat_max} occurs for the symmetrical tree of
\fig~\ref{fig:cat_min1}. We
have\index{flat0@$\W{\fun{flat}_0}{n,\Omega,\Gamma}$}
\(\W{\fun{flat}_0}{n,\Omega,\Gamma} = \Omega + (n+3)(\Gamma+1) - 2\).
\begin{figure}[t]
\centering
\subfloat[Maximum cost \((n+1)\Gamma\)\label{fig:cat_max}]{
\includegraphics[bb=71 660 188 721]{cat_max}}
\qquad
\subfloat[$\protect\fun{flat}(\cons{\cons{x}{s}}{t})$\label{fig:lift1}]%
{\includegraphics[bb=55 661 122 721]{flat_embed}}
\qquad
\subfloat[$\protect\fun{flat}(\cons{x,s}{t})$\label{fig:lift2}]%
{\includegraphics[bb=57 661 120 721]{flat_lift}}
\caption{Maximum cost and right rotations}
\end{figure}

% Wrapping figure better declared before a paragraph
%
\begin{wrapfigure}[7]{r}[0pt]{0pt}
% [7] vertical lines
% {r} mandatory right placement
\centering
\includegraphics[bb=71 658 220 710]{flat}%[... 721]
\caption{Defining \fun{flat/1}\label{fig:flat}
\index{stack!flattening!definition}}
\end{wrapfigure}

\paragraph{Small-step design}
\index{design!small-step $\sim$}

An alternative method for flattening of a stack consists in
lifting~\(x\) in rule~\(\gamma\) one level up amongst the embedded
stacks, thus approaching little by little a flat stack. In terms of
the abstract syntax trees, this operation is a \emph{right
  rotation}\index{binary tree!rotation} of the tree associated with
the argument, as shown in \figs~\vrefrange{fig:lift1}{fig:lift2},
where the new function is called
\fun{flat/1}\index{flat@\fun{flat/1}|(} and defined in
\fig~\vref{fig:flat}. Let us run the previous example of
\fig~\vref{fig:flat0_ex} again in \fig~\vref{fig:flat_ex} with
\fun{flat/1}. The difference in cost with
\fun{flat\(_0\)/1}\index{flat0@\fun{flat$_0$/1}} resides in the number
of times rule~\(\gamma\) is used: once for each item in all the
embedded stacks. Hence the
cost\index{stack!flattening!cost}\label{cost:flat} is \(1 + n + \Omega
+ \Gamma + L\), where \(L\)~is the sum of the lengths of all the
embedded stacks.

\paragraph{Comparison}

Consider the following costs:
\begin{equation*}
\begin{array}{@{}r@{\;}c@{\;}r@{\;}c@{\;}r@{\;}c@{\;}l@{}}
\Call{\fun{flat}([[[[[1,2]]]]])}
  &=& 12 &<& 23 &=& \Call{\fun{flat\(_0\)}([[[[[1,2]]]]])};\\
\Call{\fun{flat}([\el,[[1],2],3])}
  &=& 10 &<& 14 &=& \Call{\fun{flat\(_0\)}([\el,[[1],2],3])};\\
\Call{\fun{flat}([\el,[[1,[2]]],3])}
  &=& 12 &<& 19 &=& \Call{\fun{flat\(_0\)}([\el,[[1,[2]]],3])};\\
\Call{\fun{flat}([[\el,\el,\el]])}
  &=&  8 &>&  7 &=& \Call{\fun{flat\(_0\)}([[\el,\el,\el]])}.
\end{array}
\end{equation*}
\begin{figure}
\begin{equation*}
\boxed{%
\begin{array}{r@{\;}l@{\;}l}
\fun{flat}([\el,[[1],2],3])
& \xrightarrow{\smash{\omega}} & \fun{flat}([[[1],2],3])\\
& \xrightarrow{\smash{\gamma}} & \fun{flat}([[1],[2],3])\\
& \xrightarrow{\smash{\gamma}} & \fun{flat}([1,\el,[2],3])\\
& \xrightarrow{\smash{\delta}} & [1|\fun{flat}([\el,[2],3])\\
& \xrightarrow{\smash{\omega}} & [1|\fun{flat}([[2],3])]\\
& \xrightarrow{\smash{\gamma}} & [1|\fun{flat}([2,\el,3])]\\
& \xrightarrow{\smash{\delta}} & [1,2|\fun{flat}([\el,3])]\\
& \xrightarrow{\smash{\omega}} & [1,2|\fun{flat}([3])]\\
& \xrightarrow{\smash{\delta}} & [1,2,3|\fun{flat}(\el)]\\
& \xrightarrow{\smash{\psi}}   & [1,2,3].
\end{array}}
\end{equation*}
\caption{\(\fun{flat}([\el,[[1],2],3]) \twoheadrightarrow [1,2,3]\)
\label{fig:flat_ex}
\index{stack!flattening!example}}
\end{figure}
Simple algebra shows that\index{flat@$\C{\fun{flat}}{n,\Omega,\Gamma}$}
\index{flat0@$\B{\fun{flat}_0}{n,\Omega,\Gamma}$}
\begin{equation*}
\C{\fun{flat}}{n,\Omega,\Gamma}
\leqslant
\B{\fun{flat}_0}{n,\Omega,\Gamma}
\Leftrightarrow
\begin{cases}
  L \leqslant 3\Gamma - \Omega,
                         & \text{if \(\Omega \geqslant \Gamma\)};\\
  L \leqslant 2\Gamma,   & \text{otherwise.}
\end{cases}
\end{equation*}
\index{flat@\fun{flat/1}|)} This criterion is impractical to check and
it is inconclusive if the inequalities on the right\hyp{}hand side
fail. Things worsen if we settle for \(L \leqslant 2\Gamma \Rightarrow
\smash[t]{\C{\fun{flat}}{n,\Omega,\Gamma}} \leqslant
\smash[t]{\C{\fun{flat}_0}{n,\Omega,\Gamma}}\), because this condition
is too strong when \(\Omega\)~is large. Let us examine what happens at
the other extreme, when \(\Omega = 0\). Considering an example like
\([0,[1,[2]],3,[4,5,[6,7],8],9]\), it may occur to us that if there
are no empty stacks, the length of each stack is lower than or equal
to the number of non\hyp{}stack items in it and its embeddings (it is
equal if there is no further embedded stack). Therefore, summing up
all these inequalities, the following inequality ensues:
\begin{equation}
  \Omega = 0 \Rightarrow C - L \geqslant 0, \label{eq:CL}
\end{equation}
where \(C\)~is the cost of rewriting the calls
to~\fun{cat/2}\index{cat@\fun{cat/2}}
in~\fun{flat\(_0\)/1}\index{flat0@\fun{flat$_0$/1}}. Because
\(\C{\smash{\fun{flat}_0}}{n,\Omega,\Gamma} = (1 + n + \Omega +
\Gamma) + (C + \Gamma)\) and \(\C{\fun{flat}}{n,\Omega,\Gamma} = (1 +
n + \Omega + \Gamma) + L\),
\begin{equation*}
  \C{\smash{\fun{flat}_0}}{n,\Omega,\Gamma} -
  \C{\fun{flat}}{n,\Omega,\Gamma} =
  (C - L) + \Gamma.
\end{equation*}
From equation~\eqref{eq:CL}, we deduce that, in the absence of empty
stacks, we have the inequality
\(\C{\smash{\fun{flat}_0}}{n,\Omega,\Gamma} -
\C{\fun{flat}}{n,\Omega,\Gamma} \geqslant L\), that is,
\fun{flat/1}\index{flat@\fun{flat/1}} is faster.

\mypar{Termination}
\label{flattening:termination}
\index{stack!flattening!termination|(}

As we have seen with the simplified Ackermann's function
(section~\ref{par:ackermann}, \vpageref{par:ackermann}), termination
follows from finding a well\hyp{}founded order \((\succ)\) on the
recursive calls, which is entailed by the rewrite relation
\((\rightarrow)\), that is, \(x \rightarrow y \Rightarrow x \succ
y\). One well\hyp{}founded order for stacks is the \emph{immediate
  subterm order}, satisfying \(\cons{x}{s} \succ s\) and \(\cons{x}{s}
\succ x\). Since big\hyp{}step design uses recursive calls to subterms
(section~\ref{par:well-founded}, \vpageref{par:well-founded}), it
eases termination proofs based on such an ordering.

For instance, let us recall the definition of
\fun{flat\(_0\)/1}\index{flat0@\fun{flat$_0$/1}|(} in
\fig~\ref{fig:flat0} on page~\pageref{fig:flat0}. Since
\fun{cat/2}\index{cat@\fun{cat/2}} is independent of
\fun{flat\(_0\)/1}, we prove its termination in isolation by using the
proper subterm order on its first argument. Assuming now that
\fun{cat/2} terminates, let us prove the termination of
\fun{flat\(_0\)/1}. Because the recursive calls of \fun{flat\(_0\)/1}
contain only (stack) constructors, we can try to order their arguments
\citep{ArtsGiesl_1996}. Again, the same order works:
\begin{itemize*}

  \item \(\cons{y}{t} \succ t\) by rule~\(\delta\) and rule~\(\omega\)
    when \(y=\el\),

  \item \(\cons{\cons{x}{s}}{t} \succ t\) and

  \item \(\cons{\cons{x}{s}}{t} \succ \cons{x}{s}\) by
    rule~\(\gamma\).

\end{itemize*}
Termination ensues.\hfill\(\Box\)

Let us further recall the definition of
\fun{flat/1}\index{flat@\fun{flat/1}} in \fig~\ref{fig:flat} and
prove its termination. Here, the order we used for \fun{flat\(_0\)/1}
fails:
\begin{equation*}
  \cons{\cons{x}{s}}{t} \nsucc \cons{x,s}{t} =
  \cons{x}{\cons{s}{t}}.
\end{equation*}
We could try the more general \emph{proper subterm
  order}\index{induction!proper subterm order}, that is, the strict
inclusion of a term into another, but, despite \(\cons{x}{s} \succ
x\), we have \(t \nsucc \cons{s}{t}\). One way out is to define a
\emph{measure}\index{termination!measure} on the stacks
\citep{Giesl_1995a}.\index{flat0@\fun{flat$_0$/1}|)}

A measure \(\measure{\cdot}\) is a map from terms to a
well\hyp{}ordered set (\(A,\succ\)), which is \emph{monotone} with
respect to rewriting:
\begin{equation*}
  x \rightarrow y \Rightarrow \measure{x} \succ \measure{y}.
\end{equation*}
Actually, we will only consider \emph{dependency pairs}
\citep{ArtsGiesl_2000}\index{termination!dependency pair}, that is,
pairs of calls whose first component is the left\hyp{}hand side of a
rule and the second components are the calls in the righ\hyp{}hand
side of same rule. This is easier than working with \(x\)~and~\(y\) in
\(x \rightarrow y\), as only subterms of~\(y\) are considered. The
pairs are\index{flat@\fun{flat/1}}:
\begin{itemize*}

  \item \((\fun{flat}(\cons{\el}{t}),
    \fun{flat}(t))_\omega\),

  \item \((\fun{flat}(\cons{\cons{x}{s}}{t}),
    \fun{flat}(\cons{x,s}{t}))_\gamma\) and

  \item \((\fun{flat}(\cons{y}{t}), \fun{flat}(t))_\delta\), with \(y
    \not\in S\).
\end{itemize*}
We can actually drop the function names, as all the pairs involve
\fun{flat/1}\index{flat@\fun{flat/1}}. A common class of measures are
monotone embeddings into (\(\mathbb{N},>\)), so let us seek a measure
satisfying
\begin{itemize*}

  \item \(\measure{\cons{\cons{x}{s}}{t}} > \measure{\cons{x,s}{t}}\);

  \item \(\measure{\cons{y}{t}} > \measure{t}\), if \(y \not\in S\) or
    \(y=\el\).

\end{itemize*}
For instance, let us set the following \emph{polynomial
  measure}\index{termination!polynomial measure}:
\begin{itemize*}

  \item \(\measure{\cons{x}{s}} := 1 + 2\cdot\measure{x} +
    \measure{s}\);

  \item \(\measure{y} := 0\), if \(y \not\in S\) or \(y=\el\).

\end{itemize*}
We have, for each stack,
\begin{itemize*}

  \item \(\measure{\cons{\cons{x}{s}}{t}} = 3 + 4\cdot\measure{x} +
    2\cdot\measure{s} + \measure{t}\),

  \item \(\measure{\cons{x,s}{t}} = 2 + 2\cdot\measure{x} +
    2\cdot\measure{s} + \measure{t}\).

\end{itemize*}
Therefore \(\measure{\cons{\cons{x}{s}}{t}} = \measure{\cons{x,s}{t}}
+ 1 + 2\cdot\measure{x}\). Because \(\measure{x} \in \mathbb{N}\),
for all~\(x\), we have \(\measure{\cons{\cons{x}{s}}{t}} >
\measure{\cons{x,s}{t}}\). The second inequality yields faster:
\(\measure{\cons{y}{t}} = 1 + \measure{t} > \measure{t}\). This
entails the termination of
\fun{flat/1}\index{flat@\fun{flat/1}}.\index{stack!flattening!termination|)}\hfill\(\Box\)

\cite{Giesl_1997} tackled the termination of mutually recursive
functions. Functional programs, as special cases of
term\hyp{}rewriting systems, have been considered by
\cite{Giesl_1995b} and \cite{GieslWaltherBrauburger_1998}.

% Wrapping figure better declared before a paragraph
%
\begin{wrapfigure}[6]{r}[0pt]{0pt}
% [6] vertical lines
% {r} mandatory right placement
\centering
\includegraphics[bb=71 644 227 708]{flat1}% Originally [... 721]
\caption{Variant flattening\label{fig:flat1}
\index{stack!flattening!definition}}
\end{wrapfigure}
\paragraph{Exercises}

\begin{enumerate*}

  \item Define \fun{gamma/1}, \fun{lambda/1} and \fun{omega/1}, which
    compute \(\Gamma\), \(L\) and~\(\Omega\), respectively.

  \item Compare the costs of \fun{flat/1}\index{flat@\fun{flat/1}} and
    \fun{flat\(_1\)/1} \index{flat1@\fun{flat$_1$/1}} defined in
    \fig~\ref{fig:flat1} (see~(\(\leadsto\))).

\end{enumerate*}
\index{stack!flattening|)}


% Master File: ps10.tex
\input ../6001mac

\newcommand{\Code}[1]{\mbox{\tt #1}}

\begin{document}

\psetheader{Sample Problem Set}{Compilation}
\begin{center}
{\bf Register Machines and Compilation}
\end{center}

\medskip

Register machines provide a means of customizing code for particular
processes.  In principle, customization leads to more efficient code,
since one can avoid the overhead that comes from a compiler's obligation
to handle more general computations\footnote{For example, the compiler in Chapter
5 generates code in which arguments of procedures are maintained as a list
in the {\tt argl} register.  On the other hand, a register machine
customized for a procedure of, say, three arguments might usefully keep
the arguments in three separate registers.}.
In this problem set you will handcraft two simple machines and compare
them to the compiler in Chapter 5 of the notes.

The register machines you define should use only the following few
primitives:
\beginlisp
+ - * / inc dec = < > zero?  not true false
cons car cdr pair? null? list eq? symbol? write-line
\endlisp
Even though code generated by the compilers uses more complex primitives
such as
\beginlisp
lookup-variable-value extend-environment \ldots,
\endlisp
your hand-crafted code should turn out to run more efficiently.

Remember that register machine instructions are only of the
following types:
\beginlisp
test branch assign goto save restore perform
\endlisp
In this problem set, you should not need to use {\tt perform}.
Remember also that the only values that can be assigned to registers
or tested in branches are constants, fetches from registers, or
primitive operations applied to fetches from registers.  No nested
operations are permitted\footnote{For example,
(assign val (op inc) ((op *) (reg a) (reg b)))
is {\em not} permitted, since a call to {\tt *} is nested inside a
call to {\tt inc}.}.

\medskip
Here are the definitions of two Scheme procedures for deleting all
occurrences of an element, {\tt x}, from a list, {\tt l}:
\beginlisp
(define (delq1 x l)
  (cond ((null? l) '())
        ((eq? x (car l)) (delq1 x (cdr l)))
        (else (cons (car l) (delq1 x (cdr l))))))
\endlisp

\medskip
\beginlisp
(define (delq2 x l)
  (define (delete-reverse maybe-xs no-xs)
    (cond ((null? maybe-xs) no-xs)
          ((eq? x (car maybe-xs)) (delete-reverse (cdr maybe-xs) no-xs))
          (else (delete-reverse (cdr maybe-xs) (cons (car maybe-xs) no-xs)))))
  (delete-reverse (delete-reverse l '()) '()))
\endlisp

\paragraph{PreLab exercise 1A:}
For each of these procedures, say what order of growth in time (total
machine operations) and space (maximum stack depth) you expect them to use.

\paragraph{PreLab exercise 1B:}
Implement both of these procedures as register machines.  You should show
the controllers for all the machines, but you need show the data paths for
only one of them.

\section{To do in lab}

In lab, you will use the register machine simulator to test the register
machines you designed in exercise 1B.  To use the simulator, load the code
for problem set 10 and type in your machine definitions:

\beginlisp
(define my-machine
  (make-machine
   '(x l val \ldots)
   standard-primitives          ; + - * / inc, etc.
   '((test \ldots)
     \vdots
     )))
\endlisp

You'll find it convenient to define test procedures that load an input
into a machine, run the machine, print some statistics, and return the
result computed by the machine.  For example:

\beginlisp
(define (test-machine x l)
  (set-register-contents! my-machine 'x x)
  (set-register-contents! my-machine 'l l)
  (my-machine 'initialize-stack)
  (my-machine 'initialize-ops-counter)
  (start my-machine)
  (my-machine 'print-stack-statistics)
  (my-machine 'print-ops)
  (get-register-contents my-machine 'val))
\endlisp

In addition to routines that gather statistics for stack usage and
total number of operations, there are some procedures to help you
debug your machines.  {\tt trace-reg-on} will show all
assignments to a specified machine register as they occur. Evaluating:
\beginlisp
(trace-reg-on my-machine 'l)
\endlisp
before running your test procedure will show you all the changes to the
{\tt l} register. To see even more stuff, try:

\beginlisp
(trace-on my-machine)
\endlisp

which will print each machine instruction as it is executed.  To get rid
of these traces, use {\tt trace-reg-off} and {\tt trace-off}.

\paragraph{Lab exercise 2A:}
Debug your machines, run them on some representative inputs, and make a
table that records the total number of machine operations, total number of
stack pushes, and maximum stack depth as a function of the length of the
list from which an element is being deleted.

\paragraph{PostLab exercise 2B:}
Try to derive formulas for the total number of machine operations, total
number of pushes, and maximum stack depth used by your machines, as
functions of the length of the list.  In most cases, the functions will
turn out to be polynomials in the list length, in which case you should be
able to exhibit exact formulas, not just orders of growth.

\subsubsection{Running the Compiler}

There are two ways to run the compiler.  First, you may simply compile an
expression and obtain the list of machine instructions as a result, so
that you can study it.  For instance,

\beginlisp
(define test-expression '(define (f x y) (* (+ x y) (- x y))))

(define result (compile test-expression 'val 'return))

(pp result)
\endlisp

A way to look just at the produced code even more easily is:

\beginlisp
(compile-and-display test-expression)
\endlisp
which does exactly the same call to {\tt compile} as above.

The second way to run the compiler is to apply the procedure {\tt
compile-and-go} to the expression.  This compiles the expression and
executes it in the environment of the explicit control evaluator machine
{\tt eceval}.  When evaluation is complete, you are left in the
read-eval-print loop talking to the explicit control evaluator.  Then you
can experiment with the compiled expression by evaluating further
expressions.

\subsubsection{Running the Evaluator}

The evaluator for this problem set is the explicit control evaluator of
section 5.4.  For your convenience, we have extended it to handle {\tt
cond} and {\tt let}.

To evaluate an expression in the {\tt eceval} read-eval-print loop,
type the expression after the prompt, followed by {\tt ctrl-X ctrl-E}.
After each evaluation, the simulator will print the number of stack
and machine operations required to execute the code.\footnote{These
counts may include a few extra operations needed to run the driver
loop itself.  This is a small constant overhead that you can ignore
when you collect statistics.}

Here is an example:

\beginlisp
(compile-and-go
 '(define (fact n) (if (= n 0) 1 (* n (fact (- n 1)))))))
(total-pushes = 0 maximum-depth = 0)
(machine-ops = 12)
;;; EC-Eval value:  (the-unspecified-value)
\endlisp

\beginlisp
;;; EC-Eval input: (fact 4)          <== you type this and ctrl-X ctrl-E
(total-pushes = 31 maximum-depth = 14)
(machine-ops = 278)
;;; EC-Eval value: 24
\endlisp

\beginlisp
;;; EC-Eval input: (fact (fact 3))   <== you type this
(total-pushes = 68 maximum-depth = 20)
(machine-ops = 594)
;;; EC-Eval value: 720
\endlisp

\beginlisp
;;; EC-Eval input: fact
(total-pushes = 0 maximum-depth = 0)
(machine-ops = 13)
;;; EC-Eval value: <compiled-procedure>
\endlisp

\beginlisp
;;; EC-Eval input:
(define (fact n) (if (= n 0) 1 (* n (fact (- n 1))))) ;<== fact gets redefined
(total-pushes = 3 maximum-depth = 3)
(machine-ops = 45)
;;; EC-Eval value: (the-unspecified-value)
\endlisp

\beginlisp
;;; EC-Eval input: fact
(total-pushes = 0 maximum-depth = 0)
(machine-ops = 13)
;;; EC-Eval value:
;;;  (compound-procedure (n)
;;;    ((if (= n 0) 1 (* n (fact (- n 1))))) <procedure-env>)
\endlisp

\beginlisp
;;; EC-Eval input:
(fact 4)                ;<== redefined fact gets interpreted -- slower!
(total-pushes = 144 maximum-depth = 20)
(machine-ops = 1572)
;;; EC-Eval value: 24
\endlisp

To exit back to regular Scheme type {\tt ctrl-C ctrl-C}.  To reenter the
evaluator with the previous global environment, you may do another {\tt
compile-and-go}, or you may simply evaluate {\tt (eval-loop)} in Scheme.
To start the evaluator with a reinitialized global environment, evaluate
{\tt start-eceval}.

\paragraph{Lab exercise 3A:}
Compile and run the (Scheme) definitions of the {\tt delq1} and {\tt
delq2} procedures, and make tables to record statistics.

\paragraph{Lab exercise 3B:}
Now redefine them within the {\tt eceval} read-eval-print loop and record
corresponding statistics for the interpreted definitions.

\paragraph{PostLab exercise 3C:}
Derive formulas for the total number of machine operations, total number
of pushes, and maximum stack depth required, as functions of the length of
the list, for the compiled and interpreted delete procedures.

\bigskip

The file {\tt naivecom.scm} contains the simple code generator
described in lecture which omits the stack optimizations carried out
in the Notes.  Because its procedures satisfy a simplified
``contract'' slightly different from that in the Notes, the naive
compiler is not compatible with the evaluator.  We display its code
using {\tt naive-compile-and-display}, and run naive code using {\tt
naive-compile-and-go}.  For example: \beginlisp (define (fibexp n)
  `(begin
     (define (fib m)
       (if (< m 2)
           m
           (+ (fib (- m 1)) (fib (- m 2)))))
     (fib ,n)))
\endlisp

\beginlisp
(naive-compile-and-go (fibexp 8))
(total-pushes = 1469 maximum-depth = 27)
(machine-ops = 6544)
;value of expression: 21
;Value: \#[useless-value]
\endlisp

Compare this to:
\beginlisp
(compile-and-go (fibexp 8))
(total-pushes = 332 maximum-depth = 23)
(machine-ops = 2772 )
;;; EC-Eval value: 21
\endlisp

So in this case, the optimized code executes about 40\% as many
instructions and uses 85\% of the stack space as the code generated by
the naive compiler.

\paragraph{Lab exercise 4:}  Repeat exercise 3 for the naively compiled
delete procedures.

\paragraph{Post Lab exercise 5:} We'll consider the time used for a
computation to be the total number of machine operations, and the space
used to be the maximum stack depth.  For each of your list-deletion
procedures, determine the limiting ratio, as the list length becomes
large, of the time and space requirements for your hand-coded machines,
versus the time and space requirements for the compiled, naive-compiled,
and interpreted code.

\paragraph{Lab exercise 6A:} Make listings of the code generated by the
compiler from the Notes for the definitions of {\tt delq1} and {\tt
delq2}.

\paragraph{PostLab exercise 6B:}
Compare the listings with your hand-coded versions to see why the
compiler's code is less efficient than yours.  Suggest one improvement to
the compiler that could lead it to do a better job.  Write one or two
clear paragraphs indicating how you might go about implementing your
improvement.  You needn't actually carry out the the implementation, but
your description should be reasonably precise.  For example, you should
say what new information the compiler should keep track of, what new data
structures may be required to maintain this information, and how the
information should be used in generating the new, improved code.

\end{document}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                 %
%  GEANT manual in LaTeX form                              %
%                                                                 %
%  Michel Goossens (for translation into LaTeX)                   %
%  Version 1.00                                                   %
%  Last Mod. Jan 24 1991  1300   MG + IB                          %
%                                                                 %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Origin{L. Urb\'{a}n}
\Version{Geant 3.16}\Routid{PHYS340}
\Submitted{28.05.86} \Revised{16.12.93}
\Makehead{Total cross-section and energy loss for bremsstrahlung
by e-e+}

\section{Subroutines}
\Shubr{GBRELA}{}
\Rind{GBRELA} fills the tables for the energy loss of electrons,
positrons and muons due to
bremsstrahlung at initialisation time for different materials.
The energy
binning is set within the array \texttt{ELOW} (common \FCind{/CGMULO/}) in the
routine \Rind{GPHYSI}. In the tables, the dE/dx due to bremsstrahlung
is summed with that due to the ionisation. For energy loss
of electrons and positrons, \Rind{GBRELA} calls the function \Rind{GBRELE}.
Following pointers are used:
\begin{DLtt}{MMMMMMMMMMMMMMMMM}
\item[JMA = LQ(JMATE-I)] pointer to the I$^{th}$ material;
\item[JEL1 = LQ(JMA-1)]  pointer to $dE/dx$ for $\Pem$;
\item[JEL1+NEK1]           pointer to $dE/dx$ for $\Pep$.
\end{DLtt}
\Rind{GBRELA} is called at initialisation time by \Rind{GPHYSI}.
\Sfunc{GBRELE}{VALUE = GBRELE(ZZ,T,BCUT)}
\Rind{GBRELE} calculates the energy loss due to bremsstrahlung
of an electron with kinetic energy {\tt T} in material
with atomic number {\tt ZZ}.
It is called by \Rind{GBRELA} and for energies below the cut
{\tt BCUT} it adds the contribution of bremsstrahlung to.
Above this cut, the bremsstrahlung process is simulated
explicitly (see {\tt [PHYS341]}) and tabulation of these continuous losses
is not needed. \Rind{GBRELE} is called by \Rind{GBRELA}.
\Sfunc{GBFLOS}{VALUE = GBFLOS(T,C)}
\Rind{GBFLOS} calculates a weight factor for the positron continuous
bremsstrahlung energy loss. {\tt T} is the kinetic energy in GeV of the
positron and C is the energy cut for bremsstrahlung ({\tt BCUTE}). The
value is the ratio of the energy loss due to bremsstrahlung of the
positron to that of the electron so that:
$<${\it positron loss}$>$ = \Rind{GBFLOS} $\times$ $<${\it electron loss}$>$.
\Rind{GBFLOS} is called by \Rind{GBRELA}.
\Shubr{GBRSGA}{}
\Rind{GBRSGA} calculates the total cross-section for bremsstrahlung
in all materials. It tabulates the mean free path, $\lambda =
\frac{1}{\Sigma}$ (in cm) as a function of medium and energy. The energy
binning is set within the array {\tt ELOW} (common \FCind{/CGMULO/}) in the
routine \Rind{GPHYSI}. The following pointers are used:
\begin{DLtt}{MMMMMMMMMMMMMMMMMMN}
\item[JMA = LQ(JMATE-I)]pointer to the I$^{th}$ material
\item[JBREM = LQ(JMA-9)]pointer to bremsstrahlung cross-sections
\item[JBREM            ]pointer for  $\Pem$
\item[JBREM+NEK1       ]pointer for  $\Pep$
\item[JBREM+2*NEK1     ]pointer for $\mu^+/\mu^-$
\end{DLtt}
\Rind{GBRSGA} is called at initialisation time by \Rind{GPHYSI}.
\Sfunc{GBRSGE}{VALUE = GBRSGE(ZZ,T,BCUT)}
\Rind{GBRSGE} calculates the total cross-section of
bremsstrahlung of an electron with kinetic energy {\tt T}
in material with atomic number {\tt ZZ}.
It is called by \Rind{GBRSGA}. For kinetic energies
which are below the cut {\tt BCUT} or
for which bremsstrahlung process is not simulated
explicitly (see {\tt [PHYS341]}) it returns 0.
\Sfunc{GBFSIG}{VALUE = GBFSIG(T,C)}
\Rind{GBFSIG} calculates a
weight factor for the positron discrete (hard) bremsstrahlung cross section.
{\tt T} is the kinetic energy in GeV of the
positron and C is the energy cut for bremsstrahlung ({\tt BCUTE}). The
value returned is the ratio of the positron bremsstrahlung cross-section
to that of the electron so that:
<{\it positron cross-section}> = \Rind{GBFSIG} $\times$ <{\it electron
cross-section}>.  \Rind{GBFSIG} is called by \Rind{GBRSGA}.
\section{Method}
Let's call $d\sigma(Z,T,k)/dk$ the differential cross-section for
production of a photon of energy $k$ by an electron of kinetic energy
$T$ in the field of an atom of charge $Z$, and
$k_c$ the energy cut-off below which the soft photons are treated
as continuous energy loss ({\tt BCUTE} in the program).
Then the mean value of the energy lost by the electron due
to soft photons is
\begin{equation}
  E_{Loss}^{brem} (Z,T,k_c ) =
\int_{0}^{k_ c}k\frac{d \sigma (Z,T,k)}{dk}dk
\end{equation}
whereas the total cross-section for the emission of
a photon of energy larger than $k_c$ is
\begin{equation}
 \sigma_{brem} (Z,T,k_c ) = \int_{k_c}^{T}\frac{d \sigma (Z,T,k)}{dk} dk
\end{equation}
Many theories of the bremsstrahlung process exist, each with its own
limitations and regions of applicability. Perhaps the best synthesis
of these theories can be found in the paper of S.M. Seltzer and M.J.
Berger \cite{bib-SEL1}. The authors give a tabulation of the
bremsstrahlung cross-section $d\sigma/dk$ differential in the photon
energy $k$, for electrons with kinetic energies $T$ from 1 keV to 10
GeV. For electron energies above 10 GeV the screened Bethe-Heitler
differential cross-section can be used
\latexhtml{\cite{bib-EGS3,bib-NELS}}{\cite{bib-EGS3}, \cite{bib-NELS}}
together with the Midgal
corrections~\latexhtml{\cite{bib-MES1,bib-MIGD}}%
                      {\cite{bib-MES1}, \cite{bib-MIGD}}.
The first of the two Migdal corrections is
important for very high electron energies only ($T \geq$ 1 TeV) and
has the effect of reducing the cross-section.  The second Migdal
correction is effective even at ``ordinary'' energies (100 MeV -- 1
GeV) and it decreases the differential cross-section at photon
energies below a certain fraction of the incident electron energy
($d\sigma/dk$ decreases significantly if $ k/T \leq 10^{-4}$.)

\subsection{Parameterisation of energy loss and total cross-section}
Using the tabulated cross-section values of Seltzer and Berger together
with the Migdal corrected Bethe-Heitler formula we have computed
$\sigma(Z,T,k_c ) $
and we have used these computed values as ``data points''
in the fitting procedure.
Calculating the ``low energy'' ($T\leq 10$ GeV) data we have applied the
second Midgal correction to the results of Seltzer and Berger.
We have chosen the parameterisations:
\begin{equation}
\label{eq:phys340-1}
\sigma (Z,T,k_c ) =\frac{Z(Z+\xi_{\sigma} )(T+m)^2}
     {T(T+2m)}[ \ln (T/k_c )]^\alpha F_{\sigma} (Z,X,Y)
\mbox{\quad(barn)}\\
\end{equation}
and
\begin{equation}
\label{eq:phys340-2}
E_{Loss}^{brem} (Z,T,k_c ) =\frac{Z(Z+ \xi_l)(T+m)^2 }
      {(T+2m)}\left[\frac{k_c C_ M }{T}\right]^\beta
      F_{l} (Z,X,Y) \mbox{\quad(GeV barn)}
\end{equation}
where  $m$ is the mass of the electron,
\[
\begin{array}{LLL}
X = \ln(E/m), & Y = \ln (v_{\sigma} E/k_c) &
\mbox{\quad for the total cross-section }\sigma \\
X = \ln(T/m), & Y = \ln(k_c/v_lE)       &
\mbox{\quad for the energy loss }  E_{Loss}^{brem}  \\
\end{array}
\]
with $E=T+m$.
The constants $\xi_{\sigma},\ \xi_l,\ \alpha,\ \beta,\ v_{\sigma},\ v_l$
are parameters to be fitted.
\begin{eqnarray*}
C_M &=&\frac{\Dstm 1}{1+\frac{\Tstm n r_0 \lambdar^2  (T+m)^2}{\Tstm\pi k^2_c}}
\end{eqnarray*}
is the Midgal correction factor, with
\begin{DLtt}{MM}
\item[$r_o$] classical electron radius;
\item[$\lambdar$] reduced electron Compton wavelength;
\item[$n$] electron density in the medium.
\end{DLtt}
The factors $(T+m)^2/T(T+2m)$ and $(T+m)^2/(T+2m)$ come from
the scaled cross-section computed by Seltzer and Berger:
\[
f(k/T) = \frac{\beta^2}{Z^2 }k\frac{d \sigma}{dk}
       = \frac{T(T+2m)} {(T+m)^2 Z^2}  k \frac{d \sigma}{dk}
\]

The functions $F_i(Z,X,Y)$ ($ i=\sigma,l $) have the form
\begin{equation}
 F_i(Z,X,Y) = F_{i0}(X,Y)+ZF_{i1}(X,Y)
\end{equation}
where $\Dstm F_{ij}(X,Y)$ are polynomials of the variables $\Dstm X,Y$
\begin{eqnarray}
F_{i0}(X,Y) & = &  (C_1+C_2X+\ldots+C_6X^5)+(C_7+C_8X+\ldots+C_{12}X^5)Y
                                                             \nonumber \\
          &   & +(C_{13}+C_{14}X+\ldots + C_{18}X^5)Y^2+\ldots
                +(C_{31}+C_{32}X+\ldots+C_{36}X^5)Y^5                  \\
          &   & \mbox{\hspace{11cm}} \Bbfm Y\leq 0  \Ebfm    \nonumber \\
          & = &  (C_1+C_2X+\ldots+C_6X^5)+(C_7+C_8X+\ldots+C_{12}X^5)
                                                             \nonumber \\
          &   & +(C_{37}+C_{38}X+\ldots+C_{42}X^5)Y^2+\ldots+
                 (C_{55}+C_{56}X+\ldots+C_{60}X^5)Y^5        \nonumber \\
          &   & \mbox{\hspace{11cm}} \Bbfm Y > 0\Ebfm        \nonumber \\
F_{i1}(X,Y) & = &  (C_{61}+C_{62}X+\ldots+C_{65}X^4)
                +(C_{66}+C_{67}X+\ldots+C_{70}X^4)Y          \nonumber \\
          &   & +(C_{71}+C_{72}X+\ldots+C_{75}X^4)Y^2+\ldots
                +(C_{81}+C_{82}X+\ldots+C_{85}X^4) Y^4                 \\
          &   &   \mbox{\hspace{11cm}} \Bbfm Y\leq 0\Ebfm    \nonumber \\
          & = &  (C_{61}+C_{62}X+\ldots+C_{65}X^4)
                +(C_{66}+C_{67}X+\ldots+C_{70}X^4)Y          \nonumber \\
          &   & +(C_{86}+C_{87}X+\ldots+C_{90}X^4)Y^2+\ldots
                +(C_{96}+C_{97}X+\ldots+C_{100}X^4)Y^4       \nonumber  \\
          &   &  \mbox{\hspace{11cm}} \Bbfm Y>0 \Ebfm        \nonumber \\
\end{eqnarray}
$F_{ij}(X,Y)$ denotes in fact a function constructed from two
polynomials
\[
F_{ij}(X,Y) = \left \{
\begin{array}{ll}
F_{ij}^{neg}(X,Y) & \mbox{for\hspace{0.5cm}} Y\leq 0 \\
F_{ij}^{pos}(X,Y) & \mbox{for\hspace{0.5cm}} Y>0
\end{array} \right .
\]
where the polynomials $F_{ij}$ fulfil the conditions
\[
F_{ij}^{neg}(X,Y)_{Y=0} = F_{ij}^{pos}(X,Y)_{Y=0}   \hspace{2cm}
\left ( \frac{\partial F_{ij}^{neg}}{\partial Y} \right )_{Y=0} =
\left ( \frac{\partial P_{ij}^{pos}}{\partial Y} \right )_{Y=0}
\]
We have computed 4000 ``data points'' in the range
\[
Z = 6  ;  13  ;  29  ;  47  ;  74  ;  92  \hspace{1cm}
10 \: \mbox{keV} \leq T \leq 10 \: \mbox{TeV}  \hspace{1cm}
10 \: \mbox{keV} \leq k_c \leq T
\]
and we have performed a least-squares fit to determine the parameters.

The values of the parameters ($\xi_{\sigma}$, $\alpha$,
$v_{\sigma}$, $C_i $ for $\sigma$ and
$\xi_l$, $\beta$, $V_l$, $C$ for $E_{Loss}^{brem}$)
can be found in the {\tt DATA}
statement within the functions
\Rind{GBRSGE} and \Rind{GBRELE}  which compute the formula (\ref{eq:phys340-1})
and (\ref{eq:phys340-2}) respectively.

The errors of the parameterisations (\ref{eq:phys340-1}) and (\ref{eq:phys340-2})
can be estimated as

\begin{eqnarray*}
\frac{\Delta\sigma} {\sigma} & = & \left \{
\begin{array}{llr}
        12-15\%    & \mbox{for    } & T \leq 1 MeV \\
        \leq 5-6\% & \mbox{for    } & 1 MeV < T \leq 10 TeV
\end{array}
\right . \\[1cm]
\frac{\Delta E_{Loss}^{brem}}
     {E_{Loss}^{brem}} & = & \left \{
\begin{array}{llr}
        10-15\%    & \mbox{for    } & T \leq1 MeV  \\
        5-6\%      & \mbox{for    } & 1 MeV < T \leq 100 GeV\\
        10\%       & \mbox{for    } & 100 GeV < T \leq10 TeV
\end{array}
\right .
\end{eqnarray*}

We have performed a fit to the ``data'' without the Midgal corrections, too.
In this case we used the data of Seltzer and Berger without any
correction for $T \leq 10$ GeV and we used the Bethe-Heitler cross-section
for $T \geq 10$ GeV. The parameterised forms of the cross-section and
energy loss are the same as they were in the first fit (i.e. (\ref{eq:phys340-1})
and (\ref{eq:phys340-2})), only the numerical values of the parameters
have changed.
These values are in {\tt DATA} statements in the functions \Rind{GBRSGE}
and \Rind{GBRELE} and this second kind of parameterisation can be activated
using the \Rind{PATCHY} switch {\tt +USE,BETHE}. (The two
parameterisations give different results for high electron energy.)

The energy loss due to soft photon bremsstrahlung is tabulated at
initialisation time as a function of the medium and of the energy by
routine \Rind{GBRELA} (see {\tt JMATE} data structure).

The mean free path for discrete bremsstrahlung is tabuled at initialisation
time as a function
of the medium and of the energy by routine \Rind{GBRSGA} (see
{\tt JMATE} data structure).

\subsection{Corrections for $\Pem/\Pep$ differences}

The radiative energy loss for electrons or positrons is:

\begin{eqnarray*}
-\frac{1}{\rho} \left ( \frac{dE}{dx} \right )_{rad}^{\pm} & = &
\frac{N_{Av} \alpha r_e^2}{A} (T+m) Z^2 \Phi_{rad}^{\pm}(Z,T) \\
\Phi^{\pm}_{rad}(Z,T) & = & \frac{1}{\alpha r_{e}^2 Z^2 (T+m)}
\int^{T}_{0}{k\frac{d\sigma^{\pm}}{dk}dk}
\end{eqnarray*}

Reference \cite{bib-KIM1} says that: \\
{\it ``The differences between the radiative loss of positrons
and electrons are considerable and cannot be disregarded.

[...] The ratio of the radiative energy loss for positrons
to that for electrons obeys a simple scaling law, [...] is a
function only of the quantity $T/Z^2$''}

In other words:

\begin{eqnarray*}
\eta & = & \frac{\Phi_{rad}^{+}(Z,T)}{\Phi_{rad}^{-}(Z,T)} =
\eta \left (\frac{T}{Z^2}\right )
\end{eqnarray*}

The authors have calculated this function in the range $10^{-7}
\leq \frac{T}{Z^2} \leq 0.5$ (here the kinetic energy T is
expressed in MeV). Their {\it data} can be fairly accurately
reproduced using a parametrisation:

\begin{eqnarray*}
\eta & = & \left \{
\begin{array}{llr}
0 & \mbox{if   } & x \leq -8 \\
\frac{1}{2} + \frac{1}{\pi} \arctan \left( a_1 x + a_3 x^3
+ a_5 x^5 \right ) & \mbox{if  } & -8 < x < 9 \\
1 & \mbox{if   } & x \geq 9
\end{array}
\right .
\end{eqnarray*}

where:

\begin{eqnarray*}
x & = & \log \left ( C \frac{T}{Z^2} \right ) \mbox{(T in GeV)} \\
C & = & 7.5221 \times 10^{6} \\
a_1 & = & 0.415 \\
a_3 & = & 0.0021 \\
a_5 & = & 0.00054
\end{eqnarray*}

This $\Pem/\Pep$ energy loss difference is not a pure low-energy
phenomenon (at least for high Z), as it can be seen from
Tables~\ref{tb:phys340-1}, \ref{tb:phys340-2} and \ref{tb:phys340-3}.

\begin{table}[hbt]
\begin{centering}
\begin{tabular}{rr|r|r} \hline
\multicolumn{1}{c}{$\frac{T}{Z^2} (GeV)$}
& \multicolumn{1}{c|}{T}
& \multicolumn{1}{c|}{$\eta$}
& \multicolumn{1}{c}{$\left ( \frac{rad. \ loss}{total \ loss}
\right )_{e^-}$} \\[3mm] \hline
$10^{-9}$ & $\sim 7 keV$ & $\sim 0.1$ & $\sim 0\%$ \\
$10^{-8}$ & $67 keV $ & $\sim 0.2$ & $\sim 1\%$ \\
$2 \times 10^{-7}$ & $1.35 MeV$ & $\sim 0.5$ & $\sim 15\%$ \\
$2 \times 10^{-6}$ & $13.5 MeV$ & $\sim 0.8$ & $\sim 60\%$ \\
$2 \times 10^{-5}$ & $135. MeV$ & $\sim 0.95$ & $> 90\%$ \\ \hline
\end{tabular}
\caption{ratio of the $\Pem/\Pep$ radiative energy loss in lead
(Z=82).}
\label{tb:phys340-1}
\end{centering}
\end{table}

The scaling holds for the ratio of the total radiative energy
losses, but it is significantly broken for the photon spectrum
in the screened case.
In case of a point Coulomb charge the
scaling would hold also for the spectrum.
The scaling can be expressed by:

\begin{eqnarray*}
\frac{\Phi^+}{\Phi^-} = \eta \left ( \frac{T}{Z^2} \right )
& \hspace{3cm} &
\frac{\frac{d\sigma^+}{dk}}{\frac{d\sigma^-}{dk}} =
\mbox{does not scale}
\end{eqnarray*}

If we consider the photon spectrum from bremsstrahlung reported
in \cite{bib-KIM1} we see that:

\begin{eqnarray*}
\frac{d\sigma^{\pm}}{dk} = S^{\pm} \left( \frac{k}{T} \right )
\hspace{2cm}
\frac{S^{+}(k)}{S^{-}(k)} \leq 1 & \hspace{1cm} & S^{+}(1) = 0
\hspace{2cm} S^{-}(1)  >  0
\end{eqnarray*}

\begin{table}[hbt]
\begin{centering}
\begin{tabular}{l|rrr|rrr}
\hline
\multicolumn{1}{c}{T(MeV)}
& \multicolumn{3}{|c|}{C}
& \multicolumn{3}{c}{Pb} \\[2mm]
\hspace{1cm}
& $\Delta E^{0}_{l}$ & $\Delta E_{l}$ & $\Delta \sigma_{l}$
& $\Delta E^{0}_{l}$ & $\Delta E_{l}$ & $\Delta \sigma_{l}$ \\
\hline
0.02   & -2.86 & -2.86 & +52.00 & -4.89 & -4.69 & +99.80 \\
0.1    & -0.33 & -0.33 & +21.10 & -0.52 & -0.47 & +81.08 \\
1      & +0.07 & +0.07 &  +6.49 & +0.11 & +0.11 & +48.99 \\
10     &  0.00 &  0.00 &  +1.75 &  0.00 & +0.01 & +23.89 \\
$10^2$ &  0.00 &  0.00 &   0.00 &  0.00 &  0.00 &  +9.00 \\
$10^3$ &  0.00 &  0.00 &   0.00 &  0.00 &  0.00 &  +2.51 \\
$10^4$ &  0.00 &  0.00 &   0.00 &  0.00 &  0.00 &  +0.00 \\
\hline
\multicolumn{7}{c}{\hspace{1cm}} \\
\multicolumn{7}{c}{
$\displaystyle{\Delta E_{l} =
100 \frac{E^{-}_{l}-E^{+}_{l}}{E^{-}_{l}}\%}$ \hspace{5mm} and
\hspace{5mm}
$\displaystyle{\Delta \sigma_{l} =
100 \frac{\sigma^{-}_{l}-\sigma^{+}_{l}}{\sigma^{-}_{l}}\%}$
}
\end{tabular}
\caption{Difference in the energy loss and bremsstrahlung
cross-section for $\Pem/\Pep$ in Carbon and Lead with a
cut for $\gamma$ and $e^{\pm}$ of 10keV. $\Delta E^{0}_{l}$ is
the value without the correction for the difference
$\Pem/\Pep$.}
\label{tb:phys340-2}
\end{centering}
\end{table}

We further assume that:

\begin{eqnarray}
\frac{d\sigma^+}{dk} = f(\epsilon) \frac{d\sigma^-}{dk}
& \hspace{2cm} &
\epsilon = \frac{k}{T}
\label{eq:phys340-3}
\end{eqnarray}

In order to satisfy approximately the scaling law for the ratio
of the total radiative energy loss, we require for $f(\epsilon)$:

\begin{eqnarray}
\int^{1}_{0}{f(\epsilon)d\epsilon} & = & \eta
\label{eq:phys340-4}
\end{eqnarray}

From the photon spectra we require:

\begin{eqnarray}
\left .
\begin{array}{l}
f(0) = 1 \\
f(1) = 0
\end{array}
\right \} \hspace{2cm} \mbox{for all $Z,T$}
\label{eq:phys340-5}
\end{eqnarray}

We have chosen a simple function $f$:

\begin{eqnarray}
f(\epsilon) & = & C (1-\epsilon)^{\alpha} \hspace{3cm} C,\alpha > 0
\label{eq:phys340-6}
\end{eqnarray}

\begin{table}[hbt]
\begin{centering}
\begin{tabular}{l|rrr|rrr}
\hline
\multicolumn{1}{c}{T(MeV)}
& \multicolumn{3}{|c|}{C}
& \multicolumn{3}{c}{Pb} \\[2mm]
\hspace{1cm}
& $\Delta E^{0}_{l}$ & $\Delta E_{l}$ & $\Delta \sigma_{l}$
& $\Delta E^{0}_{l}$ & $\Delta E_{l}$ & $\Delta \sigma_{l}$ \\
\hline
2      & +4.19 & +4.21 &  +7.29 & +4.47 & +6.88 & +61.78 \\
10     & +0.87 & +0.87 &  +1.93 & +0.87 & +1.14 & +26.29 \\
$10^2$ & +0.08 & +0.08 &   0.00 & +0.06 & +0.06 &  +9.10 \\
$10^3$ &  0.00 &  0.00 &   0.00 &  0.00 &  0.00 &  +2.42 \\
$10^4$ &  0.00 &  0.00 &   0.00 &  0.00 &  0.00 &  +0.00 \\
\hline
\multicolumn{7}{c}{\hspace{1cm}} \\
\multicolumn{7}{c}{
$\displaystyle{\Delta E_{l} =
100 \frac{E^{-}_{l}-E^{+}_{l}}{E^{-}_{l}}\%}$ \hspace{5mm} and
\hspace{5mm}
$\displaystyle{\Delta \sigma_{l} =
100 \frac{\sigma^{-}_{l}-\sigma^{+}_{l}}{\sigma^{-}_{l}}\%}$
}
\end{tabular}
\caption{Difference in the energy loss and bremsstrahlung
cross-section for $\Pem/\Pep$ in Carbon and Lead with a
cut for $\gamma$ and $e^{\pm}$ of 1MeV. $\Delta E^{0}_{l}$ is
the value without the correction for the difference
$\Pem/\Pep$.}
\label{tb:phys340-3}
\end{centering}
\end{table}

\begin{table}[hbt]
\begin{centering}
\begin{tabular}{r|rr|rr}
\multicolumn{5}{c}{$\displaystyle{100 \frac{E^{+}_{dep}-E^{-}_{dep}}
{\sqrt{\sigma_{+}^{2}+\sigma_{-}^{2}}} (\%)}$} \\[5mm]
\hline
\multicolumn{1}{c}{Depth}
& \multicolumn{2}{c}{C}
& \multicolumn{2}{|c}{Pb} \\
\multicolumn{1}{c|}{($X_{0}$ units)} &
No $e^{\pm}$ diff & $e^{\pm}$ diff &
No $e^{\pm}$ diff & $e^{\pm}$ diff \\
\hline
0.5 &   -11.7 & -13.0 &  -0.8 &  -3.9 \\
1.0 &    -5.3 &  -4.9 &  -1.0 &  -4.1 \\
1.5 &    +7.3 &  +8.0 &  -1.4 &  -3.5 \\
2.0 &    +7.1 &  +5.3 &  -0.7 &  -0.0 \\
2.5 &    +4.9 &  +4.3 &  +1.7 &  +3.6 \\
3.0 &    +4.8 &  +4.1 &  +1.1 &  +4.3 \\
3.5 &    +3.3 &  +2.7 &  +2.7 &  +3.1 \\
4.0 &    +3.6 &  +5.3 &  +2.9 &  +3.0 \\
4.5 &    +1.7 &  +2.8 &  +0.5 &  +2.3 \\
5.0 &    +3.4 &  +3.5 &  -1.9 &  +1.8 \\
\hline
\end{tabular}
\caption{Difference in the shower development
for $\Pem/\Pep$ in Carbon and Lead.
{\it No diff} refers to the
value without the correction for the difference
$\Pem/\Pep$.}
\label{tb:phys340-4}
\end{centering}
\end{table}

from the conditions (\ref{eq:phys340-4}), (\ref{eq:phys340-5}) we get:

\begin{eqnarray*}
C & = & 1 \\
\alpha & = & \frac{1}{\eta} - 1 \hspace{2cm}
\mbox{($\alpha > 0$ because $\eta < 1$)} \\
f(\epsilon) & = & (1-\epsilon)^{\frac{1}{\eta}-1}
\end{eqnarray*}

We have defined weight factors $F_{l}$ and $F_{\sigma}$ for the
positron continuous energy loss and discrete bremsstrahlung cross
section:

\begin{eqnarray}
F_{l} = \frac{1}{\epsilon_{0}} \int^{\epsilon_{0}}_{0}
{f(\epsilon)d\epsilon} & \hspace{3cm} &
F_{\sigma} = \frac{1}{1-\epsilon_{0}} \int^{1}_{\epsilon_{0}}
{f(\epsilon)d\epsilon}
\label{eq:phys340-7}
\end{eqnarray}

where $\epsilon_{0} = \frac{k_c}{T}$ and $k_c$ is the photon
cut {\tt BCUTE}. In this scheme the positron energy loss and
discrete bremsstrahlung can be calculated as:

\begin{eqnarray*}
\left ( - \frac{dE}{dx} \right )^{+} = F_{l}
\left ( - \frac{dE}{dx} \right )^{-} & \hspace{2cm} &
\sigma^{+}_{brems} = F_{\sigma} \sigma^{-}_{brems}
\end{eqnarray*}

As in this approximation the photon spectra are identical, the
same SUBROUTINE is used for generating $\Pem/\Pep$ bremsstrahlung.
The following relations hold:

\begin{eqnarray*}
F_{\sigma} & = & \eta (1-\epsilon_{0})^{\frac{1}{\eta}-1}
< \eta \\
\epsilon_{0} F_{l} + (1-\epsilon_{0}) F_{\sigma} & = & \eta
\hspace{6cm} \mbox{from the def (\ref{eq:phys340-7})} \\
\Rightarrow F_{l} & = & \eta \frac{1-(1-\epsilon_{0})^{\frac{1}
{\eta}})}{\epsilon_{0}} > \eta \frac{1-(1-\epsilon_{0})}
{\epsilon_{0}} = \eta  \hspace{1cm}
\Rightarrow   \left \{
\begin{array}{l}
F_{l} > \eta \\
F_{\sigma} < \eta
\end{array} \right .
\end{eqnarray*}

which is consistent with the spectra.

The effect of this $\Pem/\Pep$ bremsstrahlung difference can be also
seen in e.m. shower development, when the primary energy is not too
high. An example can be found in table~\ref{tb:phys340-4}.


\lab{Getting Started}{Getting Started}
\objective{Introduce basic coding procedures and objects usage in Python.}
\label{lab:Essential_Python}

\section*{Python}
Python is a powerful general-purpose programming language. As an interpreted
language, it can be used interactively.
It is quickly gaining momentum as a fundamental tool in scientific computing because it has the following features:
\begin{itemize}
\item Clear, readable syntax
\item Full object orientation
\item Complete memory management (via garbage collection)
\item High level, dynamic datatypes
\item Extensibility via C
\item Ability to interface with other languages such as R, C, C++, and Fortran
\item Embeddability in applications
\item Portability across many platforms (Linux, Windows, Mac OSX)
\item Open source
\end{itemize}
In addition to these, Python is freely available and can also be freely distributed.

\section*{Running Python}
Python 2.7 is required for the labs in this text and can be downloaded from \url{http://www.python.org/}. Although later versions of
Python are available, they do not have many of the features needed for scientific computing.

Many free IDEs (Integrated Development Environments) and text editors are compatible with Python. We recommend you use IPython, which provides three different interfaces: commandline, QTConsole, and Notebook. You can open these interfaces by running \li{ipython}, \li{ipython qtconsole}, or \li{ipython notebook} respectively.
The commandline interface is the simplest of the three, as it merely adds colored syntax to the text in the terminal window.
The QTConsole provides some extra features not available in the commandline interface.
The Notebook interface has the most features and is displayed in a web browser.

For more information on installing Python and various libraries, see Appendices \ref{win64install} and \ref{pythoninstall}.

\section*{Learning Python}
The remainder of this lab will introduce you to some basic Python data types and control flow blocks. The text for this lab is intended to tell you just enough so that you can create these objects and experiment with them. Each section has additional required readings, listed at its end. Moreover, as you begin your study of Python, we \emph{strongly} suggest you read the following:
\begin{enumerate}
\item Chapters 3, 4, and 5 of the Official Python Tutorial \\
        (\url{http://docs.python.org/2.7/tutorial/introduction.html}).
\item Section 1.2 of the SciPy Lecture Notes\\
        (\url{http://scipy-lectures.github.io/}).
\item PEP8 - Python Style Guide \\
        (\url{http://www.python.org/dev/peps/pep-0008/}).
\end{enumerate}

In addition to these resources, there are other ways to learn Python. One useful aspect of the IPython interfaces is \emph{object introspection}, which allows you to see all the methods associated to an object. Also, you can use a question mark to learn about an object or method.

\begin{lstlisting}
# You can use a pound sign to write a single-line comment.

# To see the methods associated to an object, type the object name followed by a period, and press tab.
>>> list.
list.append   list.extend   list.insert   list.pop      list.reverse
list.count    list.index    list.mro      list.remove   list.sort

# To learn about a method, use "?".
>>> list.append?
Type:       method_descriptor
Base Class: <type 'method_descriptor'>
String Form:<method 'append' of 'list' objects>
Namespace:  Python builtin
Docstring:  L.append(object) -- append object to end
\end{lstlisting}

Finally, if you cannot answer your question using these strategies, try googling it. Many common questions about Python programming have been answered on internet forums.

\section*{Data Types}
\subsection*{Numerical Types}
There are four numerical data types, \li{int}, \li{long},
\li{float}, and \li{complex}, each of which stores a certain kind of number.

\begin{lstlisting}
>>> type(3)
int

>>> type(3.0)
float
\end{lstlisting}

Python can be used as a calculator. Use \li{**} for exponentiation.
\begin{lstlisting}
>>> 3**2 + 2*5
19
\end{lstlisting}

We can also create and manipulate variables with Python.

\begin{lstlisting}
# Use a SINGLE equals sign to create a variable.
>>> x = 12
>>> y = 2 * 6

# Use a DOUBLE equals sign to check equality of variables.
>>> x == y
True
\end{lstlisting}

Required readings:
\begin{itemize}
\item \url{http://scipy-lectures.github.io/intro/language/basic_types.html#numerical-types}
\item \url{https://docs.python.org/2.7/tutorial/introduction.html#numbers}
\item \url{https://docs.python.org/2.7/library/stdtypes.html#typesnumeric}
\end{itemize}

\begin{problem}
Use the required readings and the strategies listed in the section ``Learning Python'' to help you answer the questions in this lab.
\begin{enumerate}

\item How do you convert an integer to a float? (This is called \emph{casting}.)
\item What are the two ways to create a complex number?
How do you extract the real part or the imaginary part?
\item The way the operator \li{/} behaves depends on the types of its operands.
\begin{enumerate}
\item Why does \li{7/3} return 2?
\item How can you get decimal answers to a division problem like $7/3$?
\item How can you get integer answers when you divide floats?
\end{enumerate}
\end{enumerate}
\end{problem}

\subsection*{Strings}
A Python \li{string} can be created with either single or double quotes. They can be concatenated with the \li{+} operator.
\begin{lstlisting}
>>> str1 = "I love"
>>> str2 = 'the ACME program'
>>> my_string = str1 + " " + str2 + "!"
>>> mystring
'I love the ACME program!'
\end{lstlisting}

We can access single characters of strings using brackets and a range of characters using \emph{slicing}. Slicing syntax is \li{[start:stop:step]}. The parameters \li{start} and \li{stop} default to the beginning and end of the string, respectively. The parameter \li{step} defaults to 0. For more information on slicing, see the section ``Lists.''

\begin{lstlisting}
# Indexing begins at 0 and negative numbers count backwards from the end.
>>> my_string[-1]
'!'

# Pick out every other character in a string.
>>> my_string[::2]	# string[start:stop:step]
'Ilv h CEporm'
\end{lstlisting}

Required readings:
\begin{itemize}
\item \url{http://scipy-lectures.github.io/intro/language/basic_types.html#strings}
\item \url{https://docs.python.org/2.7/tutorial/introduction.html#strings}
\end{itemize}

\begin{problem}
Answer the following questions about strings.
\begin{enumerate}
\item Suppose \li{my_string = "I love the new ACME program\!"}. What output is produced by \li{my_string[::3]} and \li{my_string[::-1]}?
\item How can you print a \li{string} backwards?
\end{enumerate}
\end{problem}

\subsection*{Lists}
A Python \li{list} is created by enclosing comma-separated values with square brackets. You can access a single entry of a \li{list} or a range of entries with the same indexing or slicing operations as we used on strings.
\begin{lstlisting}
>>> my_list = ["Remi", 21, "08/06", 1993]
>>> my_list
['Remi', 21, '08/06', 1993]
>>> my_list[-2]
'08/06'
\end{lstlisting}

Whenever possible, you should create your lists using a \emph{list comprehension}, which is demonstrated below.
\begin{lstlisting}
# The command range(n) produces the list [0, 1, 2, . . . , n-1].
>>> [x**2 for x in range(10)]
[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
\end{lstlisting}

Required readings:
\begin{itemize}
\item \url{http://scipy-lectures.github.io/intro/language/basic_types.html#lists}
\item \url{https://docs.python.org/2.7/tutorial/introduction.html#lists}
\item \url{https://docs.python.org/2.7/tutorial/datastructures.html#list-comprehensions}
\end{itemize}

\begin{problem}
Answer the following questions about lists.

\begin{enumerate}
\item If \li{my_list = ["mushrooms", "rock climbing", 1947, 1954, "yoga"]}, write a sequence of commands that does the following:
\begin{enumerate}
\item Finds the length of the list,
\item Appends ``Jonathan, my pet fish'' to the end of the list,
\item Inserts \li{'pizza'} at index 3, and
\item Clears the entire list.
\end{enumerate}
\item Write a sequence of commands that does the following:
\begin{enumerate}
\item Creates an empty list called \li{num},
\item Adds the integers \li{3}, \li{5}, \li{19}, \li{20}, and \li{4} to \li{num},
\item Replaces the integer at index 3 with itself converted to a string,
\item Removes the integer at index 2, and
\item Sorts \li{num} backwards.
\end{enumerate}
\item Using a list comprehension, create a list that has the elements of \li{num} converted into strings. For example, if \li{num = [ 5, 4, 3, 2, 1]}, write a list comprehension that outputs \li{num=['5', '4', '3', '2', '1']}.
\end{enumerate}

\end{problem}

\subsection*{Sets}
A Python \li{set} is an unordered collection of distinct objects, and can be created from a list. We can add or remove members from a set after its creation.
\begin{lstlisting}
>>> gym_members = set(["Doe, John", "Doe, John", "Smith, Jane", "Brown, Bob"])
>>> gym_members
set(['Brown, Bob', 'Doe, John', 'Smith, Jane'])
>>> gym_members.discard("Doe, John");
>>> gym_members
set(['Brown, Bob', 'Smith, Jane'])
>>> gym_members.add("Lytle, Josh")
>>> gym_members
set(['Brown, Bob', 'Lytle, Josh', 'Smith, Jane'])
\end{lstlisting}

Like mathematical sets, a \li{set} has operations like union, intersection,
difference, and symmetric difference.

\begin{lstlisting}
# Set intersection returns a new set object.
>>> library_members = set(["Lytle, Josh", "Henriksen, Ian", "Grout, Ryan"])
>>> set.intersection(gym_members, library_members)
set(['Lytle, Josh'])
\end{lstlisting}

Required readings:
\begin{itemize}
\item \url{http://scipy-lectures.github.io/intro/language/basic_types.html#more_container_types}
\item \url{https://docs.python.org/2.7/tutorial/datastructures.html#sets}
\end{itemize}

\begin{problem}
Answer the following questions about sets.
\begin{enumerate}
\item What are two ways to create sets? How do you create an empty set?
\item Define two sets and use a Python command to find their union.
\end{enumerate}
\end{problem}

\subsection*{Dictionaries}
Like a \li{set}, a Python \li{dictionary} is an unordered data type.  A \li{dictionary} stores \li{key:value} pairs, which are called \emph{items}. The values of a dictionary are indexed by its keys.
\begin{lstlisting}
>>> tel = {"marriott": 4121, "math": 2061, "visual arts" : 7321}
>>> tel["math"]
2061
\end{lstlisting}

The keys of a dictionary must be \emph{immutable}, which means that they must be objects that cannot be modified after creation. Numerical types and strings are immutable objects. Lists, dictionaries, and sets are mutable.

Required readings:
\begin{itemize}
\item \url{http://scipy-lectures.github.io/intro/language/basic_types.html#dictionaries}
\item \url{https://docs.python.org/2.7/tutorial/datastructures.html#dictionaries}
\end{itemize}

\begin{problem}
Answer the following questions about dictionaries.
\begin{enumerate}
\item What are two ways to create dictionaries? How do you create an empty dictionary?
\item How do you delete a key-value pair from a dictionary?
\item How do you access a list of all the values in your dictionary?
How do you access a list of all the items?
\end{enumerate}
\end{problem}

\section*{Control Flow Tools}
Control flow blocks control the order in which your code is executed.
Python supports the usual control flow statements
including while loops, if statements, for loops, and function definitions. For examples besides those in this lab, see the following resources:

\begin{itemize}
\item Sections 1.2.3.1-1.2.3.4 of \url{http://scipy-lectures.github.io/intro/language/control_flow.html}
\item \url{http://scipy-lectures.github.io/intro/language/functions.html}
\item \url{https://docs.python.org/2.7/tutorial/introduction.html#first-steps-towards-programming}
\item Sections 4.1-4.3, 4.6, and 4.7.1-4.7.2 of \url{https://docs.python.org/2.7/tutorial/controlflow.html}
\end{itemize}

\subsection*{The While Loop}
Python uses indentation to identify the beginning and end of blocks of code, so you must indent each line of an execution block the same way.
The convention is to indent blocks of code with four spaces. A \li{while} loop executes an indented block of code \emph{while} the given condition holds.

\begin{lstlisting}
>>> i = 0
>>> while i < 10:           # The colon is required.
...     print i,             # This indented line is executed if b<10.
...     i = i+1       # This indented line is also executed if b<10.
...
0 1 2 3 4 5 6 7 8 9
\end{lstlisting}
In the above example, the comma in the line \li{print i,} makes Python print all the numbers on the same line (by stripping off newline characters). Try running this example without the comma and see what happens.

\subsection*{The If Statement}
An \li{if} statement executes the
indented code \emph{if} the given condition holds.
The \li{elif} statement is short for ``else if'' and can be used multiple times following an \li{if} statement, or not at all.
The \li{else} keyword may be used at most once at the end of a series of \li{if}/\li{elif} statements.
\begin{lstlisting}
>>> food = "bagel"         # Use a SINGLE equals sign create variables
>>> if food == "apple":    # Use a DOUBLE equals sign to check equality
...     print "72 calories"
... elif food == "banana":
...     print "105 calories"
... elif food == "egg":
...     print "102 calories"
... else:
...     print "calorie count unavailable"
...
calorie count unavailable
\end{lstlisting}

\subsection*{The For Loop}
A \li{for} loop iterates over the items in any \emph{iterable}. Iterables include lists, sets, and dictionaries.

\begin{lstlisting}
>>> for i in range(10):
...     print i,
...
0 1 2 3 4 5 6 7 8 9
\end{lstlisting}

\subsection*{Function Definition}
To define a function, use the \li{def} keyword followed by the function name and a parenthesized list of formal parameters. Then indent the function body.
\begin{lstlisting}
# Compute the area of a rectangle
>>> def area(width, height):
...     return width*height
...
>>> area(2, 5)
10
\end{lstlisting}

We define a function with \emph{parameters} and call it with \emph{arguments}.
In the example above, \li{width} and \li{height} are parameters for the function \li{area}. The values \li{2} and \li{5} are the arguments that we pass when calling the function. In practice, the terms \emph{parameter} and \emph{argument} are often used interchangeably.

It is also possible to specify default values for formal parameters, as in the following example.
\begin{lstlisting}
>>> def fn(a, b, c=0):
...    print a, b, c
\end{lstlisting}
The function \li{fn} has three formal parameters, and the value of \li{c} defaults to 0.
We can pass arguments to \li{fn} based on position (positional arguments) or name (named arguments or keyword arguments). We must define positional arguments before keyword arguments.
\begin{lstlisting}
# Call fn with 2 positional arguments (c=0 by default)
>>> fn(1, 2)
1 2 0

# Call fn with 3 positional arguments
>>> fn(4, 5, 6)
4 5 6

# Call fn with 1 positional argument and 2 named arguments
>>> fn(1, c=2, b=3)
1 3 2
\end{lstlisting}
The final example demonstrates the flexibility of Python but is somewhat confusing. Whenever possible, you should pass arguments to a function in the order they are defined in the function. Thus, do the following.
\begin{lstlisting}
# Call fn with 1 positional argument and 2 named arguments
>>> fn(1, b=3, c=2)
1 3 2
\end{lstlisting}

\begin{problem}
Define the following function in your interpreter.
\begin{lstlisting}
>>> def track(n, my_list=[]):
...    my_list.append(n)
...    return my_list
\end{lstlisting}
\begin{enumerate}
\item Now execute the following commands in your interpreter: \li{track(1)}, \li{track(2)}, \li{track(3)} and  \li{track(1, [1, 2, 3])}. What outputs do you get?
\item The default values of a function are only evaluated once.
This means that when you call \li{track} with the default value for \li{my_list}, the same list is used each time.
Modify \li{track} so that the default value for \li{my_list} is not shared between calls.
With your modified function, the outputs in part (a) should be \li{[1]}, \li{[2]}, \li{[3]} and \li{[1, 2, 3, 1]}. Hint: Read here about the Python constant \li{None}: \url{https://docs.python.org/2/library/constants.html}.
\end{enumerate}
\end{problem}

The most general form of a function definition is as follows.
\begin{lstlisting}
def fn(*args, **kwargs):
\end{lstlisting}
This means that ``\li{fn} takes some arguments and keyword arguments.''
The arguments, \li{args}, are stored as a tuple; and the keyword arguments, \li{kwargs}, are stored in a dictionary.
The function \li{fn} can accept any number of arguments and keyword arguments.
\begin{lstlisting}
>>> def fn(*args, **kwargs):
...     print "Positional: ", args
...     print "Keyword: ", kwargs
...
>>> fn("Hello", 2, 1, apples = 3, oranges = 2)
Positional: ('Hello', 2, 1)
Keyword: {'apples': 3, 'oranges': 2}
\end{lstlisting}

\begin{problem}

\begin{enumerate}
\item Explain what the \li{print} and \li{return} statements do. How are they different?
\item Modify the code below so that it produces the desired output.
\begin{lstlisting}
Grocery List = ['pineapple', 'orange juice', "avocados", "pesto sauce"]
for i in range(Grocery List)
if i % 2 = 0
print i, Grocery List(i)
\end{lstlisting}
Desired output:
\begin{lstlisting}
0 pineapple
2 avocados
\end{lstlisting}
\item When you call the function ``groceries'' below, it returns an error. Why?
\begin{lstlisting}
>>> def groceries(food, drink):
...     print food
...     print drink

>>> groceries(food="Bananas", "Juice")
\end{lstlisting}
\end{enumerate}
\end{problem}

\begin{comment}
\section*{Specifications}
We suggest that you submit your solutions in a file called \li{solutions.py}, using the following format.
\lstinputlisting[language=, abovecaptionskip=2pt, belowcaptionskip=2pt]{template.txt}
\end{comment}