\documentclass{article}

@{{{
aaa = 1
pyp.freeze()
bbb = 2
print(aaa,bbb)
pyp.clear()
print(aaa)
try:
	print(bbb)
except:
	print("As expected, bbb is now undefined.")
}}}
@{{{
try:
	print(bbb)
except:
	print("As expected again, bbb is still undefined.")
}}}

% This doesn't actually work.
\pdfinfoomitdate1
\pdfsuppressptexinfo-1
\pdftrailerid{}

\usepackage[utf8]{inputenc}
\usepackage[english]{babel}
\usepackage{amsmath}
\usepackage{verbatim}
\usepackage{relsize}
\usepackage{graphicx}

\usepackage{hologo}

@{from sympy import *}

\newcommand{\Longupdownarrow}{\Big\Updownarrow}
\usepackage{listings}
\lstset{
   basicstyle=\footnotesize\ttfamily}

\usepackage{natbib}

\newcommand{\pyptex}{{P\kern-0.08em\raisebox{-0.5ex}{Y\kern-0.1emP}\kern-0.28em\TeX{}}}

\title{\pyptex{}: The Python Preprocessor for \LaTeX{}.}
\date{wololo}
\author{Sébastien Loisel}

\begin{document}
\maketitle

\begin{abstract}
\pyptex{} is a Python template Preprocessor for \LaTeX{}. From a source template document \texttt{a.tex} containing specially marked Python code fragments, one or more pure \LaTeX{} files \texttt{a.pyptex} are generated and compiled into final \texttt{a.pdf} documents. Our new approach differs from previous approaches that embedded Python into the \LaTeX{} engine and allowed bidirectional communication between Python and \LaTeX{}. The embedded Python approach exposes users to security risks, but it also has a deadlock problem and is very hard to debug. By contrast, \pyptex{} avoids the security risks of embedded Python, completely eliminates the deadlock problem, and is easy to debug. We have used \pyptex{} to produce a 71-page handout for linear algebra students containing automatically generated problem sets. In combination with SymPy, SciPy and other Python packages, \pyptex{} can be used to create beautiful scientific documents.
\end{abstract}

\section{Introduction}

\pyptex{} is a macro preprocessor (or template engine) for \LaTeX{} \citep{lamport1994latex} that allows one to use the rich Python ecosystem to automate parts of the redaction of sophisticated scientific documents.
In combination with SciPy \citep{virtanen2020scipy} and SymPy \citep{meurer2017sympy}, \pyptex{} is a powerful tool for generating documents ranging from research papers and books to calculus problem sets for students.

One installs \pyptex{} by typing \texttt{pip install pyptex} at the command prompt. This assumes that one already has working Python and \LaTeX{} installations; by default, \pyptex{} assumes that \texttt{pdflatex} is available at the command line, although alternate \LaTeX{} implementations can also be used. Then, using one's favorite text editor, one places the following text in a file \texttt{example.tex}:
\begin{lstlisting}
\documentclass{article}
@@{from sympy import *}
\begin{document}
$$\int x^3\,dx = @@{S('integrate(x^3,x)')}+C$$
\end{document}
\end{lstlisting}
One compiles \texttt{example.tex} using the \pyptex{} command line \texttt{pyptex example.tex}. This generates the final output \texttt{example.pdf}, which contains this:
$$\int x^3\,dx = @{S('integrate(x^3,x)')}+C$$
As we can see, SymPy was used to compute an indefinite integral symbolically, and the result was typeset with standard \LaTeX{}.

\pyptex{} also produces the intermediate file \texttt{example.pyptex}, which is a pure-\LaTeX{} file that is useful either for debugging purposes, or for sending a final manuscript to a journal. It contains the following:
\begin{lstlisting}
\documentclass{article}
@{from sympy import *}
\begin{document}
$$\int x^3\,dx = @{S('integrate(x^3,x)')}+C$$
\end{document}
\end{lstlisting}
The SymPy Python code in the template file \texttt{example.tex} was executed and replaced with its own output in standard \LaTeX{} notation.
The file \texttt{example.pdf} was automatically generated by \pyptex{} from the \texttt{example.pyptex} file (internally, \pyptex{} invoked the command \texttt{pdflatex example.pyptex}).

\begin{figure}
$$\texttt{a.tex} \implies \text{\pyptex{}} \implies \texttt{a.pyptex} \implies \texttt{pdflatex}\implies \texttt{a.pdf}$$
\caption{Dataflow of a the \pyptex{} Python template Preprocessor. \label{f:pre}}
\end{figure}
\begin{figure}
$$\texttt{a.tex} \implies
\left\{
\begin{array}{c}
\texttt{pdflatex} \\
\Longupdownarrow \\
\text{Python}
\end{array}
\right\}
\implies \texttt{a.pdf}
$$
\caption{Dataflow when Python is embedded in the \texttt{pdflatex} engine. \label{f:embed}}
\end{figure}

In \pyptex{}, debugging and error handling are first-class citizens. If any errors occur during Python interpretation, \pyptex{} automatically launches the Python debugger Pdb in postmortem mode, just like standard \LaTeX{} enters \texttt{errorstopmode} on error. In Pdb, all standard Python debugging tools work as normal, and source code from the originating \texttt{.tex} file is visible in its context (e.g. with the \texttt{list} command). If an error occurs during \LaTeX{} compilation (e.g. during \texttt{pdflatex example.pyptex}), the usual error prompt is provided by \LaTeX{}.

\pyptex{} is a {\em preprocessor} (or {\em template engine}) for \LaTeX{}, see Figure \ref{f:pre}.
Python fragments are extracted from the (template) source \texttt{a.tex} file by a regular expression pattern matcher, executed by a Python interpreter, and substituted with the appropriate outputs. The collated file is written to disk as \texttt{a.pyptex}, which is a pure \LaTeX{} file. Because this procedure is done by regular expressions, the \LaTeX{} compiler is not invoked and not involved in parsing or processing \texttt{a.tex}. Once \texttt{a.pyptex} has been produced, then \texttt{a.pdf} is obtained, e.g. via \texttt{pdflatex a.pyptex}.

As far as we know, \pyptex{} is the first time that Python is formally used as a preprocessor or templating engine for \LaTeX{}. However, Python has previously been {\em embedded} into \LaTeX{} engines, see Figure \ref{f:embed}; we mention \citet{fine2005tex}, \citet{ehmsen}, \citet{poore2015pythontex}. For SymPy there is \citet{molteno2014sympytex} and for Sage there is \citet{drake2009sagetex}. Other scripting languages have also been embedded into \LaTeX{}, for example Perl \citep{pakin2004perltex} and Lua \citep{hagen2005luatex}. When Python is embedded into \LaTeX{}, all the Python fragments are extracted from a source \texttt{a.tex} file by the \TeX{} macro engine itself. After executing these Python fragments, the relevant outputs are substituted into the macro stream being ``digested'' by the \TeX{} engine \citep{knuth1984texbook}. Although templating engines for \LaTeX{} seem rare, they are commonly used for other document formats, see e.g. \citet{hepple1998}, or \citet{alchin2013pro}. Usually, templating engines focus on generating multiple documents from a single template, whereas \pyptex{} focuses on generating a single document from a template. For that reason, we prefer the terminology ``preprocessor''. That being said, \pyptex{} can indeed be used in a more traditional templating mode where multiple documents are generated from a single template \texttt{a.tex}.

With the help of \pyptex{}, we have produced a 71-page handout \citep{Loisel2020} for the course F19NB at Heriot-Watt University on numerical linear algebra. Previous to \pyptex{}, in 2018, we had used an ad-hoc and highly complex build system for \LaTeX{} code generation. While we distinguish this ad-hoc approach from our new template preprocessor approach, we mention that the ad-hoc generation of \LaTeX{} from pure Python programs is widespread. In 2019, we switched from an ad-hoc approach to PythonTex and it was a significant improvement, but we found three important drawbacks to the embedded Python approach, which motivated us to create \pyptex{}.

First, there is the (somewhat theoretical) security risk of allowing third-party \LaTeX{} packages to execute arbitrary Python codes unbeknownst to the user. Second, there is the issue of ``deadlock'', which is when the source and cache files enter a state where compiling \texttt{a.tex} into \texttt{a.pdf} becomes impossible because of \TeX{} errors. This occurs when the \TeX{} macro processor is simultaneously extracting new Python fragments from \texttt{a.tex} while inserting outdated cached substitutions from a previous version of \texttt{a.tex}. To break deadlock, it is usually necessary to manually delete all cache files, but this is not always sufficient, and sometimes modifying \texttt{a.tex} is necessary. Finally, the third problem is the difficulty of debugging Python fragments and generated \LaTeX{} fragments.

We have found that our new Python template preprocessor \pyptex{} avoids all three problems. First, it does not allow third-party \LaTeX{} packages to execute arbitrary Python codes because there is no bidirectional communication between \LaTeX{} and Python. Second, deadlock is impossible by design because the \LaTeX{} engine is not involved at all in the extraction, execution and substitution of Python fragments from \texttt{a.tex}. Finally, debugging with Pdb is treated as a first-class citizen and works as normal, and the collated \LaTeX{} document is made available in the human-preferred format of a pure-\LaTeX{} source file \texttt{a.pyptex}, as opposed to a ``partially digested'' \TeX{} macro stream. We have confirmed these significant improvements using our F19NB handout, which consists of 2,592 lines and 105KB of \LaTeX{} source in file \texttt{notes.tex}, including 1,256 lines of Python code.

Our paper is organized as follows. In Section 2, we give a brief tour of \pyptex{} features. In Section 3, we discuss the F19NB case study, a 71 page PDF document containing automatically generated problem sets for linear algebra students. We end with some conclusions in Section 4.

\section{A brief tour of \pyptex{} features}

The \texttt{pyptex a.tex} command executes Python fragments in \texttt{a.tex} delimited by either \verb|@@{...}| or \verb|@@{{{...}}}|; the latter notation is necessary if the Python fragment contains curly braces. If a literal \verb|@@{| is needed, it can be escaped by using a double \verb|@@@{|; apart from this, it is not necessary to escape \verb|@| symbols. \pyptex{} also honors \LaTeX{}-style comments so that \verb|%@{error}| does not execute the Python expression \verb|error|.

\pyptex{} allows one to execute arbitrary Python programs and import arbitrary Python packages, e.g. \verb|@@{from sympy import *}|. One can use SymPy to create simple plots, save them to a file and include them via the standard \LaTeX{} graphicx package. For example:
\lstinputlisting{plot1.tex}
As with all modern template preprocessors, \pyptex{} enables modular development by assembling a project from multiple component files. For example, the preceding plotting snippet was saved in the \texttt{plot1.tex}, which will later be included in our master \texttt{a.tex} via the command
\verb|@@{pyp.input('plot1.tex')}|. The files \texttt{a.tex} and \texttt{plot1.tex} are analogous to Python modules in that they execute their own separate namespaces. As such, it is necessary to re-import SymPy into the namespace of \texttt{plot1.tex}, even though it already has been imported into the namespace of the master file \texttt{a.tex}.

The pattern of plotting a figure, saving it to a file, and then including its filename into the generated \texttt{a.pyptex} file is very common, so \pyptex{} includes a convenience function \texttt{pyp.savefig()} that automatically generates distinct numbered filenames under the \texttt{a-generated/*} directory; in the present case, we create the file \texttt{a-generated/fig1.eps} with the following fragment:
\lstinputlisting{plot2.tex}
These plotting commands have also been stored in a separate file \texttt{plot2.tex}.
Note that the Python fragment in \texttt{plot2.tex} consists of two Python statements. The Python programming language distinguishes {\em expressions} that return or produce a value, and typically consist of a single line; and {\em statements} that may run multiple lines and produce no value. The multiple lines in the \texttt{plot2.tex} Python code fragments means that they are statements that produce no value. In order to print the filename \texttt{a-generated/fig1.eps} into the curly braces of the \verb|\includegraphics{...}|, it is therefore required to use the \verb|pyp.print(...)| command.

Embedding the files \texttt{plot1.tex} and \texttt{plot2.tex} via the \texttt{pyp.input(...)} mechanism described above, results in the following output:\\
\noindent @{pyp.input('plot1.tex')}
@{pyp.input('plot2.tex')}

Standard out and standard error print out to the console as usual, and are additionally logged in the \texttt{a.pyplog} file. If one wishes to print directly to the \texttt{a.pyptex} file, one should use the \texttt{pyp.print()} function.

For performance reasons, \pyptex{} caches the outputs of Python fragments in a binary file \texttt{a.pickle}. If one edits purely textual portions of \texttt{a.tex} while leaving the Python fragments untouched, the cached outputs are used and the production of \texttt{a.pyptex} is nearly instantaneous. If the Python fragments in \texttt{a.tex} are not identical to the cached fragments, or if the command-line arguments to \texttt{pyptex} have changed, or if the \texttt{pyptex} package version has changed, the cache is automatically invalidated. Furthermore, the command \verb|pyp.dep(filename)| can be used to add further dependencies that will invalidate the cache when the file \verb|filename| changes. Any auxiliary \texttt{.tex} files (and their dependencies) incorporated via \verb|pyp.input(...)| are automatically added to the list of dependencies via \verb|pyp.dep()|, but if external data files are \texttt{open()}ed and used to generate, e.g. \LaTeX{} tables, these files should manually be added to the dependencies via \verb|pyp.dep()|. The helper function \verb|pyp.open(...)| automatically calls \verb|pyp.dep(...)| before calling the builtin \verb|open(...)| function.

One can control how the \texttt{a.pyptex} file is compiled into \texttt{a.pdf} by specifying which \LaTeX{} engine to use. To completely disable all \LaTeX{} processing, do \verb|@@{pyp.latexcommand=False}| anywhere in \texttt{a.tex}. The default \texttt{latexcommand} is
\begin{lstlisting}
{latex} {pyptexfilename} &&
   (test ! -f {bibfilename} || bibtex {auxfilename})
\end{lstlisting}
The usual Python substitutions are made from the \texttt{pyp} object, e.g. \verb|pyp.latex| defaults to \verb|"@{pyp.latex}"| but this can be overridden from anywhere in \texttt{a.tex}.

\pyptex{} can be used programmatically in the Python interpreter with \texttt{import pyptex}. The module exports a \texttt{pyptex.pyptex} object; doing \\ \texttt{pyp = pyptex.pyptex('a.tex')} causes the file \texttt{a.tex} to be read in, the Python fragments are executed, and the file \texttt{a.pyptex} is written out. The compiled text \texttt{a.pyptex} is available as the string \texttt{pyp.compiled}. The function \\\texttt{pyptex.pyptexmain()} implements the standard operations of the shell command \texttt{pyptex}. Further documentation is available by doing e.g. \texttt{help(pyptex)}.

On Mac, \pyptex{} can be used with TeXShop by creating the file \\ \verb|~/Library/TeXShop/Engines/pyptex.engine| with the following contents:
\begin{lstlisting}
#!/bin/bash
pyptex $1
\end{lstlisting}
Upon restarting TeXShop, this adds the \texttt{pyptex} build option to the list of build engines.
%\lstinputlisting{~/Library/TeXShop/Engines/pyptex.engine}

\section{Case study: the F19NB handout}

At Heriot-Watt University, F19NB is a course on numerical linear algebra for undergraduate students. Topics include Gaussian elimination, classical iterations (Jacobi and SOR), GMRES and the QR iteration. All of the theory, proofs, examples and exercises are collected in a 71-page handout. Many of the numerical exercises and their solutions are automatically generated. For some problems (e.g. eigenvalue problems, where the characteristic polynomial must be obtained), it is helpful to do a little bit of symbolic calculations using SymPy. Other exercises and examples are more numerical and use numpy and matplotlib for displaying solutions.

As of this writing, there are 2,592 lines and 105KB\footnote{As usual, some \LaTeX{} lines can be very long or very short, so the size of the file in KB may be more indicative of the size of the project} in the source file \texttt{notes.tex}, of which 1,256 lines are Python scripts. However, up to 2018, the \texttt{notes.tex} file did not contain any Python code. The Python codes were stored in separate \texttt{.py} files under a \texttt{problib} directory. These problem sets were spread over 24 Python source files and 1,268 lines of Python code. The \texttt{problib} codes were executed in sequence and all the outputs collected in an automatically generated 1,211 line (78KB) \texttt{problems.tex} file. The file \texttt{problems.tex} is a pure \LaTeX{} file that contains problem questions and solutions, encapsulated in \verb|\newcommand| statements, and is then included in the main \texttt{notes.tex} file via the \verb|\input{problems.tex}| mechanism. Various problems and their solutions can then be instantiated in the \texttt{notes.tex} file by invoking the corresponding \LaTeX{} commands.

The sheer number of files and building steps caused an explosion in complexity more typical of software engineering than mathematical typesetting. Identifying which Python code generated any particular problem set was becoming increasingly challenging. On occasions, it was found that \texttt{problems.tex} was inconsistent with the \texttt{problib} Python scripts, either because the \texttt{problib} Python scripts had not been rerun, or sometimes because a Python script had accidentally been deleted. Fixing these issues was taking an increasing amount of the author's time.

\subsection{PythonTex and \texttt{notes.tex}}

In 2019, we adopted PythonTex and it was a major success. This allowed us to immediately reduce the number of external Python scripts and build steps, because many of the simpler tasks could be done directly from \texttt{notes.tex}. By the end of 2019, all Python scripts were moved to \texttt{notes.tex}, and \texttt{problib} was deleted.

Despite these major improvement, new ``software engineering-style'' problems arose. In the abstract, allowing third-party \LaTeX{} packages to execute arbitrary Python programs seems like a security problem. As of this writing, there are 7,093 potentially malicious \LaTeX{} packages on CTAN. That being said, there are 211,855 packages currently on the Python archive PyPI, and malicious Python packages are regularly identified, e.g. \citet{cimpanu2018twelve}. Ultimately, it was the deadlock and debugging problems that motivated us to create \pyptex{}.

We now list a few examples of deadlock situations, inspired from deadlocks that happened during the development of \texttt{notes.tex}. First, if some Python fragment in \texttt{notes.tex} generates the image \texttt{dog.png}, then the \LaTeX{} command \verb|\includegraphics{dog.png}| will fail on first execution because PythonTex has not yet executed the Python code that generates \texttt{dog.png}. Because the first execution of \verb|pdflatex| has failed, the Python code to generate \verb|dog.png|. Repeatedly invoking \verb|pdflatex| or \verb|pythontex|, or deleting cache and aux files, does not break the deadlock. One must modify \texttt{notes.tex} so that it does not cause an error when the file \texttt{dog.png} does not exist. Furthermore, if the filename for the \verb|includegraphics| is generated programmatically, e.g. \\ \verb|\includegraphics{\py{"dog.png"}}|, then when there is no cache, \texttt{pdflatex} is likely to fail because \verb|\py{"dog.png"}| will macro-expand to the empty string, causing an error. One can ``prime'' the cache by temporarily deleting the \verb|\includegraphics|. After reinserting the \verb|\includegraphics|, \texttt{notes.tex} will compile successfully, but deleting the cache or \texttt{dog.png} will cause a compilation failure/deadlock again.
We also found that PythonTex often tried to substitute mismatched cache outputs to various input Python fragments.
We are not entirely certain how PythonTex keeps track of matching inputs and outputs in the cache, but it seemed to us that adding or deleting a Python code fragment \verb|\py{...}| almost always resulted in deadlock and having to delete all cache files. Of course, deleting all cache files itself sometimes caused deadlock elsewhere.

Practically speaking, we found that almost any significant and even minor edit to \texttt{notes.tex} resulted in deadlock and had to be accompanied with a manual deletion of all temporary files, and further tweaks to \texttt{notes.tex} that are required by the deletion of the cache files.

We found it difficult to debug Python code fragments in \texttt{notes.tex} because PythonTex actually executes Python fragments stored in some temporary files that PythonTex aggressively deletes, not straight from \texttt{notes.tex}. Furthermore, the Python interpreter often declared incorrectly that syntax errors were located in PythonTex glue code that is inserted between extracted Python fragments. Although PythonTex attempts to reconcile line numbers between \texttt{notes.tex} and the various temporary files, we found that this simply led to more confusion and difficulties in debugging.

The generated \LaTeX{} is merged into the \TeX{} token stream from various temporary files, so there is no collated file similar to the \texttt{notes.pyptex} of \pyptex{}. It seemed to us that \TeX{} was struggling to provide informative error messages, and it was difficult to view generated \LaTeX{} fragments in context. We resorted to manually copy-and-pasting generated \LaTeX{} fragments from various temporary files into \texttt{notes.tex}.

Altogether, debugging was challenging. Issues had to be identified and isolated by searching through multiple temporary files, and then locating the corresponding source in \texttt{notes.tex}.

\subsection{The invention of \pyptex{}.}

If the motivation of upgrading from ad-hoc scripting to PythonTex was to mitigate the burgeoning software engineering challenges in our old build process, then the motivation for moving to \pyptex{} was to address the perceived drawbacks of PythonTex: deadlock issues, and ease of debugging.

Our starting point was that \TeX{} was not a good tool for the end-to-end process of extracting Python fragments from a template file, replacing them with their outputs and compiling the whole thing down into a PDF. When \TeX{} is performing the extraction task, if it is also simultaneously performing insertions from cache files, deadlock seems almost inevitable. \TeX{} must clearly be used to generate the PDF so it seemed natural to cut \TeX{} out of the beginning of the process, when the Python fragments are extracted from the \texttt{notes.tex} file. From this insight, we concluded we had to abandon the Python Embedding approach, in favor of the Python template Preprocessor approach.

We have successfully used \pyptex{} for the 2020 version of the F19NB handout
and found that \pyptex{} has the following advantages over PythonTex:
\begin{enumerate}
\item {\bf No deadlock.} \pyptex{} is always able to either generate \texttt{notes.pyptex} from \texttt{notes.tex}, regardless of any cache contents, or report genuine Python errors in the source file \texttt{notes.tex}.
\item {\bf Easy to debug Python.} When \pyptex{} does report genuine Python errors in \texttt{notes.tex}, the error messages are clear and Python debugging is done directly in the source \texttt{notes.tex} file using standard Python tools such as Pdb. There is no auxiliary file for collecting Python code fragments, and no confusion between various line numberings. There is no glue code inserted between Python fragments, and hence Python errors are always correctly reported inside user codes.
\item {\bf Easy to debug generated \LaTeX{}.} Debugging the generated \LaTeX{} code \texttt{notes.pyptex} is much easier, as it consists entirely of high-level, human-readable \LaTeX{} code, as opposed to a partially digested \TeX{} token stream that is difficult to debug for all but the most advanced \TeX{}nicians.
All \LaTeX{} error messages correspond exactly to the contents of \texttt{notes.pyptex} and its line numbers.
\item {\bf Security.} Third-party \LaTeX{} packages cannot execute arbitrary Python code on the user's machine.
\end{enumerate}
One can regard the \texttt{notes.pyptex} as an intermediate file that the user will occasionally have to inspect in order to debug generated \LaTeX{} fragments, and the experience of PythonTex is that such temporary user-facing files must be carefully thought through lest they become a source of problems. By only generating one such user-facing intermediate file, our experience with \texttt{notes.pyptex} is that we have avoided most of the problems we had tracking information across multiple temporary files in PythonTex. In addition, unlike PythonTex, our intermediate file \texttt{notes.pyptex} is designed to be used first by humans, and secondarily by the \LaTeX{} compiler. This is because \texttt{notes.pyptex} consists of high-level, human-style \LaTeX{} source commands, and not some low-level macro-expansion of the high-level \LaTeX{} source.

In addition to the user-facing file \texttt{notes.pyptex}, \pyptex{} also produces a plain-text log file \texttt{notes.pyplog}, and a cache file \texttt{notes.pickle} that is in binary format and opaque to users. In our experience, we never had to manually inspect the contents of \texttt{notes.pickle} and this file never caused deadlock or debugging problems in \pyptex{}. Furthermore, \texttt{notes.pickle} can also be deleted without breaking the build. In extremis, \texttt{notes.pickle} can theoretically be loaded and inspected using Python's pickle module, but we have never needed to do this.

Theoretically, an outdated \texttt{notes.pickle} cache could cause the a miscompilation of \texttt{notes.pyptex} and produce an incorrect \texttt{notes.pdf}, or even a \LaTeX{} compilation error. The previously-described dependency-tracking features of \pyptex{} are almost always able to detect that the cache should be invalidated, but a sufficiently determined user could defeat these safety measures. For example, if a user is reading data from a file without declaring it as a dependency, or if a user is falsifying ``last modification'' timestamps on files,
or generating random numbers, or some other form of nondeterminism is taking place, then cache invalidation may fail. A concerned user can completely disable the \texttt{notes.pickle} cache file by issuing the Python command \verb|pyp.disable_cache=True| in \texttt{notes.tex}, trading efficiency for safety.

\section{Conclusions and outlook}

We have introduced \pyptex{}, the Python template Preprocessor for \LaTeX{}. Unlike other projects that have embedded Python into \LaTeX{}, \pyptex{} uses regular expressions to extract Python fragments and substitute their outputs. Our preprocessor approach is superior to the embedded approach because it avoids the deadlock and debugging issues that plague embedded Python approaches, and it also eliminates the attack vector of arbitrary code execution by malicious third-party \LaTeX{} packages. \pyptex{} has been used to generate problem sets for the F19NB class at Heriot-Watt University. This large 71-page document features 1,256 lines of Python in a 105KB source file \texttt{notes.tex}.

\pyptex{} centers around the Python programming language, but one could extend on our idea by adding more languages to the preprocessor, e.g. the string \verb|@julia{...}| could invoke a Julia interpreter. This poses a challenging issue of how to tightly integrate any such ``guest language'', and particularly its native debugging tools, so that the user experience is best possible. The tight integration of Python's Pdb debugger, and the deliberate cache invalidation algorithm, required careful use of Python's extensive introspection and detailed code generation facilities. This is an avenue for future research.

\bibliographystyle{plainnat}

\bibliography{@{{{
pyp.bib(r"""
@article{knuth1989errors,
  title={The errors of {TeX}},
  author={Knuth, Donald E},
  journal={Software: Practice and Experience},
  volume={19},
  number={7},
  pages={607--685},
  year={1989},
  publisher={Wiley Online Library}
}
@book{knuth1984texbook,
  title={The {TEXbook}},
  author={Knuth, Donald Ervin and Bibby, Duane},
  volume={3},
  year={1984},
  publisher={Addison-Wesley Reading}
}
@book{lamport1994latex,
  title={{LATEX}: a document preparation system: user's guide and reference manual},
  author={Lamport, Leslie},
  year={1994},
  publisher={Addison-wesley}
}
@article{greenwade1993comprehensive,
  title={The comprehensive {TEX} archive network (ctan)},
  author={Greenwade, George D},
  journal={TUGBoat},
  volume={14},
  number={3},
  pages={342--351},
  year={1993},
  publisher={Addison-Wesley}
}
@article{seindal1997gnu,
  title={{GNU} m4, version 1.4},
  author={Seindal, Ren{\'e}},
  journal={Free Software Foundation},
  volume={59},
  year={1997}
}
@article{virtanen2020scipy,
  title={{SciPy} 1.0: fundamental algorithms for scientific computing in {P}ython},
  author={Virtanen, Pauli and Gommers, Ralf and Oliphant, Travis E and Haberland, Matt and Reddy, Tyler and Cournapeau, David and Burovski, Evgeni and Peterson, Pearu and Weckesser, Warren and Bright, Jonathan and others},
  journal={Nature Methods},
  pages={1--12},
  year={2020},
  publisher={Nature Publishing Group}
}
@article{meurer2017sympy,
  title={{SymPy}: symbolic computing in {Python}},
  author={Meurer, Aaron and Smith, Christopher P and Paprocki, Mateusz and {\v{C}}ert{\'\i}k, Ond{\v{r}}ej and Kirpichev, Sergey B and Rocklin, Matthew and Kumar, AMiT and Ivanov, Sergiu and Moore, Jason K and Singh, Sartaj and others},
  journal={{PeerJ} Computer Science},
  volume={3},
  pages={e103},
  year={2017},
  publisher={PeerJ Inc.}
}
@article{poore2015pythontex,
  title={{PythonTeX: reproducible documents with LaTeX, Python, and more}},
  author={Poore, Geoffrey M},
  journal={Computational Science \& Discovery},
  volume={8},
  number={1},
  pages={014010},
  year={2015},
  publisher={IOP Publishing}
}
@article{fine2005tex,
  title={{TEX} forever!},
  author={Fine, Jonathan},
  journal={Proceedings EuroTEX},
  pages={140--149},
  year={2005}
}
@misc{Loisel2020,
  author        = {S{\'e}bastien Loisel},
  title         = {Numerical Analysis {B} (lecture notes)},
  year          = {2020},
  publisher={Heriot-Watt University}
}
@book{kernighan1977m4,
  title={The {M4} macro processor},
  author={Kernighan, Brian W and Ritchie, Dennis M},
  year={1977},
  publisher={Bell Laboratories Murray Hill, NJ}
}
@article{cimpanu2018twelve,
  title={Twelve Malicious {P}ython Libraries Found and Removed from {PyPI}},
  author={Cimpanu, Catalin},
  year={2018},
  journal={ZDNet},
  month={October},
}
@article{pakin2004perltex,
  title={PerlTEX: Defining LATEX macros using Perl},
  author={Pakin, Scott},
  journal={TUGboat},
  volume={25},
  number={2},
  pages={150--159},
  year={2004}
}
@misc{ehmsen,
title={Python.sty},
author={Martin R. Ehmsen},
publisher={CTAN},
year={2012},
}
@misc{drake2009sagetex,
  title={The {SageTEX} package},
  author={Drake, Dan and others},
  publisher={CTAN},
  year={2009}
}
@book{molteno2014sympytex,
  title={SympyTeX: Embedding Symbolic Computation Into {LaTeX} Documents},
  author={Molteno, Timothy Christopher Anthony},
  year={2014},
  publisher={Electronics Group, University of Otago}
}
@article{hagen2005luatex,
  title={{LuaTEX}: Howling to the moon},
  author={Hagen, Hans},
  journal={The Communications of the TEX Users Group},
  pages={152},
  year={2005}
}
@article{hepple1998,
title={Writing {HTML} with m4},
author={Bob Hepple},
journal={Linux journal},
year={1998},
month={March},
}
@article{ronacher2008jinja2,
  title={Jinja2 Documentation},
  author={Ronacher, Armin},
  journal={Welcome to Jinja2—Jinja2 Documentation (2.8-dev)},
  year={2008}
}
@book{alchin2013pro,
  title={Pro Django},
  author={Alchin, Marty and Kaplan-Moss, Jacob and Vilches, George},
  year={2013},
  publisher={Springer}
}
""")
}}}}
\end{document}


\chapter{Psychophysiological Interactions (PPI)}

\section{Theoretical background}

Psychophysiologic interactions (PPI) model the response in one cortical area as the influence of another region and its interaction with an experimental treatment (sensory stimulus, task, etc.) \cite{ppi}. This technique is one way of examining effective connectivity, or the influence that one neural system exerts on another \cite{func1}. Mechanistically, a PPI analysis involves the following steps.
\begin{enumerate}
\item Performing a standard GLM analysis.
\item Extracting BOLD signal from a source region identified in the GLM analysis.
\item Forming the interaction term (source signal x experimental treatment)
\item Performing a second GLM analysis that includes the interaction term, the source region's extracted signal and the experimental vector in the design. The inclusion of the source region's signal and the experimental vector is analogous to including the main effects in an ANOVA in order to make an inference on the interaction.
\end{enumerate}

Forming the proper interaction term turns out to be a challenge because of the unique characteristics of fMRI (BOLD) data in which the underlying neural signal is convolved with a hemodynamic response function. However, interactions in the brain take place at the neural and not the hemodynamic level. Therefore, appropriate models of the interactions require the neural signal, which is not measured directly, but instead must be derived by deconvolving the HRF. The PPI software (\texttt{spm\_peb\_ppi.m}) was developed in order to provide robust deconvolution of the HRF and the proper derivation of the interaction term \cite{gitelman_03}.

\section{Practical example}

The dataset in this exercise is from one subject who was studied in the \cite{buchel1998} report and refers to the ``attention to motion'' dataset available from the SPM website\footnote{\url{http://www.fil.ion.ucl.ac.uk/spm/data/attention/}}. It has already been described in the previous chapter for DCM.

The goal is to use PPI to examine the change effective connectivity between V2 and V5 while the subject observes visual motion (radially moving dots) under the experimental treatments of attending vs. not attending to the speed of the dots. The psychophysiologic interaction can be conceived of as looking for a significant difference in the regression slopes of V1 vs. V5 activity under the influence of the different attentional states \cite{ppi}.

\subsection{GLM analysis - Design setup and estimation}

This dataset has already been preprocessed (coregistered, normalised and smoothed) using an earlier version of SPM.

\begin{enumerate}
\item The analysis directory should include
\begin{enumerate}
\item A directory named \texttt{functional}, which includes the preprocessed fMRI volumes.
\item A directory named \texttt{structural}, which includes a T1 structural volume
\item Files: \texttt{factors.mat}, \texttt{block\_regressors.mat}, \texttt{multi\_condition.mat} and \texttt{multi\_block\_regressors.mat}.
\item You will also need to make 2 empty directories called \texttt{GLM} and \texttt{PPI} for performing the analyses.
\end{enumerate}

\item In \matlab\ type
\begin{verbatim}
>> cd 'path-to-analysis-directory'
>> spm fmri
\end{verbatim}
\item From the Tasks menu at the top of the Graphics window select \textsc{Batch}
\item Select \textsc{New ``Stats''} from the Options box, Figure 1.1.

\begin{figure}[!ht]
\centering\epsfig{file=ppi/select-stats,width=85mm}
\caption{\em Select \textsc{New ``Stats''} from the Options box}
\label{ppi_fig1}
\end{figure}

\item Click \textsc{Stats} in the Batch box and then select \textsc{New ``Fmri model specification''}, \textsc{New ``Model Estimation''} and \textsc{``New Contrast Manager''} from the Options box, Figure 1.2.

\begin{figure}[ht]
\centering\epsfig{file=ppi/select-batch-components,width=100mm}
\caption{\em Click \textsc{Stats} in the Batch box and then select \textsc{New ``Fmri model specification''}, \textsc{New ``Model Estimation''} and \textsc{``New Contrast Manager''} from the Options box}
\label{ppi_fig2}
\end{figure}

\item Right click in the Batch box then choose \textsc{Exp/Con All > Expand All}, Figure 1.3\\\\

\begin{figure}[!ht]
\centering\epsfig{file=ppi/expand-batch-components,width=85mm}
\caption{ \em{Right click the Batch box then choose \textsc{Exp/Con All > Expand All}}}
\label{ppi_fig3}
\end{figure}

\textbf{Fill in the \textsc{Fmri model specification}} (Figure 1.4)

\begin{figure}[!ht]
\centering\epsfig{file=ppi/expanded-batch-newsubj,width=75mm}
\caption{\em Click \textsc{Data \& Design} and Choose \textsc{New "Subject/Session"}}
\label{ppi_fig4}
\end{figure}

%\begin{figure}[!ht]
%\centering\epsfig{file=ppi/expanded-batch,width=75mm}
%\caption{\em Fill in the \textsc{Fmri model specification}}
%\label{ppi_fig4}
%\end{figure}

\item Click \textsc{Directory} and choose the \texttt{GLM} directory that you made above.
\item \textsc{Units for design} [\textsc{scans}]
\item \textsc{Interscan interval} [3.22]
\item \textsc{Microtime resolution} [16]
\item \textsc{Microtime onset} [1]
\item Click \textsc{Data \& Design}, Choose \textsc{New "Subject/Session"} from the options box then right click the Batch box and expand all, Figure 1.4.
\item Click \textsc{Scans} and choose all the functional scans \texttt{snffM00587\_00xx.img}. There should be 360 \texttt{*.img} files.
\item The experimental conditions can be defined either individually or using a multiple condition \texttt{mat}-file. This exercise shows both methods for educational purposes. When doing an actual analysis you can just follow one of the two approaches below.\\\\\\
\textbf{Define conditions individually}\\
\item Load the mat file containing the individual conditions:
\begin{verbatim}
>> load factors.mat
\end{verbatim}
You can look at the loaded variables by typing the variable names.
( \texttt{stat} = stationary, \texttt{natt} = no attention, \texttt{att} = attention)
\begin{verbatim}
>> stat
>> natt
>> att
\end{verbatim}
\item Click \textsc{Conditions} under \textsc{Subject/Session} and from the Options box add 3 \textsc{``New Conditions''}, then expand all.

\item Condition 1: Name = \texttt{Stationary}, \textsc{Onsets} = \texttt{stat}, \textsc{Durations} = 10
\item Condition 2: Name = \texttt{No-attention}, \textsc{Onsets} = \texttt{natt}, \textsc{Durations} = 10
\item Condition 3: Name = \texttt{Attention}, \textsc{Onsets} = \texttt{att}, \textsc{Durations} = 10
\item Next you will enter 3 regressors to model block effects. This will account for the fact that the experiment took place over 4 runs that have been concatenated into a single session to make the PPI analysis easier. First load the regressors:
\begin{verbatim}
>> load block_regressor.mat
\end{verbatim}
\item Click \textsc{Regressors} and add 3 \textsc{New Regressors}, then expand all.
\item Regressor 1: \textsc{Name} = \texttt{Block 1}, \textsc{Value} = \texttt{block1}
\item Regressor 2: \textsc{Name} = \texttt{Block 2}, \textsc{Value} = \texttt{block2}
\item Regressor 3: \textsc{Name} = \texttt{Block 3}, \textsc{Value} = \texttt{block3}\\\\

\textbf{Define conditions using multiple condition and multiple regressor files}\\
\item If you would like to look at the organization of the variables in the multiple condition file, first load it.
\begin{verbatim}
>> load multi_condition.mat
>> names
>> onsets
>> durations
\end{verbatim}
Notice that there are three variables organized as cell arrays. The variables in a multiple condition file must always be named: 'names', 'onsets', and 'durations'
\textit{(Note: You only need to do this step if you want to look at the organization of the variables. In contrast to defining conditions individually, as shown above, when using a multiple condition file you do not have to load the file in order to enter it into the design.)}\\
\item To use the multiple conditions file in the design, click \textsc{Multiple Conditions}, then \textsc{Specify Files} in the Options box and choose the \texttt{multi\_condition.mat} file.
\item Next you will enter the 3 regressors to model block effects by using a multiple regressor file. To look at the organization of the multiple regressor variable, first load it. \textit{(Again you do not have to load the multiple regressor file in order to use it. This step is just to allow you to examine the variable.)}
\begin{verbatim}
>> load multi_block_regressor.mat
>> R
\end{verbatim}
Notice that this file contains a single variable, \texttt{R}, which has each regressor in a separate column.
\item To use the multiple regressor file, click \textsc{Multiple Regressor} then select the  \texttt{multi\_block\_regressor.mat} file\\\\

\textbf{Complete the design setup}\\
\item \textsc{High-pass filter} [192] (Note: most designs will use a high-pass filter value of 128. However, this dataset requires a longer high-pass filter in order not to lose the low frequency components of the design.)
\item \textsc{Factorial design} is not used
\item The \textsc{Basis function} is the \textsc{canonical HRF} as shown and \textsc{Model derivatives} [\textsc{No derivatives}]
\item \textsc{Model Interactions (Volterra)}: [\textsc{Do not model interactions}]
\item \textsc{Global normalisation} [\textsc{None}]
\item \textsc{Explicit mask} [\textsc{None}]
\item \textsc{Serial correlations} [\textsc{AR(1)}]
\item Under \textsc{Model estimation} click \textsc{Select \texttt{SPM.mat}} then choose \textsc{Output from ``fMRI model specification''} from the Options box.
\item Under \textsc{Contrast Manager} click \textsc{Select \texttt{SPM.mat}} then choose \textsc{Output from ``Model estimation''} from the Options box.
\item Click \textsc{Contrast Sessions} then click \textsc{New ``F-contrast''} once, and \textsc{New ``T-contrast''} twice from the Options box, and Expand all.
\item Click \textsc{F-contrast} $\rightarrow$ \textsc{Contrast vectors} and then choose \textsc{New ``F contrast vector''} 3 times from the Options box
\item Under the F-contrast the name is: \texttt{Effects of Interest}
\item The F contrast vectors are as follows.
Enter each one in turn into an F contrast vector.
\begin{verbatim}
1 0 0 0 0 0 0
0 1 0 0 0 0 0
0 0 1 0 0 0 0
\end{verbatim}
\item For the first T-contrast click \textsc{Name}, then click \textsc{Specify Text} in the Options box and enter: \texttt{Attention}.
\item Click \textsc{T contrast vector}, then \textsc{Specify Text} in the Options box and enter: \texttt{~0~-1~1~0~0~0~0} (Note the order of the conditions in the design matrix is: Stationary, NoAttMot and AttMot).
\item For the second T-contrast the name is: \texttt{Motion}. The vector is: \texttt{-2~1~1~0~0~0~0}
\item Click the \textsc{Save} button and save the batch file.\\

\textbf{Design estimation}\\
\item If everything has been entered correctly the \textsc{Run} button is no longer grayed out. Click \textsc{Run} to estimate the design.
\item The design matrix should look as shown in Figure 1.5, below.

\begin{figure}[!ht]
\centering\epsfig{file=ppi/glm-design-matrix,width=85mm}
\caption{\em Design matrix}
\label{ppi_fig5}
\end{figure}
\end{enumerate}

\subsection{GLM analysis - Results}

\begin{enumerate}
\item Click \textsc{Results} and select the \texttt{SPM.mat} file.
\item Choose the \texttt{Attention} contrast
\item Mask with other contrasts [No]
\item Title for comparison [Attention]
\item p value adjustment to control [None]
\item threshold {T or p value} [0.0001]
\item \& extent threshold {voxels} [10]
\item You should see an SPM that looks like the one shown below, Figure 1.6. Note the Superior Parietal and Dorso-Lateral Prefrontal activations, among others. By selecting \textsc{overlays} $\rightarrow$ \textsc{sections}, and selecting the normalised structural image, you should be able to identify the anatomy more accurately.

\begin{figure}[!ht]
\centering\epsfig{file=ppi/attention-contrast,width=85mm}
\caption{\em Statistical parametric map for the \texttt{Attention} contrast}
\label{ppi_fig6}
\end{figure}

\item To look at the \texttt{Motion} contrast where \texttt{Attention} is greater than \texttt{No Attention}, click \textsc{Results}, choose the \texttt{SPM.mat} file and choose the \texttt{Motion} contrast.
\item Mask with other contrasts [Yes]
\item Select contrast for masking: Choose the \texttt{Attention} contrast
\item Uncorrected mask p-value [0.01]
\item Nature of Mask: [inclusive]
\item Title for comparison: leave as the defaults, which is [Motion  (masked [incl.] by Attention at p=0.01)]
\item p value adjustment to control [FWE]
\item threshold {T or p value} [0.05]
\item \& extent threshold {voxels} [3]
\item The masked \texttt{motion} contrast on the glass brain is shown below in Figure 1.7.

\begin{figure}[!ht]
\centering\epsfig{file=ppi/motion-attnmask,width=85mm}
\caption{\em Statistical parametric map for the \texttt{Motion} contrast inclusively masked by the Attention contrast}
\label{ppi_fig7}
\end{figure}
\end{enumerate}

\section{GLM analysis - Extracting VOIs}

\begin{enumerate}
\item First select the \texttt{Motion} contrast, but do not include masking. Use a p-value adjustment of FWE with height threshold of 0.05 and a cluster threshold of 3.
\item Go to point [15 -78 -9]
\item Press \texttt{eigenvariate}
\item Name of region [V2]
\item Adjust data for [effects of interest]
\item VOI definition [sphere]
\item VOI radius(mm) [6]
\end{enumerate}
This saves the extracted VOI data in the file \texttt{VOI\_V2\_1.mat} in the working directory, and displays Figure 1.8, below. The left side shows the location on a standard brain. The right side shows the first eigenvariate of the extracted BOLD signal.

\begin{figure}[!ht]
\centering\epsfig{file=ppi/v2-eigenvariate,width=85mm}
\caption{\em First eigenvariate of the extracted BOLD signal in V2}
\label{ppi_fig8}
\end{figure}

\section{PPI analysis - Create PPI variable}
\begin{enumerate}
\item Press the \textsc{PPIs} button, and select the previous \texttt{SPM.mat} file in the \texttt{GLM} directory.
\item Analysis type ? [psychophysiologic interaction]
\item Select \texttt{VOI\_V2\_1.mat}
\item Include Fixation [No]
\item Include Stationary [No]
\item Include No-Attention [Yes], contrast weight [-1]
\item Include Attention [Yes], contrast weight [1]
\item Name of PPI [ V2x(Att-NoAtt) ]
\end{enumerate}
After a few seconds the PPI will be calculated and a graphical window will appear, see below. A file \texttt{PPI\_V2x(Att-NoAtt).mat} will be created in the current working directory. It contains the variable \texttt{PPI.ppi} (the interaction term), \texttt{PPI.Y} (the original ROI eigenvariate) and \texttt{PPI.P} (the \texttt{Attention - No Attention} task vector). You will use these vectors in setting up your psychophysiologic interaction GLM analysis. See \texttt{spm\_peb\_ppi} for a full description of the \texttt{PPI} data structure.

\begin{figure}[!ht]
\centering\epsfig{file=ppi/ppi-setup,width=85mm}
\caption{\em PPI output graphics}
\label{ppi_fig9}
\end{figure}

\subsection{PPI GLM analysis - Design setup and estimation}

\begin{enumerate}
\item Copy the file \texttt{PPI\_V2x(Att-NoAtt)} \textsc{Mat}-file to the \texttt{PPI} directory that you created at the start of this exercise.
\item Create a new directory and copy the file \texttt{PPI\_V2x(Att-NoAtt).mat} to this directory.
\item \texttt{cd} (change directory) to the new directory.
\item At the \matlab\ prompt type
\begin{verbatim}
>> load PPI_V2x(Att-NoAtt)
>> whos
\end{verbatim}
\item From the Tasks menu at the top of the Graphics window select Batch
\item Select \textsc{``New Stats''} from the Options box, then add jobs \textsc{New ``fMRI model specification''}, \textsc{New ``Model estimation''}, and \textsc{New ``Contrast Manager''}, and Expand All.
\item Directory: Choose the \texttt{PPI} directory
\item Units for design [scans]
\item Interscan interval [3.22]
\item Add a \textsc{New ``Subject/Session''} under \textsc{Data \& Design}
\item Click \textsc{Scans} and choose all the functional scans \texttt{snffM00587\_00xx.img}. There should be 360 \texttt{*.img} files.
\item Click \textsc{Regressors}, add 3 regressors and Expand All
\item Regressor 1: Name: \texttt{PPI-interaction}, Value: \texttt{PPI.ppi}
\item Regressor 2: Name: \texttt{V2-BOLD}, Value: \texttt{PPI.Y}
\item Regressor 3: Name: \texttt{Psych\_Att-NoAtt}, Value: \texttt{PPI.P}
\item High Pass Filter [192]
\item \textsc{Model estimation} $\rightarrow$ \textsc{Select \texttt{SPM.mat}} $\rightarrow$ \textsc{Output from ``fMRI model specification''}
\item \textsc{Contrast Manager} $\rightarrow$ \textsc{Select \texttt{SPM.mat}} $\rightarrow$ \textsc{Output from ``Model estimation''}
\item \textsc{Contrast Manager} $\rightarrow$ \textsc{Contrast sessions} $\rightarrow$ \textsc{New ``T-contrast''}. Double click \textsc{T-contrast} to expand.
\item T-contrast: Name: \texttt{PPI-Interaction}
\item T-contrast vector: \texttt{1 0 0 0}
\item Save the batch file.
\item Run
\end{enumerate}
The design matrix is shown below, Figure 1.10.

\begin{figure}[ht]
\centering\epsfig{file=ppi/ppi-design-matrix,width=85mm}
\caption{\em Design matrix of the PPI analysis}
\label{ppi_fig10}
\end{figure}

\subsection{PPI analysis - Results}

\begin{enumerate}
\item Press the \textsc{Results} button and select the \texttt{SPM.mat} file in the PPI directory.
\item Choose the \texttt{PPI-Interaction} contrast
\item Mask with other contrasts [No]
\item Title for comparison [PPI-Interaction]
\item p value adjustment to control [None]
\item threshold {T or p value} [0.01]
\item \& extent threshold {voxels} [10]
\item You should see an SPM that looks the same as the one shown below in the top part of Figure 1.11. The resulting SPM shows areas showing differential connectivity to V2 due to the effect of attention vs. no attention conditions. The effect in this subject is weak.
\end{enumerate}

\begin{figure}[!ht]
\centering\epsfig{file=ppi/ppi-contrast,width=100mm}
\caption{\em PPI results}
\label{ppi_fig11}
\end{figure}

\subsection{PPI analysis - Plotting}

\begin{enumerate}
\item One region showing the psychophysiologic interaction is the V5region , which is located at [39~-72~0] in this subject. Move the cursor to this point to view the area of activation, as shown below, in the bottom half of Figure 1.11.

\item In order to plot the PPI graph showing the effect of attention, you need to extract a VOI from the V5 region. To do this, you will return to the original GLM analysis.
\item Click Results, then select the GLM analysis \texttt{SPM.mat} file
\item Mask with other contrasts [No]
\item Title for comparison [Motion]
\item p value adjustment to control [None]
\item threshold {T or p value} [0.001]
\item \& extent threshold {voxels} [3]
\item Go to point [39- 72 0]
\item Press eigenvariate
\item Name of region [V5]
\item Adjust data for [effects of interest]
\item VOI definition [sphere]
\item VOI radius(mm) [6]
\item Now you will create 4 PPIs (Follow the steps under section 1.4, Create PPI Variable, above). By using the PPI software machinery to create the interaction vectors, rather than just multiplying the extracted V2 and V5 eigenvariates by the behavioral vectors, the PPI vectors will be formed properly.

\begin{enumerate}
\item \texttt{V2xNoAttention} (Use the V2 VOI and include \texttt{No-Attention} with a contrast weight of 1, do not include \texttt{Stationary}, \texttt{Attention})
\item \texttt{V2xAttention} (Use the V2 VOI and include \texttt{Attention} with a contrast weight of 1, do not include \texttt{Stationary}, \texttt{No-Attention})
\item \texttt{V5xNoAttention} (Use the V5 VOI and include \texttt{No-Attention} with a contrast weight of 1, do not include \texttt{Stationary}, \texttt{Attention})
\item \texttt{V5xAttention} (Use the V5 VOI and include \texttt{Attention} with a contrast weight of 1, do not include \texttt{Stationary}, \texttt{No-Attention})
\end{enumerate}
\item Load the PPIs you just created with the following commands at the \matlab\ prompt:
\begin{verbatim}
>> v2noatt = load('PPI_V2xNoAttention');
>> v2att   = load('PPI_V2xAttention.mat');
>> v5noatt = load('PPI_V5xNoAttention.mat');
>> v5att   = load('PPI_V5xAttention.mat');
\end{verbatim}
\item Plot the PPI datapoints with the following commands at the \matlab\ prompt:
\begin{verbatim}
>> figure
>> plot(v2noatt.PPI.ppi,v5noatt.PPI.ppi,'k.');
>> hold on
>> plot(v2att.PPI.ppi,v5att.PPI.ppi,'r.');
\end{verbatim}
\item To plot the best fit lines type the following first for \texttt{NoAttention}
\begin{verbatim}
>> x  = v2noatt.PPI.ppi(:);
>> x  = [x, ones(size(x))];
>> y  = v5noatt.PPI.ppi(:);
>> B  = x\y;
>> y1 = B(1)*x(:,1)+B(2);
>> plot(x(:,1),y1,'k-');
\end{verbatim}
\item Then for \texttt{Attention}
\begin{verbatim}
>> x = v2att.PPI.ppi(:);
>> x = [x, ones(size(x))];
>> y = v5att.PPI.ppi(:);
>> B = x\y;
>> y1 = B(1)*x(:,1)+B(2);
>> plot(x(:,1),y1,'r-');
>> legend('No Attention','Attention')
>> xlabel('V2 activity')
>> ylabel('V5 response')
>> title('Psychophysiologic Interaction')
\end{verbatim}
\end{enumerate}

\begin{figure}[!ht]
\centering\epsfig{file=ppi/ppi-plot,width=110mm}
\caption{\em }
\label{ppi_fig12}
\end{figure}


\documentclass{report}
\input{preamble}

\begin{document}

\thispagestyle{FirstPage}
\begin{center}
\textbf{\large Notes}
\end{center}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% TOPIC %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section*{Rate Independence of Absorption in $1/v$-absorbers}

The rate of absorption in a $1/v$-absorber with microscopic absorption cross section $\sigma_a$ is independent of the energy of the neutrons involved in the reaction. This should make some intuitive sense. Neutrons with greater energies are traveling faster and so will tend to collide faster. At the same time, they also have lower cross sections (higher $v$, lower $\sigma = 1/v$) and so will be less likely to be absorbed.

We can prove this independence more rigorously. We start by recalling the formula for a reaction rate, given energy dependent fluxes and cross sections. The reaction rate is the product of the macroscopic cross section of the material and the neutron flux. Since both cross section and flux can vary with energy, we must integrate over all possible energies to get a total reaction rate.

\begin{equation}
\label{reactionrate}
R = \int_0^{\infty} \Sigma_a(E) \, \phi(E) \, dE
\end{equation}

From this formula, we recall the definitions for both macroscopic cross section and flux. They are
$$ \Sigma_a(E) = N \sigma_a(E) \qquad\text{and}\qquad \phi(E) = n(E) v(E) $$
where $N$ is the number density of the absorbing material, $\sigma_a(E)$ is the microscopic absorption cross section of the material at energy $E$, $n(E)$ is the neutron number density at energy $E$, and $v(E)$ is the neutron speed given corresponding energy $E$.

For $1/v$-absorbers, we note that the absorption cross section can be described given as
\begin{equation}
\label{microXS}
\sigma_a(E) = \frac{C}{\sqrt{E}}
\end{equation}
where $C$ is some constant of proportionality. Remembering that $E = \frac{1}{2}mv^2$, we can include the $\sqrt{\frac{m}{2}}$ factor in the constant $C$, and it becomes clear that indeed, $\sigma_a(E) \propto 1/v$. Now, we know that the $1/v$ behavior is dominant for low velocities and energies. In this case, let's write our constant $C$ in terms of one specific energy and the corresponding microscopic cross section. The choice of energy $E_0$ is arbitrary and so we will leave our formula in terms of the variable $E_0$ (frequently $E_0$ is chosen to be the thermal energy, $E_0 = 0.0253\text{ eV}$). In this case, we find
$$ \sigma_a(E_0) = \frac{C}{\sqrt{E_0}} $$
or
$$ C = \sigma_a(E_0)\sqrt{E_0} $$
Using this to replace $C$ in equation (\ref{microXS}),
$$ \sigma_a(E) = \sigma_a(E_0)\sqrt{\frac{E_0}{E}} $$
Now that we have eliminated $C$, we can write this equation in terms of neutron speeds. If $E = \frac{1}{2}mv^2$ (and accordingly, $E_0 = \frac{1}{2}mv_0^2$), then
\begin{align*}
\sigma_a(E)	&= \sigma_a(E_0)\sqrt{\frac{\frac{1}{2}mv_0^2}{\frac{1}{2}mv^2}} \\
			&= \sigma_a(E_0)\sqrt{\frac{v_0^2}{v^2}} \\
			&= \sigma_a(E_0)\frac{v_0}{v}
\end{align*}
Explicitly noting the energy dependence of this velocity, the macroscopic cross section is
$$ \Sigma_a(E) = N \sigma_a(E_0)\frac{v_0}{v(E)} $$
We now return to our original equation for the reaction rate, equation (\ref{reactionrate}) and substitute in our explicit formulas for macroscopic cross section and flux.

$$ R = \int_0^{\infty} N \sigma_a(E_0)\frac{v_0}{v(E)} \, n(E) v(E) \, dE $$

In this equation, $N$, $\sigma_a(E_0)$, and $v_0$ are constants and can be brought outside of the integral, and the two instances of $v(E)$ cancel.

$$ R = N \sigma_a(E_0) v_0 \int_0^{\infty} n(E) \, dE $$

The integral of all number densities for all energies is just the total number of neutrons in the system, $n_0$.
$$ n_0 = \int_0^{\infty} n(E) \, dE .$$
This formula can be put back in terms of macroscopic cross section and flux, both now constants ($\Sigma_a(E_0) = N \sigma_a(E_0)$ and $\phi_0 = v_0 n_0$).
\begin{align*}
R	&= N \sigma_a(E_0) v_0 n_0 \\
	&= \Sigma_a(E_0) \phi_0 \\
\end{align*}
This formula is clearly independent of energy, and suggests that the reaction rate will be constant regardless of the chosen energy. Perhaps more surprisingly, for $1/v$-absorbers the reaction rate is the same whether the neutrons are all at one energy or covering a range of energies. Any increase in the neutron flux is compensated for exactly by a decrease in cross section, and vice-versa.

\newpage
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% TOPIC %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section*{The Maxwell-Boltzmann Distribution for Neutrons}

The fundamental assumption behind the Maxwell-Boltzmann (MB) distribution is that particles behave like an ideal gas; specifically
\begin{itemize}
\item interactions are classical (collisions are instantaneous and elastic)
\item the surrounding environment is thermal
\end{itemize}
While this might seem like a stretch given the various other processes we have discussed (fission, radiative capture, and inelastic scattering) the distribution still does a reasonable job approximating the thermal neutron energy distribution in reactors. Remember that reactors have significant quantities of moderator and so neutron-moderator collisions are generally elastic; if our reactor was pure uranium, this model would be far less effective.

Still, we are making some big assumptions, so let's be very explicit. Modeling the thermal distribution of neutrons with the MB distribution assumes
\begin{enumerate}
\item no absorption
\item no leakage
\item no sources
\end{enumerate}
\-\\
Now, we can look at the distribution itself. We won't derive it here, but using statistical physics it can be shown that
$$ M(v) = 4 \pi v^2 \left(\frac{m}{2 \pi k_B T} \right)^{3/2} e^{\frac{-m v^2}{2 k_B T}} ,$$
or equivalently (as a distribution for energies)
$$ M(E) = 2\sqrt{\frac{E}{\pi}}\left(\frac{1}{kT}\right)^{3/2} e^{-\frac{E}{kT}} .$$
\begin{figure}[h]
\begin{multicols}{2}\begin{enumerate}[(a)]
\item \includegraphics[width=8cm]{mb-dist_v.png}
\item \includegraphics[width=8cm]{mb-dist_E.png}
\end{enumerate}\end{multicols}
\caption{(a) The MB distribution as a function of velocity, compared to (b) the distribution as a function of energy.}
\end{figure}

\end{document}


\documentclass{article}
\usepackage{graphicx}
\usepackage{marvosym}
\usepackage{dingbat}

\title{The MergeSort algorithm}
\date{}

\begin{document}

\maketitle
Mergesort is a divide and conquer algorithm for sorting the element of
an array. It can be implemented as a recursive procedure where the
input array is split in two halves, mergesort is recursively called
separately on each half and then the results of the two recursive calls
are combined together to build the final sorted array.

\vspace{0.5cm}

\begin{minipage}{1.0\linewidth}
  \centering
  \includegraphics[width=0.8\textwidth]{msort}
\end{minipage}

The objective of this exercise is to parallelize the mergesort
algorithm using OpenMP.

\section{Package content}
The \texttt{MergeSort} directory contains a single file named
\texttt{mergesort.c}. This file contains a main program that allocates
an array, fills it with random numbers and then sorts it using the
mergesort algorithm. The mergesort algorithm is implemented through
the two routines \texttt{mergesort} and \texttt{merge}; only the first
one has to be modified to parallelize the algorithm.

The code can be compiled using the \texttt{make} command: simply type
\texttt{make} inside the \texttt{MergeSort} directory. This will
generate an executable \texttt{main} file that can be launched like
this
\begin{verbatim}
$ ./main n
\end{verbatim}
where \texttt{n} is the size of the array to be sorted. When executed,
the program will print the mergesort execution time or an error
message in case the result is not correct.

\section{Assignment}
\begin{itemize}
\item {\huge \Keyboard} parallelize the \texttt{mergesort} routine
  using the \texttt{\#pragma omp task} construct. Compile and run the
  \texttt{main} program using 1, 2 and 4 threads to verify that the
  proposed parallelization is correct.
\item \smallpencil Evaluate the performance for a large value of
  \texttt{n} (up to 10M) of the parallelization
  using 1, 2 and 4 threads. Report the measured eecution times in the
  \texttt{responses.txt} file.
\end{itemize}

\section{Advice}
\begin{itemize}
\item Note that creating and handling tasks has a cost. It may be wise
  to limit the generation of tasks once a sufficient amount of
  parallelism has been reached.
\end{itemize}

\end{document}

%%% Local Variables:
%%% mode: latex
%%% TeX-master: t
%%% End:


\newcommand*{\perm}[1][-3mu]{\permcomb[#1]{P}}
\newcommand*{\permcomb}[4][0mu]{{{}^{#3}\mkern#1#2_{#4}}}

\begin{document}
	\chapter{Permutations and Combinations}
	\section{Permutations}
	Consider $n$ objects from which $r$ are to be arranged in a particular order, where $r \leq n$. The number of \textit{permutations} of which $r$ objects from a total of $n$ refers to the number of ways in which these $r$ objects can be arranged, where the order of arrangement matters.\\

	Let us consider $3$ letters \{A, B, C\}. There are $6$ possible arrangements, or \textit{permutations}, of these letters, namely:
	\begin{center}
		\set{\set{A,B,C}, \set{A,C,B}, \set{B,A,C}, \set{B,C,A}, \set{C,B,A}, \set{C,A,B}}
	\end{center}
	In general, the number of permutations of $r$ objects from a total of $n$ is denoted by $\perm n r$ defined as \[\perm n r = \dfrac{n!}{(n-r)!}\]

	\begin{example}
		Consider the set of letters $\set{A,B,C,D,E}$.

		\quad\textbf{(a)}How many of these arrangements start with a vowel?
	\end{example}

	\begin{example}
		Consider the set of numbers $\set{1,2,3,4,5,6}$.

		\quad\textbf{(a)} In how many ways can a $4$ digit number be formed from the above set?

		\quad\textbf{(b)} How many of these numbers are even?

		\quad\textbf{(c)} How many of these numbers are greater than 3000?
	\end{example}

	\begin{example}
		Consider the set of numbers $\set{1,2,3,4,5,0}$.

		\quad\textbf{(a)} How many $3$ digit numbers can be formed?

		\quad\textbf{(b)} How many of these numbers are even?

		\quad\textbf{(c)} How many of these numbers are greater than $400$?

		\quad\textbf{(d)} How many even numbers can be formed?
	\end{example}

	\subsection{Permutations with Identical Objects}
	The above method, however, does not suffice in the case that we have identical objects. Suppose we have the set $\set{S,E_1,E_2}$. For every time $t$ the repeated element is present in the given set, we have to divide the total we have to divide by $t!$
	\begin{example}
		In how many ways can the letters of the word `MALTA' be arranged?
	\end{example}

	\begin{example}
		In how many ways can the letters of the word `ILLUSTRATIONS' be arranged?
	\end{example}
	Since the letters $\set{I,L,S,T}$ are repeated twice, the total possibilities have to be divided by the factorial of the number of each recurring letter. (\textit{i.e., divide by $2!$ for the two `I's, by $2!$ for the two `L's ...})

	\subsection{Circular Permutations}
	In a particular field of mathematics referred to as group theory, a cyclic permutation is a permutation of the elements of some set $X$ which maps the elements of some subset $S$ of $X$ to each other in a cyclic fashion, while fixing all other elements of $X$. In other words, this is the number of ways in which a set can be permuted whilst omitting identical cycles.
	\begin{example}
		In how many ways can 6 people be seated at a round table?
	\end{example}

	\begin{example}
		In how many ways can 4 couples be arranged around a table?

		\quad\textbf{(a)} In  how many of these arrangements are all the males separated? (\textit{i.e., no male sits next to another})
	\end{example}
	\begin{example}
		In how many ways can 4 couples be seated such that every one person sits next to their partner?
	\end{example}

	\section{Combinations}
 A combination is defined as one of the selections of $r$ objects from a total of $n$, where order does not matter. The number of total combinations is denoted by $\permcomb{C}{n}{r}$, where \[\permcomb{C}{n}{r} = \frac{n!}{(n-r)!\,r!}\]
	\begin{example}
		In how many ways can a committe of 8 people be chosen from a group of 17 candidates?
	\end{example}
	\[\permcomb{C}{17}{8} = 24310 \text{ selections}\]

	\begin{example}
		In how many ways can a team of 5 players be chosen from a group of 15 students?

		\quad\textbf{b)} In how many ways can the selection if the eldest student is to be selected?

		\quad\textbf{c)} In how many ways can the selection if the twins in the group must not be seperated?
	\end{example}

	\begin{example}
		In how many ways can 16 people be divided into 2 groups of

		\quad\textbf{a)} 9 people and 7 people respectively?

		\quad\textbf{b)} 8 people each?
	\end{example}

	\begin{example}
		In how many ways can 18 people be divided into 3 groups of 6 people each.
	\end{example}

	\section{Further Permutations and Combinations}

	\begin{example}
	Find the number of permutations of the word `ACQUAPANNA'. How many of these arrangements

		\quad\textbf{a)}	haveo the letters `\textbf{A}' appear adjacent?

		\quad\textbf{b)}	have the letters `\textbf{A}' appear seperated?

		\quad\textbf{c)}	have the letters `\textbf{CQ}' appear adjacent?

		\quad\textbf{d)}	have the letters `\textbf{CQ}' appear seperated?
	\end{example}
	\begin{example}
							Find the number of permutations of the word `ELECTRICITY`. How many of these arrangements

		\quad\textbf{a)}	have adjacent `\textbf{E}'s?

		\quad\textbf{b)}	\textbf{start} and \textbf{finish} with the same letter?

		\quad\textbf{c)}	have the word `\textbf{CITY}' appear in them?

		\quad\textbf{d)}	have the letters `\textbf{CITY}' together?
\end{example}

\section{Distribution of Objects}

\begin{example}
		Grandma has 10 identical 1 euro coins to distribute among her 3 grandchildren. In how many eays can she distribute the coins?

		\quad \textbf{a)} In how many of these possibilities is the oldest grandchild the only one to end up with no coin at all?
\end{example}

This problem can be simplified to the number of ways these 12 symbols (€ or |) to 1

\begin{example}
Twelve identical sweets are to be distributed to 4 children such that all children recieve at least one sweet. In how many ways can this be done?
\end{example}
\end{document}


\documentclass[letter]{article}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{ifthen}
\usepackage{fancyhdr}
\usepackage[usenames,dvipsnames,svgnames,table]{xcolor}
\usepackage{tikz}

%%%
% Set up the margins to use a fairly large area of the page
%%%
\oddsidemargin=.2in
\evensidemargin=.2in
\textwidth=6in
\topmargin=0in
\textheight=9.0in
\parskip=.07in
\parindent=0in
\pagestyle{fancy}

\expandafter\def\expandafter\quote\expandafter{\quote\sf\color{DarkGreen}}

%%%
% Set up the header
%%%
\newcommand{\setheader}[6]{
  \lhead{{\sc #1}\\{\sc #2} %({\small \it \today})
  }
  \rhead{
    {\bf #3}
    \ifthenelse{\equal{#4}{}}{}{(#4)}\\
    {\bf #5}
    \ifthenelse{\equal{#6}{}}{}{(#6)}%
  }
}

%%%
% Set up some shortcut commands
%%%
\newcommand{\R}{\mathbb{R}}
\newcommand{\N}{\mathbb{N}}
\newcommand{\Z}{\mathbb{Z}}
\newcommand{\Proj}{\mathrm{proj}}
\newcommand{\Perp}{\mathrm{perp}}
\newcommand{\Span}{\mathrm{span}}
\newcommand{\Null}{\mathrm{null}}
\newcommand{\Rank}{\mathrm{rank}}
\newcommand{\mat}[1]{\begin{bmatrix}#1\end{bmatrix}}

%%%
% This is where the body of the document goes
%%%
\begin{document}
  \setheader{Math 211 (A01)}{Typed Homework 1}{Bill Xiong, Arlene Zhang}{}{}{V00737042, V00802761}

\section{Question 1}
    Let $\vec u=\mat{1\\2\\3}$, $\vec v=\mat{4\\5\\6}$, and $\vec w=\mat{7\\8\\9}$. Explain whether
          the set $A=\{\vec u,\vec v,\vec w\}$ is a basis for $\R^3$.
      Make sure to include all relevant definitions.

\subsection{Solution for Question 1}

    A \emph{basis} for a subspace $V\subset \R^3$ is a linearly independent set of vectors $A$ such that $\Span\, A=V$.

    First, let's check whether $a$ is a linearly independent set.
    A set is considered \emph{linearly independent} if the only way to express it as a linear combination of vectors is trivial. (ie, the combination where all coefficients are $0$).

    Does \[\mat{0\\0\\0}=c_1\mat{1\\2\\3}+c_2\mat{4\\5\\6}+c_3\mat{7\\8\\9}\]
    have a nontrivial solution? We can rewrite the equation above as:
        \begin{align*}
          0&=c_1+4c_2+7c_3\\
          0&=2c_1+5c_2+8c_3\\
          0&=3c_1+6c_2+9c_3.
        \end{align*}
        \\
  By solving this system, we can conclude that any $c$'s satisfying the condition $c_2=-2c_3=-2c_1$ will lead to a valid solution.
  If we arbitrarily chose the value of $1$ for $c_1$, we can plug in and find that $c_2 = -2$ and $c_3 = 1$ give a solution to the above system.
  Since $c_1$, $c_2$, and $c_3 \neq 0$, $\vec 0=\vec u-2\vec v+\vec w$ is a solution.

Since $\vec 0$ can be written as a non-trivial linear combination of vectors in $A$, $A$ is a linearly dependent set, and therefore cannot be a basis for $R^3$.

\section{Question 2}

Fix $\vec u,\vec v\in \R^n$.  Show that $\Span(\Span\{\vec u,\vec v\})=\Span\{\vec u,\vec v\}$.
      Make sure to include all relevant definitions.

\subsection{Solution for Question 2}

    The \emph{span} of a set of vectors $X$ is defined as set of all linear combinations of vectors in $X$.

    We want to show that for any two vectors $\vec u,\vec v\in \R^n$,
        $\Span(\Span\{\vec u,\vec v\})=\Span\{\vec u,\vec v\}$. To do this, we show that $\Span(\Span\{\vec u,\vec v\})$ and $\Span\{\vec u,\vec v\}$ are subsets of each other.

    $\Leftarrow$:\\
    Let $\vec u,\vec v$ be some arbitrary vectors in $\R^n$ and $A=\Span\{\vec u,\vec v\}$.

  $A=\{\vec x\in\R^n:\vec x=m\vec u+n\vec v$ for some $m,n\in \R\}$.

    If we also let $\vec w$ be some arbitrary vector in $\Span\,A$, then by definition
    $\vec w=\sum_{i=1}^n k_i\vec s_i$. for some $s_i \in \vec A$ and some value $k \in \R$.

    By the definition of $A$, we can expand the above into:

    \[
        \vec w =\sum_{i=1}^n k_i (m_i\vec u+n_i\vec v)=
        (\sum_{i=1}^n k_i m_i)\vec u+
        (\sum_{i=1}^n k_i n_i)\vec v
    \]
        for some $m_i,n_i,k_i\in \R$.

        This shows that $\vec w$ is a linear combination of $\vec u$ and $\vec v$, and thus $\vec w \in A$
        and thus $\Span\, A\subseteq A$.

    $\Rightarrow$:\\
    By definition, $A$ is a subset of $\Span\,A$.

    $\therefore A=\Span\,A$.

\section{Question 3}

The worksheets define $\Proj_{\vec v}\vec u$ as the vector in the direction $\vec v$ such that
      $\vec u-\Proj_{\vec v}\vec u$ is orthogonal to $\vec v$.  Call this definition (a).  Your textbook
      defined $\Proj_{\vec v}\vec u$ as the vector $\frac{\vec u\cdot \vec v}{\vec v\cdot\vec v}\vec v$.
      Call this definition (b).  Show that definitions (a) and (b) are equivalent by showing
      that that the vector arising from definition (b) must be the same as the vector
      arising from definition (a).
      In your answer, elaborate on definition (a) by including
      the definition of \emph{vector in the direction of $\vec v$} and \emph{orthogonal}.

\subsection{Solution for Question 3}
    We'll assume that $\vec v \neq 0$ because otherwise it would break definition (b). \footnote{I'm also a computer scientist, and in my profession, dividing by zeros usually throws syntax errors.}

    Remember that a vector $\vec u$ is in the direction of a vector $\vec v$ if $\vec u=k\vec v$ for some nonzero $k \in \R$.
    Also, two vectors $\vec u, \vec v$ are considered \emph{orthogonal} if $\vec u \cdot \vec v = 0$.

   Let's take a further look at the two definitions:

    By Definition (a), $(\vec u-\Proj_{\vec v}\vec u) \cdot \vec v = 0$. We know that $\Proj_{\vec v}\vec u = \frac{\vec u\cdot \vec v}{\vec v\cdot\vec v}\vec v$ from definition (b). Let's substitute it into the equation.
   \[
        (\vec u-\frac{\vec u\cdot \vec v}{\vec v\cdot\vec v}\vec v) \cdot \vec v = 0
    \]
    \[
        \vec u \cdot \vec v - \frac{\vec u\cdot \vec v}{\vec v\cdot\vec v}\vec v \cdot \vec v = 0
    \]

    Since for any vectors $\vec u, \vec v$, $\vec u \cdot \vec v$ is a scalar. Furthermore, for any vector $\vec v$, $\vec v \cdot \vec v \neq 0$ because a vector cannot be perpendicular to itself.
    Thus, in the equations above, $\vec v \cdot \vec v$ is a non-zero scalar, and we can happily cancel.

    \[
        \vec u \cdot \vec v - \frac{\vec u\cdot \vec v}{\vec v\cdot\vec v}\vec v \cdot \vec v = \vec u \cdot \vec v - \vec u \cdot \vec v = 0
    \]

    This means that $(\vec u-\Proj_{\vec v}\vec u) \cdot \vec v$ is orthoganal to $\vec v$.
\section{Addendum}
  This is the first time one of us is submitting an assignment in \LaTeX{}. Please be gentle in grading our assignment and excuse the obvious poor formatting. Many thanks to the people in the assistance centre, who provided invaluable help for questions 2 and 3.
\end{document}