\input{../../_common/preamble}

\title{Probability theory and statistics}

\begin{document}

\maketitle

\begin{frame}{Contents}
    \tableofcontents[hideallsubsections]
\end{frame}

\section{Probability theory}

\begin{frame}{`Random' points}
    \begin{center}
        \includegraphics[width=\textwidth]{figures/random_points}
    \end{center}
\end{frame}

\begin{frame}{What is probability?}
    \begin{quote}
        `The extent to which something is likely to happen'
        \begin{flushright}
            \small%
            --- Oxford English Dictionary
        \end{flushright}
    \end{quote}
    \vfill
    \begin{block}{Examples}
        \begin{itemize}
            \item Probability that it will rain tomorrow
            \item Probability that you will win the lottery
        \end{itemize}
    \end{block}
\end{frame}

\begin{frame}{Sources of uncertainty}
    \begin{columns}[t]
        \begin{column}{0.5\textwidth}
            \begin{center}
                \includegraphics[height=2cm]{figures/rain} \\[\medskipamount]
                \alert{Imperfect information}
            \end{center}
            Current predictive tools can only assign a number indicating our
            degree of certainty
        \end{column}
        \begin{column}{0.5\textwidth}
            \begin{center}
                \includegraphics[height=2cm]{figures/lottery} \\[\medskipamount]
                \alert{Stochastic process}
            \end{center}
            The experiment is designed to produce uncertain results (because
            it's fun)
        \end{column}
    \end{columns}
\end{frame}

\begin{frame}{Probability theory}
    \begin{block}{What?}
        The branch of mathematics concerned with \alert{random phenomena}
    \end{block}
    \vfill\pause
    \begin{block}{How?}
        Using mathematical \alert{abstractions} of non\hyp{}deterministic events
    \end{block}
    \vfill\pause
    \begin{block}{Why?}
        To identify \alert{patterns} in (apparently) random occurrences
    \end{block}
\end{frame}

\begin{frame}{Statistical regularity}
    \only<1>{%
        \begin{center}
            {\LARGE%
             We cannot predict with certainty \\ if it's going to rain tomorrow}
            \vfill
            {\large%
             but}
            \vfill
            {\LARGE%
             we can predict `average behaviour'}
        \end{center}}
    \only<2>{%
        In summary\ldots
        \begin{itemize}
            \item Probability theory describes the behaviour of random phenomena
                  \alert{in the long run}
            \item If this information is useful, probability theory can be a
                  valuable tool for \alert{decision-making}
        \end{itemize}}
\end{frame}

\begin{frame}[t]{Random variables `encapsulate' random events}
    \begin{block}{Notation}
        \begin{itemize}
            \item $X$, $Y$, \ldots~(upper case) are \alert{random variables}
            \item $X = x$ (lower case) is a value (\alert{realisation}) of $X$
            \item $\Prob{X = x}$ is the \alert{probability} that $X = x$
        \end{itemize}
    \end{block}
    \vfill
    \begin{block}{Example}
        \begin{itemize}
            \item $X$ represents the (`archetypal') outcome of a coin toss
            \item $X = \text{`head'}$ represents one (actual) outcome
            \item $\Prob{X = \text{`head'}}$ is the long\hyp{}term probability
                  of the outcome `head'
        \end{itemize}
    \end{block}
\end{frame}

\begin{frame}{Maximum of two fair dice}
    \begin{columns}[t]
        \begin{column}{0.5\textwidth}
            \centering
            \textbf{A fair die} \\[\bigskipamount]
            \begin{tabular}{cc}
                \toprule
                $x$ & $\Prob{X = x}$ \\
                \midrule
                $1$ & $1/6$ \\
                $2$ & $1/6$ \\
                $3$ & $1/6$ \\
                $4$ & $1/6$ \\
                $5$ & $1/6$ \\
                $6$ & $1/6$ \\
                \bottomrule
            \end{tabular}
        \end{column}
        \begin{column}{0.5\textwidth}
            \centering
            \textbf{Maximum of two fair dice} \\[\bigskipamount]
            \begin{itemize}
                \item How many outcomes?
                \item $\Prob{X = 1}$?
                \item $\Prob{X = 6}$?
            \end{itemize}
        \end{column}
    \end{columns}
\end{frame}

\begin{frame}{Probability distributions}
    \begin{center}
        \large%
        \textbf{Simplified approximations to reality}
    \end{center}
    \vfill
    \begin{itemize}
        \item Detailed enough to capture important characteristics and serve as
              \alert{prediction tools}
        \item Simple enough to be usable in practice
    \end{itemize}
\end{frame}

\begin{frame}{Characterising probability distributions}
    \begin{block}{Measures of central tendency}
        \begin{itemize}
            \item (Arithmetic) mean or average
            \item Median
            \item Mode
        \end{itemize}
    \end{block}
    \vfill\pause
    \begin{block}{Measures of dispersion}
        \begin{itemize}
            \item Variance
            \item Minimum and maximum $\rightarrow$ range
            \item Quantiles (a.k.a.\ order statistics)
        \end{itemize}
    \end{block}
\end{frame}

\begin{frame}{Characterising probability distributions}
    \begin{center}
        \large%
        1, 8, 16, 30, 32, 37, 53, 80, 86, 91, 93
    \end{center}
    \vfill
    \begin{itemize}
        \item Mean?
        \item Median?
        \item Mode?
        \item Variance and standard deviation?
        \item Minimum and maximum, and range?
        \item Quartiles?
    \end{itemize}
\end{frame}

\section{Statistics}

\begin{frame}{Statistics}
    \begin{block}{What?}
        The science of collecting and analysing numerical data
    \end{block}
    \vfill\pause
    \begin{block}{How?}
        By planning studies, exploring and modelling the data using the tools of
        \alert{probability theory}
    \end{block}
    \vfill\pause
    \begin{block}{Why?}
        To infer properties of a \alert{population} from a \alert{sample}
    \end{block}
\end{frame}

\begin{frame}[t]{Probability or statistics?}
    You have a fair coin. You toss it 100 times. \\
    How likely is it to land heads 60 times or more?
    \vfill\pause
    \begin{center}
        \large%
        \textbf{Probability}
    \end{center}
    \begin{itemize}
        \item Random process is known (or assumed): `fair coin'
        \item Objective: \alert{find probability of a certain outcome}
    \end{itemize}
\end{frame}

\begin{frame}[t]{Probability or statistics?}
    I give you a coin. You toss it 100 times and count 60 heads. \\
    Is the coin fair?
    \vfill\pause
    \begin{center}
        \large%
        \textbf{Statistics}
    \end{center}
    \begin{itemize}
        \item Outcome is known (or measured): `$60 / 100$ heads'
        \item Objective: \alert{characterise the random process}
    \end{itemize}
\end{frame}

\begin{frame}{Probability theory and statistics}
    \begin{columns}[t]
        \begin{column}{0.5\textwidth}
            \begin{center}
                \textbf{Probability theory}
            \end{center}
            \begin{itemize}
                \item Defines the model
                \item \ldots and often its \alert{parameters}
            \end{itemize}
        \end{column}
        \begin{column}{0.5\textwidth}
            \begin{center}
                \textbf{Statistics}
            \end{center}
            \begin{itemize}
                \item Collects the data
                \item `Fits' the model \\ (estimates its parameters)
                \item Makes \alert{inferences}
            \end{itemize}
        \end{column}
    \end{columns}
\end{frame}

\end{document}


\documentclass{article}

\usepackage{hyperref}
\usepackage{cite}
\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage[ruled]{algorithm2e}
\usepackage[margin=1in]{geometry}
\usepackage{appendix}
\usepackage{float}
\usepackage{verbatim}
\usepackage[normalem]{ulem}
\usepackage{graphicx}
\usepackage{siunitx}
\usepackage[section]{placeins}

\setcounter{section}{-1}
\newtheorem{lemma}{Lemma}
\newcommand{\lemmaautorefname}{Lemma}

\title{CLimate Analysis using Digital Estimations Non-Offical Manual (CLAuDE NOM)}
\author{Sam "TechWizard" Baggen}
\date{\today}

\begin{document}

\maketitle

\tableofcontents

\newpage

\section{Introduction}

The CLimate Analysis using Digital Estimations model is a simplified planetary climate model. It will be used to educate people on how climate physics works and to experiment with different
parameters and see how much influence a tiny change can have (like for instance the rotation rate of the planet around its axis). It is built to be accessible to and runnable by everyone,
whether they have a super computer or a dated laptop. The model is written in Python and written during the weekly streams of Dr. Simon Clark \cite{twitch}. There is a useful playlist on
Simon's Twitch which has all the streams without ad breaks or interruptions \cite{playlist}.

The manual itself is split up into distinct sections, each explaining one particular part of the model. Each section will be treating one topic, like radiation, advection or the control panel.
Although many concepts cannot be seen in isolation, as the wind has influence on how much temperature is distributed throughout the atmosphere, the calculations can be split up. The manual is
cumulative, starting with the basics and slowly building up to the current form of the algorithm. All changes to the algorithms can therefore be found here. An important distinction needs to be
made regarding the changes though. If the changes only change one part of the calculations, then it is considered an evolution, which will be added to the relevant section. However if the changes
are significant and not based on the previous code then the old alghorithms will be relocated to \autoref{sec:history}. Though the relevant theory will remain, as that is required to gain an
understanding of what the algorithm does. Do note that the radiation \autoref{sec:rad} is an exception for the first calculations as this forms the basis of the beginning of CLAuDE and the
fundamentals of the theory which I deem important enough to be left in place even if the calculations end up significantly different.

This manual will provide an overview of the formulae used and will explain aspects of these formulae. For each equation each symbol will be explained what it is. In such an explanation, the units
will be presented in SI units \cite{SI} between brackets like: $T$: The temperature of the planet ($K$). Which indicates that $T$ is the temperature of the planet in degrees Kelvin. If you need
to relate SI units to your preferred system of units, please refer to the internet for help with that. There are great calculators online where you only need to plug in a number and select the
right units.

Within this manual we will not concern ourselves with plotting the data, instead we focus on the physics side of things and translating formulae into code. If you are interested in how the
plotting of the data works, or how loading and saving data works, please refer to the relevant stream on Simon's Twitch page \cite{twitch}.

This manual is for the toy model, which is as of now still in development. One important thing to note is that the layout may change significantly when new sections are added. This is due to the amount of code that is added/changed. If a lot of code changes, a lot of so called
'algorithm' blocks are present which have different placement rules than just plain text. Therefore it may occur that an algorithm is referenced even though it is one or two pages later. This is
a pain to fix and if something later on changes, the whole layout may be messed up again and is a pain to fix again. Hence I opt to let \LaTeX (the software/typeset language used to create this
manual) figure out the placement of the algorithm blocks, which may or may not be in the right places.

The manual is now up on the Planet Factory GitHub repository\cite{claudeGit}, together with all the source code. There is also a fork \cite{nomGit} that also contains the source code.
The fork will usually be more up to date than the version on the Planet Factory repository as Simon needs to merge pull requests into the repository. However I can update the fork freely so if a
particular stream is missing in the version on the Planet Factory repository, check the fork/Discord whether there is a newer version. If that is not the case, you just have to be a bit more
patient, or you can start writing a part of the manual yourself! Don't forget to ping me in the Discord to notify me of any additions (GitHub refuses to send me emails so I have no other way of
knowing).

\FloatBarrier
\newpage
\input{topics/control_panel.tex}

\FloatBarrier
\newpage
\input{topics/util_funcs.tex}

\FloatBarrier
\newpage
\input{topics/radiation.tex}

\FloatBarrier
\newpage
\input{topics/velocity.tex}

\FloatBarrier
\newpage
\input{topics/advection.tex}

\FloatBarrier
\newpage
\input{topics/planar.tex}

\FloatBarrier
\newpage
\input{topics/master.tex}

\FloatBarrier
\newpage
\input{appendices/TTNMETAF.tex}

\FloatBarrier
\newpage
\input{appendices/history.tex}

\FloatBarrier
\newpage
\input{appendices/vars.tex}

\newpage
\bibliography{references}
\bibliographystyle{plain}
\end{document}


\section{Classical simulation}
\label{sec:classical}
While the currently applied traditional methods for the analysis of experimental scattering data discussed previously are popular.
There is growing interest in the use of multi-modal analysis methods that leverage classical simulation to assist in the analysis of scattering data.\autocite{ivanovic_temperature-dependent_2018,scoppola_combining_2018,dabkowska_modulation_2014,hub_interpreting_2018}
This would involve the simulation of the chemical system in order to educate the analysis of the experimental data.
These systems, especially when the materials being simulated are soft in nature, are often highly complex and typically cover large length scales.
Classical simulation, particularly in combination with coarse-grained potential models, can feasibly enable the simulation of these systems.

In order to simulate the complexity of a real chemical system, it is necessary to model the electrons of the molecules and their interactions.
This is usually achieved using quantum mechanical calculations, where the energy of the system is calculated by finding some approximate solution to the Schr\"{o}dinger equation.
However, quantum mechanical calculations are very computationally expensive and are realistically limited to hundreds of atoms.
In order to simulate a soft matter system such as a phospholipid monolayer or polymer nanoparticles, it is necessary to simplify the calculation being performed.
This leads to the use of classical simulations, where parameterised analytical functions are used to represent the potential energy of the system.
Classical simulations are used substantially in this work, in terms of molecular dynamics simulations.\footnote{Molecular dynamics (MD) is discussed in detail in Section~\ref{sec:optimisation}.}
Therefore, it is necessary to introduce the underlying theory on which this method is defined.

\subsection{Potential models}
\label{sec:potentmodels}
Potential modelling is a more computationally efficient method for the calculation of the potential energy of a chemical system.
A potential model consists of a series of mathematical functions that depend on the atomic positions, $\mathbf{r}$.
Each of the functions represents the potential energy of a different interaction for a given atom.
Broadly, these interactions can be split into bonded and non-bonded, such that the total energy may be described as follows,
%
\begin{equation}
\begin{aligned}
  E_{\text{total}}(r) = & \sum_{\text{bonded pairs}}{E_{\text{bonded}}(r)} \\
  & + \sum_{\text{atom pairs}}{E_{\text{non-bonded}}(r)}.
\end{aligned}
\end{equation}
%
The total potential energy is then the sum of the potential energy for each of the individual atoms.

The bonded terms are used to describe different aspects of chemical bonds.
These typically consist of bond stretches, angle bends and dihedral torsions, these interactions have the following mathematical form,\footnote{These forms are specific to the OPLS2005 potential model (\cite{banks_integrated_2005}), other potential models may have different functions.}
%
\begin{equation}
\begin{aligned}
  E_{\text{bonded}}(b, \theta, \phi) = & \sum_{\text{bonds}}K_b(b-b_0)^2 + \sum_{\text{angles}}K_{\theta}(\theta-\theta_0)^2 \\
  & + \sum_{\text{dihedrals}} \frac{1}{2}\big\{A_1[1 + \cos(\phi)] \\
  & + A_2[1 - \cos(2\phi)] + A_3[1 + \cos(3\phi)]\big\},
\end{aligned}
\end{equation}
%
where, $K_b$ and $b_0$, $K_{\theta}$, $\theta_0$, and $A_1$, $A_2$, and $A_3$ are interaction dependent parameters for the bonds, angles, and dihedrals respectively, while $b$, $\theta$, and $\phi$ are the bond lengths, the size of the angles, and the size of the dihedrals that depend on the atom positions.\footnote{The values for the interaction dependent parametes are determined as outlined in Section~\protect\ref{sec:parameterisation}.}
It can be seen that both the bond stretch and angle bend have harmonic functions, whereas the dihedral consists of a more complex multiple cosine functions.

The non-bonded terms are a series of functions that describe the potential energy of intermolecular interactions, such as electrostatics and London dispersion forces.
The potential energies of the short-range interactions are usually modelled as a combination of the attractive London dispersion interaction and the repulsive exchange forces that arise from the Pauli exclusions principle.\autocite{leach_molecular_1996}
These are often forms such as shown below for the Lennard-Jones potential model,\autocite{lennard-jones_determination_1924}
%
\begin{equation}
\begin{aligned}
  E_{\text{non-boned}}(r) = & E_{\text{repulsive}} + E_{\text{attractive}} \\
  = & \frac{A}{r^{12}} - \frac{B}{r^6} = 4\varepsilon\Bigg[\bigg(\frac{\sigma}{r}\bigg)^{12} - \bigg(\frac{\sigma}{r}\bigg)^6\Bigg]
\end{aligned}
\end{equation}
%
where, $r$ is the distance between two particles, $A$ and $B$ are interaction dependent parameters, and $\sigma$ and $\epsilon$ are simple reformations of these parameters,
%
\begin{equation}
  A = 4\varepsilon\sigma^{12} \;\;\;\; B = 4\varepsilon\sigma^6.
\end{equation}
%
Figure~\ref{fig:lj} shows each component of the Lennard-Jones potential model for atoms of argon.\footnote{Using parameters for $A$ and $B$ determined in \cite{rahman_correlations_1964}.}
The Lennard-Jones potential model is not the only form that may be used for the modelling of the short-range non-bonded interactions, others such as the Buckingham and Morse potentials exist.\autocite{buckingham_classical_1938, morse_diatomic_1929}
In each case, there is a short ranged repulsive interaction to describe the electrostatic repulsion between the electron clouds, and a longer range attractive component that represents dispersion interactions.
However, the Lennard-Jones model has been used heavily in this work.
%
\begin{figure}[t]
    \forceversofloat
    \centering
    \includegraphics[width=\textwidth]{theory/lj}
    \caption{The form of each component; attractive (blue), repulsive (orange), of the Lennard-Jones potential model (green) for argon, using parameters in \cite{rahman_correlations_1964}.}
    \label{fig:lj}
\end{figure}
%

While the short-range interactions can be accounted for by a function such as the Lennard-Jones potential model, the potential energy of the long-range electrostatic interactions are usually modelled, more consistently, using Coulomb's law for classical electrostatic interaction between point particles,\autocite{coulomb_premier_1788, coulomb_second_1788}
%
\begin{equation}
  E_{\text{Coulomb}}(r) = \frac{1}{4\pi\varepsilon_0}{\frac{q_iq_je^2}{r^2}},
  \label{equ:col}
\end{equation}
%
where, $r$ is the distance between the two particles, $\varepsilon_0$ is the dielectric permittivity of the vacuum, $e$ is the charge of the electron, and $q_i$ and $q_j$ are the electronic charges on each of the particles.
It is clear that when $q_i$ and $q_j$ have the opposite signs Coulomb's law is always attractive.
The fact that Equation~\ref{equ:col} contains a factor of $r^2$ indicates that this is a much longer range interaction than those modelled with the Lennard-Jones model, make the Coulomb potential more complex to compute.\autocite{frenkel_understanding_1996}

An example of a very large classical simulation would be $\sim3$ million atoms.\autocite{gumbart_regulation_2009}
However, this is still only \SI{1.8e-16}{\mol} which is not remotely realistic as a simulation of a ``real'' system.
A common method to allow for the apparent simulation of a much larger system is the use of periodic boundary conditions.\footnote{Abbreviated to PBC.}
This is where a boundary condition is applied to the edges of the simulation cell, such as to mimic an infinite system, such that the simulation cell is surrounded by identical images of itself, this is shown pictorially in Figure~\ref{fig:pbc}.
Using the PBC means that atomic diffusion is conserved as when an atom reaches the edge of the simulation cell, it will appear on the other side as though it came from the adjacent periodic cell.
The use of a PBC is particularly powerful in the simulation of homogenous systems, such as liquids.
%
\begin{figure}[b]
    \forceversofloat
    \centering
    \includegraphics[width=0.8\textwidth]{theory/pbc}
    \caption{A graphical representation of the PBCs. Reprinted, with permission of Elsevier, from \cite{frenkel_understanding_1996}.}
    \label{fig:pbc}
\end{figure}
%

The cut-off is another important factor for classical simulation, this is the distance after which the energy between two particles is considered to be zero.
Therefore, for distances greater than the cut-off, it is not necessary to calculate the energy between the two particles as it is taken to be zero.\footnote{This leads to an increase in computational efficiency.}
Code Block~\ref{cb:lj} gives an example of some code that could be used to calculate the Lennard-Jones energy of an atomistic system, where both the PBC and the energy cut-off distance are considered.
%
\begin{listing}[b]
    \forcerectofloat
    \centering
    \caption{Code that may be used to generate the Lennard-Jones energy for a given atomistic system, which accounts for the PBC and the energy cut-off distance. The input varibles are \texttt{coordinates} which is an array of floats describing the position of the \texttt{N} particles, \texttt{cell} which are the unit cell vectors, \texttt{cut\_off} which is potential energy cut-off, and \texttt{A} and \texttt{B} which are the Lennard-Jones potential parameters. This returns an array with the energy for each particle.}
    \lstinputlisting[nolol]{reports/code_blocks/lennardjones.py}
    \label{cb:lj}
\end{listing}
%

The use of the PBC may be problematic for systems containing long-range interactions, such as classical electrostatics, due to the fact that the range of the electrostatic interaction may be much greater than the size of half of the simulation cell, which can be taken to be the energy cut-off distance.
In order to avoid truncation artefacts, the Ewald summation is often used for the calculation of the electrostatic contribution to the potential energy.\autocite{ewald_berechnung_1921}
The Ewald summation involves performing the summation of the contributing interaction energies in reciprocal space rather than in real space as is the case for the short-range interactions.
Most modern MD simulation software packages implement the Ewald summation using a particle mesh Ewald method.\autocite{essmann_smooth_1995}

\subsection{Parameterisation}
\label{sec:parameterisation}
Section~\ref{sec:potentmodels} introduced the idea of potential models that may be used to evaluate the potential energy of a given system, requiring much less time than methods that rely on the use of quantum mechanics.
However, for these methods to be effective, it is important that the potential models used are able to model the system under study accurately.
This is achieved initially by selecting the correct potential model for a given interaction, and then by ensuring that the interaction-dependent parameters are accurate for a given interaction.
The method of obtaining such parameters is referred to as ``parameterising'' the model.
Model parameterisation is important for all types of potential models, for example it is necessary to determine the equilibrium bond length $b_0$ and the force constant $K_b$ for a given covalent bonds, or the partial electrostatic charge that is present on a carbonyl oxygen atom when it interacts with the hydrogen atom from a neighbouring hydroxyl group.

Parameterisation of a potential model is usually achieved by fitting the potential model functions to energetic data obtained using a higher accuracy technique.\footnote{These may be quantum mechanical calculations or experimental methods.}
We will not dwell on the details of potential model parameterisation,\footnote{This is discussed in detail in many textbooks such as \cite{harvey_computational_2018,leach_molecular_19962}} however, it is important to note that the parameters used in MD simulation are not absolute and depend heavily on the merits of the parameterisation method.

In this work, we have focused heavily on the use of off-the-shelf potential models, to ensure the easy replicability of the work.
Off-the-shelf potential models are those that are determined to be applied to a wide range of chemical systems.
An example includes the OPLS potential model which was parameterised by comparison to quantum mechanical measurements and crystallographic data.\autocite{jorgensen_opls_1988}
While these off-the-shelf potential models are useful for their ease-of-use, it is noted that often these forcefields may require optimisation for the particular system.

\subsection{Coarse-graining}
\label{sec:coarsegraining}
The atomistic simulation of very large systems, such as multiple surfactant micelles or large phospholipid monolayers, require a huge number of atoms.
While computational efficiency improvements such as the PBC or the energy cut-off distance are able to reduce the time taken to simulate these systems, it is often still not possible to produce physically meaningful simulations,\footnote{In particular for emergent properties that depend on large system sizes and long simulation times.} without including some other efficiency improvements.

This has led to the use of coarse-graining of molecules in simulations.
This is the definition of super-atoms, in the place of groups of atoms, known as ``beading'', some examples are shown for the MARTINI force field\autocite{marrink_martini_2007} in Figure~\ref{fig:cg}.
Each of the super-atoms must correspond to the chemistry of the underlying atoms.
For example, the MARTINI potential model introduces five different apolar, beads to represent the polarity of the carbon atoms that make up the super-atom.
Additionally, there are thirteen other super-atom types that can be used to model polar, nonpolar, and charged atomic groups.
%
\begin{figure}[t]
    \forcerectofloat
    \centering
    \includegraphics[width=0.8\textwidth]{theory/beading}
    \caption{Three examples of the MARTINI coarse-graining mechanism for (a) aspertic acid, (b) a water cluster, and (c) a molecule of DPPC. Reprinted with permission of the Institute of Physics, from \cite{pluhackova_biomembranes_2015}.}
    \label{fig:cg}
\end{figure}
%

In addition to the computational benefit of having fewer particles in the simulation,\footnote{Therefore requiring fewer integrations of the equations of motion} there is also the opportunity to increase the timestep length for the simulation.\autocite{pluhackova_biomembranes_2015}
This can be achieved as the highest frequency vibrations that must be modelled in the system are integrated out.
For example, another coarse-grained model called the united atom potential model, where the hydrogen atoms have been integrated out, the timestep may be larger than for the same all-atom system as it is no longer necessary to model the high-frequency \ce{C-H} bond.

The technique of coarse-graining a molecule can range from the integration of the hydrogen atoms into the heavier atoms to which they are bound, all the way to the treatment of entire molecules as a single ``bead'', with the inclusion of an implicit solvent.
The parameterisation of a coarse-grained potential model is carried out in much the same way as discussed in Section~\ref{sec:parameterisation} for all-atom potential models.
The coarse-grained parameters are determined by comparison with a higher-resolution technique.\footnote{Often this is all-atom MD simulations.}


\section{State of the Art}

Before the main matter of the thesis, it is important to expose the current
state of the art, to check if the previous research done in the topics
related to this project. First, the section will sum up the current state of
the art in the algorithms that will be used by the thesis, as well as all
naming several libraries currently used for that purpose. Last, this section
will provide a basic state of the language to be used, Haskell; that will also
serve as a motivation for why to develop the project using this tool.\\

\subsection{Heuristic Search}

Heuristic Search is a problem solving method that belongs to Artificial
Intelligence \cite{rusell-2003-aima} used in robotics, pathfinding, computer
gaming among other fields. We can distinguish two types of heuristic search
algorithms: uninformed algorithms, which do not use a heuristic function and
perform a brute-force search; and informed algorithms, which use a heuristic
function to provide better performance than the aforementioned brute-force
algorithms.\\

\begin{figure}[ht]
\centering
\includegraphics[width=0.8\textwidth]{img/empty-tree.png}
\caption{Example of a search tree}
\label{tree:empty}
\end{figure}

Although every algorithm included in this thesis can work with implicit graphs,
the best way to gain some intuition about them is to reflect their behavior on
a search tree, like the one in Figure \ref{tree:empty}. This tree presents a
root node (top of the image), from which is possible to see two different
oriented edges going out to two new nodes. This presents in a explicit way the
fact of being able to traverse the search space using operators given in a
problem space. The green nodes present final states. The objective of any
search algorithm then is to find a path from the root node (which is the
initial state defined in the problem space) to a final node, using different
constraints depending on the problem at hand: the shortest path, lowest cost
path, or just a solution that can be found in the shortest time possible. Using
this graphical representation, we can now go deep into explaining the current
state of the art of the algorithms that will be included in the framework.\\

\subsubsection{Uninformed Algorithms}

One of the basic brute-force algorithms is, undoubtedly, Breadth-First Search.
It was first introduced by Konrad Zuse in 1945, although published years later
\cite{zuse-1972-plankalkul}. This algorithm uses a queue (First In, First Out)
data structure to store the nodes expanded. The use of this queue to sort the
nodes to expand results in an exhaustive search per depth in the tree: first
the depth 0 nodes are expanded, the depth 1, the depth 2, etc, until the
solution is found or until the search space is completely exhausted. This
behavior can be appreciated in Figure \ref{tree:bfs}.\\

\begin{figure}[ht]
\centering
\includegraphics[width=0.8\textwidth]{img/bfs.png}
\caption{Breadth-First Search execution on the tree}
\label{tree:bfs}
\end{figure}

In Figure \ref{tree:bfs} it is possible to see that the nodes are visited from
shallower to deeper levels, ensuring that the solution returned by this
algorithm is indeed the one with the shortest path from the initial state. The
algorithm is complete, that is, it will find a solution if it exists in the
search space, even if such space is infinite. The solution found will be the
nearest to the initial state, which is ensured to be the optimal if there no
variable costs. Its complexity is defined by $O(|V|)$, that is, the total
number of states. This is common to all search algorithms: theoretically, they
have to check all states in a worst case scenario. However, it is important to
notice that the complexity to finding a certain solution at a depth $d$ is
$O(b^{d+1})$, where $b$ is the branching factor of the problem
\cite{rusell-2003-aima}.\\

Another well-known uninformed algorithm is Depth-First Search. This algorithm
uses the opposite approach to the problem: tries to search as deep as possible
before exhausting a branch or finding a solution. This algorithm was first
studied by Charles Pierre Trémaux in the 19th Century, with the purpose of
solving mazes with well defined passages \cite{even-2011-graph}. This algorithm
does not need a auxiliary data structure to hold nodes: instead, it is possible
to explore the nodes in depth just using recursive calls to the algorithm. This
allows Depth-First Search to perform searches in linear space, since it only
needs to store the stack calls needed to keep track of the search. Although
this is convenient for this project, it is possible as well to use a stack
structure (Last In, First Out) to hold all the nodes in an imperative language
in case the recursion is not desired \cite{rusell-2003-aima}. A complete
execution of this algorithm can be found in Figure \ref{tree:dfs}\\

\begin{figure}[ht]
\centering
\includegraphics[width=0.8\textwidth]{img/dfs.png}
\caption{Depth-First Search execution on the tree}
\label{tree:dfs}
\end{figure}

In the execution of Figure \ref{tree:dfs}, it is possible to see how it
exhausts the first branch until no more nodes can be expanded, to then
backtrack. This backtracking can be implicitly implemented (by using recursive
calls it is possible to recover from an exhausted branch). We can see how this
search returns a worse solution than Breadth-First: the solution found by the
algorithm is 3 operations away from the initial state, while the existing
solution found before has been completely ignored by this algorithm. The main
advantage of this algorithm is its space complexity to find a given solution at
a depth $d$ is indeed linear, and its execution to find a solution should
average faster than Breadth-First Search \cite{zhang-1995-bnb}. However,
Depth-First Search is not complete in implicit graphs: since the depth of the
tree can be infinite, the search can get lost expanding nodes that do not lead
to a recursion \cite{rusell-2003-aima}.\\

For that reason, the Iterative-Deepening Depth-First Search was developed: by
limiting the depth at which a Depth-First algorithm can explore, the
backtracking is used to explore certain depths \cite{korf-1985-depth}. This
eliminates the lack of completeness, and makes IDDFS equivalent to a
Breadth-First Search if the step used to increase the depth bound is one. It is
however important to remark that this algorithm is faster than BFS in the last
iteration but most likely slower if taking into account the cumulative time of
all depth executions. Its time and space complexity are the same of Depth-First
Search, but it is complete and optimal if the depth is increased one by one.\\

The last uninformed algorithm to explore is Uniform Cost Search. This algorithm
performs a brute-force search expanding first the lowest-cost node, using a
BFS-like fashion to explore the search space \cite{rusell-2003-aima}. This
algorithm is sometimes referred to as Dijkstra's Algorithm, although the latter
is considered to be subtly different and since we are applying it to implicit
graphs, the algorithm will be treated as UCS along the thesis
\cite{felner-2011-dijkstra}. This algorithm relies on a priority queue that
sorts the nodes and always returns the one whose current cost is lower. For
that reason, Uniform Cost Search can be seen as a variation of Breadth-First
Search that takes into account variable cost paths and thus always return the
lowest cost solution, instead the shorter one. UCS is, therefore, complete and
optimal.\\

\subsubsection{Informed Algorithms}

Informed algorithms are those that perform searches using a heuristic function.
This function evaluates a state and returns a value that presents how close
that state is to a solution. Using those values, the states can be ranked on
how convenient they are for the search (the closer to the solution, the more
relevant to the search is to expand such state) \cite{pearl-1984-heuristics}.\\

The main informed algorithm to take into account is the well-known A*
algorithm. First developed in 1968 as an extension of Dijkstra's algorithm, it
features an evaluation function that takes into account both the cost of a node
and its heuristic value \cite{hart-1968-formal}. The algorithm uses a priority
queue to sort the nodes in ascending order of $f$, the aforementioned
evaluation function. This function is defined as $f(n) = g(n) + h(n)$ where $g$
is the cost of the node and $h$ is the value of the heuristic function. That
way, the algorithm expands the nodes keeping a balance of current and expected
cost to obtain the solution. Two examples of this algorithm can be found in
Figure \ref{tree:astar}.\\

\begin{figure}[ht]
\centering
\includegraphics[width=0.8\textwidth]{img/astar.png}
\caption{A* Search executions using two different heuristics}
\label{tree:astar}
\end{figure}

In the first execution of Figure \ref{tree:astar} shows how the nodes are
expanded using the values computed at each iteration. At each new iteration,
the branch expanded is the one with lower projected costs. In the second
execution, we can see how a different heuristic returns the same solution but
expanding less nodes. This introduces an important concept of A*: with a
perfect heuristic, A* performs a perfect search, expanding only the necessary
nodes to obtain and ensure that the solution found is optimal
\cite{dechter-1985-astar}. This implies that the heuristic is relevant for the
node performance, but not only that: A* is only complete and optimal if the
heuristic function used is admissible, that is, if it never underestimates the
actual cost of getting from a node to a solution \cite{pearl-1984-heuristics}.
Its complexity in worst case scenario is the one of Breadth-First Search;
$O(b^{d+1})$.\\

Following a similar idea, but using iterative-deepening for obtaining a better
memory performance, it is important to mention Iterative-Deepening A*
\cite{korf-1985-depth}. The basic idea behind it is to perform a depth-first
search using the $f$ function of A*. This results in a linear-memory algorithm,
that explores the solutions in thresholds defined by $f$ as a cutoff function.
This makes an interesting algorithm when memory constraints exist, and it is
ensured to return the shortest path from the initial state to a solution as
long as the heuristic is admissible.\\

\begin{figure}[ht]
\centering
\includegraphics[width=0.8\textwidth]{img/dfbnb.png}
\caption{Depth-First Branch and Bound Search execution on the tree}
\label{tree:dfbnb}
\end{figure}

Last, it is important to remark the family of Branch and Bound algorithms.
These algorithms uses a solution that is found to keep on the search, using the
cost of the current best solution as a bound for the rest of the search
\cite{zhang-1995-bnb}. These algorithms result as well in linear-memory
executions but ensure that the optimal solution is found (since the execution
only ends when the search space is exhausted). It is possible to see an example
execution of Depth-First Branch and Bound in Figure \ref{tree:dfbnb}, where
each new solution found creates a new bound for the search (the red highlight
indicates the part of search tree that is out of bounds when tried to be
expanded).\\

These algorithms can be tuned to use different bounds like depth, cost or other
evaluations. It is specially relevant for this project an informed version of
this algorithm proposed in \cite{zhang-1995-bnb}, that uses the $f$ function to
expand the nodes and creates bounds using cost of each solution found.\\

\subsubsection{Libraries}

Due to being more appropriate for the performance that is in general desired,
we can find that the most amount of work on Heuristic Search is done in
imperative, fast languages like C++ or Java.\\

In C++, we can find full search frameworks like \emph{HOG2} \cite{hog2},
\emph{Research code for heuristic search} \cite{cpp-search} or \emph{The
  Heuristic Search Research Framework} \cite{goldenberg-2017-framework}. All
these frameworks offer a full set of algorithms and procedures to override the
default implementations (such as cost, heuristic or expansion functions) in
order to adapt the library's behavior to the problem at hand. Also, these
frameworks offer visual representations options; a feature which is indeed the
main goal in the case of \emph{The Heuristic Search Research Framework}, that
offers a general visualization of algorithm behavior instead of domain specific
ones. On the other hand, in Java we can find similar projects like
\emph{Combinatorial Search for Java} \cite{cs4j} or \emph{AIMA}
\cite{java-aima}.\\

Trying to find similar projects in functional languages is more complicated
than that. However, one can find interesting projects like \emph{AIMA} written
in Common Lisp \cite{lisp-aima} or even a complete search framework written in
OCaml \cite{ocaml-search}. In Haskell, however, projects of this size are
nowhere to be found: All the algorithms are distributed in individual packages
with completely different implementations, as well as the data structures used
to perform the search.\\

\subsection{Haskell}

Haskell's first version was released in 1990 after the efforts of a committee
in FPCA '87 for creating an open standard for a ``non-strict, purely functional
language'' \cite{haskell-history}. Haskell's main features have remain patent
in the language, but constantly evolving: the language's main pillars are
\cite{haskell-98, haskell-2010}:

\begin{enumerate}
\item \textbf{Strong and statically typed}: the types are checked at compile
  time. That makes the run-time be sure that every function will get as
  parameter the expected object, making it more robust. However, no explicit
  type declaration is needed (although it is usually considered a good
  practice); types can be inferred most of the times by the compiler.
\item \textbf{Purely functional}: this type system is what allows Haskell to be
  purely functional. For Haskell, a string literal is of type \texttt{String},
  while an user's input on the prompt is a \texttt{IO String}. While at first
  shocking, this quality of Haskell maintains the referential transparency
  intact: the same function call with the same arguments is guaranteed to
  provide always the same output. All side effects are contained into monads
  (like the aforementioned \texttt{IO} monad) so they are contained and
  isolated.
\item \textbf{Lazy}: the fact that Haskell's evaluation is lazy (contrary to
  more common strict evaluation) means that a expression is only computed if
  its result is really necessary at a moment in time. This allows expressions
  to be defined in a much higher level: telling the computer what something is
  rather than how to compute it, and leaving the details of it to the compiler.
  Lazy evaluation provides for instance the use of infinite lists (since only
  the necessary part will be actually evaluated).
\item \textbf{Concurrent abstractions}: All the aforementioned characteristics
  also add up to the fact that the compiler is able to include concurrent
  optimizations into regular Haskell code thanks to its high-level definitions.
\end{enumerate}

Currently, the Glasgow Haskell Compiler (GHC) can be almost considered the
de-facto standard in Haskell compilers: widely spread and with an impressive
interface of pragmas to enable different optimizations by the compiler, it is
the compiler used for most projects because of the language extensions it
provides. Regarding packaging frameworks we can use Cabal, as a more
established option; or Stack, that wraps around Cabal configurations offering
more robust dependency installs and builds. Both frameworks offer several tools
for compilation, packaging, documentation, distribution, testing and profiling.
These tools will be explained in detail as they appear in the thesis.\\

Although not yet mainstream, Haskell is a language used in the industry that is
specially well-regarded in web backends: its concurrency is based in threads
that are so light that can be spawned in much larger densities than average
threads \cite{epstein-2011-cloud}. This fits specially well in a web server,
where every request can get one thread without compromising performance.
Haskell's type system also prevents different attacks (like SQL/XSS injection)
to be performed in these systems \cite{snoyman-2015-yesod}.

\newpage

%%% Local Variables:
%%% TeX-master: "tfg"
%%% End:


\RequirePackage[l2tabu, orthodox]{nag}
\documentclass[10pt, a4paper]{article}

\usepackage[T1]{fontenc}
\usepackage{fancyvrb}

\title{The dvi-format and the program dvitype}
\author{Ernst Reissner (rei3ner@arcor.de)}

\begin{document}

\maketitle
\tableofcontents

\section{Introduction}
This document describes the dvi file format
traditionally used by \LaTeX{}
and still in use with \texttt{htlatex} and that like.

A \texttt{DVI} file is a stream of 8-bit bytes, which may be regarded as a
series of commands in a machine-like language. The first byte of each command
is the operation code, and this code is followed by zero or more bytes
that provide parameters to the command. The parameters themselves may consist
of several consecutive bytes;
for example, the `\texttt{set\_rule}' command has two
parameters, each of which is four bytes long. Parameters are usually
regarded as nonnegative integers; but four-byte-long parameters,
and shorter parameters that denote distances, can be
either positive or negative. Such parameters are given in two's complement
notation. For example, a two-byte-long distance parameter has a value between
$-2^{15}$ and $2^{15}-1$.

A \texttt{DVI} file consists of a ``preamble,''
followed by a sequence of one or more ``pages,''
followed by a ``postamble''.
The preamble is simply a \texttt{pre} command,
with its parameters that define the dimensions used in the file;
this must come first.
Each ``page'' consists of a \texttt{bop} command,
followed by any number of other commands that tell where characters are to
be placed on a physical page, followed by an \texttt{eop} command.
The pages appear in the order that they were generated,
not in any particular numerical order.
If we ignore \texttt{nop} commands and \texttt{fnt\_def} commands
(which are allowed between any two commands in the file),
each \texttt{eop} command is immediately followed by a \texttt{bop} command,
or by a \texttt{post} command;
in the latter case, there are no more pages in the file,
and the remaining bytes form the postamble.
Further details about the postamble will be explained later.

Some parameters in \texttt{DVI} commands are ``pointers''.
These are four-byte quantities that give the location number
of some other byte in the file;
the first byte is number~0, then comes number~1, and so on.
For example, one of the parameters of a \texttt{bop} command
points to the previous \texttt{bop};
this makes it feasible to read the pages in backwards order,
in case the results are being directed to a device
that stacks its output face up.
Suppose the preamble of a \texttt{DVI} file occupies bytes 0 to 99.
Now if the first page occupies bytes 100 to 999, say,
and if the second page occupies bytes 1000 to 1999,
then the \texttt{bop} that starts in byte 1000
points to 100 and the \texttt{bop} that starts in byte 2000 points to 1000.
(The very first \texttt{bop},
i.e., the one that starts in byte 100, has a pointer of $-1$.)

The  \texttt{DVI} format is intended to be both
compact and easily interpreted by a machine.
Compactness is achieved by making most of the information implicit
instead of explicit.
When a \texttt{DVI}-reading program reads the commands for a page,
it keeps track of several quantities:
%
\begin{itemize}
\item
The current font $f$ is an integer;
this value is changed only by \texttt{fnt} and \texttt{fnt\_num} commands.
\item
The current position on the page
is given by two numbers called the horizontal and vertical coordinates,
$h$ and $v$.
Both coordinates are zero at the upper left corner of the page;
moving to the right corresponds to increasing the horizontal coordinate, and
moving down corresponds to increasing the vertical coordinate.
Thus, the coordinates are essentially Cartesian,
except that vertical directions are flipped;
the Cartesian version of $(h,v)$ would be $(h,-v)$.
\item
The current spacing amounts
are given by four numbers $w$, $x$, $y$, and $z$,
where $w$ and~$x$ are used for horizontal spacing and where $y$ and~$z$
are used for vertical spacing.
\item
There is a stack containing $(h,v,w,x,y,z)$ values;
the \texttt{DVI} commands \texttt{push} and \texttt{pop} are used
to change the current level of operation.
Note that the current font~$f$ is not pushed and popped;
the stack contains only information about positioning.
\end{itemize}

The values of $h$, $v$, $w$, $x$, $y$, and $z$ are signed integers having up
to 32 bits, including the sign. Since they represent physical distances,
there is a small unit of measurement such that increasing $h$ by~1 means
moving a certain tiny distance to the right. The actual unit of
measurement is variable, as explained below.

Here is a list of all the commands that may appear in a \texttt{DVI} file.
Each command is specified by its symbolic name (e.g., \texttt{bop}),
its opcode byte (e.g., 139), and its parameters (if any).
The parameters are followed by a bracketed number
telling how many bytes they occupy; for example,
`$p[4]$' means that parameter $p$ is four bytes long.

\section{The Op-Codes}\label{sec:opCodes}

\begin{itemize}

\item[0-127] \texttt{set\_char\_$<d>$ $d$} where $d\in\{0,\dots,127\}$.

Typeset character number~$d$ from font~$f$
such that the reference point of the character is at $(h,v)$.
Then increase $h$ by the width of that character.
Note that a character may have zero or negative width,
so one cannot be sure that $h$ will advance after this command;
but $h$ usually does increase.

\item[128-131] \texttt{set\_$<d>$ $128+d$ $c[d]$} where $d\in\{1,\dots,4\}$.
Same as \texttt{set\_char\_0}, except that character number~$c$ is typeset.
Note that $d$ determines the number of characters.
\texttt{set\_$2$} is intended for oriental languages
with a script with a lot of characters.

\item[132] \texttt{setrule $132$ $a[4]$ $b[4]$}.
Typeset a solid black rectangle of height $a$ and width $b$,
with its bottom left corner at $(h,v)$.
Then set $h:=h+b$. If either $a<=0$ or $b<=0$, nothing should be typeset.
Note that if $b<0$, the value of $h$ will decrease
even though nothing else happens.
Programs that typeset from \texttt{DVI} files
should be careful to make the rules line up carefully
with digitized characters,
as explained in connection with the \texttt{rule\_pixels} subroutine below.

\item[137] \texttt{put$<d>$ $132+d$ $c[d]$} where $d\in\{1,\dots,4\}$.
Typeset character number~$c$ from font~$f$
such that the reference point of the character is at $(h,v)$.
(The `put' commands are exactly like the `set' commands,
except that they simply put out a character or a rule
without moving the reference point afterwards.)

\item[137] \texttt{put\_rule $137$ $a[4]$ $b[4]$}.
Same as \texttt{set\_rule}, except that $h$ is not changed.

\item[138] \texttt{nop}.
No operation, do nothing. Any number of \texttt{nop}'s
may occur between \texttt{DVI} commands,
but a \texttt{nop} cannot be inserted
between a command and its parameters or between two parameters.

\item[139] \texttt{bop $139$ $c_0[4]$ $c_1[4]$ $\ldots$ $c_9[4]$ $p[4]$}.
Indicates the beginning of a page:
Set $(h,v,w,x,y,z):=(0,0,0,0,0,0)$ and set the stack empty.
Set the current font $f$ to an undefined value.
The ten $c_i$ parameters can be used to identify pages,
if a user wants to print only part of a \texttt{DVI} file;
\TeX82 gives them the values of \texttt{count0} $\ldots$ \texttt{count9}
at the time \texttt{shipout} was invoked for this page.
The parameter $p$ points to the previous \texttt{bop} command in the file,
where the first \texttt{bop} has $p=-1$.

\item[140] \texttt{eop $140$}
End of page:
Print what you have read since the previous \texttt{bop}.
At this point the stack should be empty.
(The \texttt{DVI}-reading programs that drive most output devices
will have kept a buffer of the material
that appears on the page that has just ended.
This material is largely, but not entirely,
in order by $v$ coordinate and (for fixed $v$) by $h$~coordinate;
so it usually needs to be sorted into some order that is
appropriate for the device in question.
\texttt{DVItype} does not do such sorting.)

\item[141] \texttt{push $141$}.
Push the current values of $(h,v,w,x,y,z)$ onto the top of the stack;
do not change any of these values. Note that $f$ is not pushed.

\item[142] \texttt{pop $142$}.
Pop the top six values off of the stack and assign them to $(h,v,w,x,y,z)$.
The number of pops should never exceed the number of pushes,
since it would be highly embarrassing if the stack were empty
at the time of a \texttt{pop} command.

\item[143-146] \texttt{right$<d>$ $142+d$ $b[d]$} where $d\in\{1,\dots,4\}$.
Set $h:=h+b$, i.e., move right $b$ units.
The parameter is a signed number in two's complement notation;
if $b<0$, the reference point actually moves left.

\item[147] \texttt{w0 $147$ }.
Set $h:=h+w$; i.e., move right $w$ units. With luck,
this parameterless command will usually suffice, because the same kind of motion
will occur several times in succession; the following commands explain how
$w$ gets particular values.

\item[148-151] \texttt{w$<d>$ $147+d$ $b[d]$} where $d\in\{1,\dots,4\}$.
Set $w:=b$ and $h:=h+b$.
The value of $b$ is a signed quantity in two's complement notation.
This command changes the current $w$~spacing and moves right by $b$.

\item[152] \texttt{x0 $152$}.
Set $h:=h+x$; i.e., move right $x$ units. The `$x$'
commands are like the `$w$' commands except that they involve $x$ instead
of $w$.

\item[153-156] \texttt{x$<d>$ $152+d$ $b[d]$} where $d\in\{1,\dots,4\}$.
Set $x:=b$ and $h:=h+b$.
The value of $b$ is a signed quantity in two's complement notation.
This command changes the current $x$~spacing and moves right by $b$.

\item[159] \texttt{down$<d>$ $156+d$ $b[d]$} where $d\in\{1,\dots,4\}$.
Set $v:=v+a$, i.e., move down $a$ units.
The parameter is a signed number in two's complement notation;
if $a<0$, the reference point actually moves up.

\item[161] \texttt{y0 $161$}.
Set $v:=v+y$; i.e., move down $y$ units.
With luck, this parameterless command will usually suffice,
because the same kind of motion will occur several times in succession.

\item[162-165] \texttt{y$<d>$ $161+d$ $a[d]$} where $d\in\{1,\dots,4\}$.
Set $y:=a$ and $v:=v+a$.
The value of $a$ is a signed quantity in two's complement notation.
This command changes the current $y$~spacing and moves down by $a$.

\item[166] \texttt{z0 $166$}.
Set $v:=v+z$; i.e., move down $z$ units.
With luck, this parameterless command will usually suffice,
because the same kind of motion will occur several times in succession.
The `\texttt{z}' commands are like the `\texttt{y}' commands
except that they involve $z$ instead of $y$.

\item[167-170] \texttt{z$<d>$ $166+d$ $a[d]$} where $d\in\{1,\dots,4\}$.
Set $y:=a$ and $v:=v+a$.
The value of $a$ is a signed quantity in two's complement notation.
This command changes the current $z$~spacing and moves down by $a$.

\item[171] \texttt{fntnum0 $171$}.
Set $f:=0$. Font 0 must previously have been
defined by a \texttt{fnt\_def} instruction, as explained below.

\item[172-234] \texttt{fntnum$<d>$ $171+d$ } where $d\in\{1,\dots,63\}$.
Set $f:=d$.

\item[235-238] \texttt{fnt$<d>$ $235+d$ $k[d]$} where $d\in\{1,\dots,4\}$.
Set $f:=k$.
An application of \texttt{fnt$2$} or higher
maybe used for fonts with colors and texture information.

\item[239-242] \texttt{xxx$<d>$ $238+d$ $k[2]$ $x[k]$}
where $d\in\{1,\dots,4\}$.
This command is undefined in general;
it functions as a $(k+2)$-byte \texttt{nop}
unless special \texttt{DVI}-reading programs are being used.
\TeX82 generates \texttt{xxx1} when a short enough \texttt{special} appears,
setting $k$ to the number of bytes being sent.
It is recommended that $x$ be a string having the form of a keyword
followed by possible parameters relevant to that keyword.

\item[243-246] \texttt{fntdef$<d>$ $242+d$
$k[d]$ $c[4]$ $s[4]$ $d[4]$ $a[1]$ $l[1]$ $n[a+l]$}
where $d\in\{1,\dots,4\}$.
Define font $k$; font definitions will be explained shortly.

\item[247] \texttt{pre $247$ $i[1]$ $num[4]$ $den[4]$ $mag[4]$ $k[1]$ $x[k]$}.
Beginning of the preamble;
this must come at the very beginning of the file.
Parameters $i$, $num$, $den$, $mag$, $k$, and $x$ are explained below.

\item[248] \texttt{post $248$}.
Beginning of the postamble, see below.

\item[249] \texttt{post\_post $249$}.
Ending of the postamble, see below.

\item[250-255] undefined currently.
\end{itemize}

\section{The Preamble}
\label{sec:preamble}

The preamble contains basic information about the file as a whole.
As stated above, there are six parameters:
%
\[
\hbox{i[1]| num[4], den[4], mag[4], k[1], x[k]}
\]
%
The $i$ byte identifies \texttt{DVI} format;
currently this byte is always set to~2.
(The value $i=3$ is currently used for an extended format that
allows a mixture of right-to-left and left-to-right typesetting.
Some day we will set $i=4$, when \texttt{DVI} format makes another
incompatible change---perhaps in the year 2048.)

The next two parameters, $num$ and $den$, are positive integers that define
the units of measurement; they are the numerator and denominator of a
fraction by which all dimensions in the \texttt{DVI} file could be multiplied
in order to get lengths in units of $10^{-7}$ meters. (For example, there are
exactly 7227 \TeX\ points in 254 centimeters, and \TeX82 works with scaled
points where there are $2^{16}$ sp in a point, so \TeX82 sets $num=25400000$
and $den=7227\cdot2^{16}=473628672$.)

The $mag$ parameter is what \TeX82 calls \texttt{mag}, i.e., 1000 times the
desired magnification. The actual fraction by which dimensions are
multiplied is therefore $mn/1000d$. Note that if a \TeX\ source document
does not call for any `{true}' dimensions, and if you change it only by
specifying a different \texttt{mag} setting, the \texttt{DVI} file that \TeX\
creates will be completely unchanged except for the value of $mag$ in the
preamble and postamble. (Fancy \texttt{DVI}-reading programs allow users to
override the $mag$~setting when a \texttt{DVI} file is being printed.)

Finally, $k$ and $x$ allow the \.{DVI} writer to include a comment, which is not
interpreted further. The length of comment $x$ is $k$, where $0<=k<256$.

\section{Font definitions}
\label{sec:fontDef}

Font definitions for a given font number $k$ contain further parameters
\[
\hbox{$c[4]$ $s[4]$ $d[4]$ $a[1]$ $l[1]$ $n[a+l]$.}
\]
The four-byte value $c$ is the check sum that \TeX\ (or whatever program
generated the \texttt{DVI} file) found in the \texttt{TFM} file for this font;
$c$ should match the check sum of the font found by programs that read
this \texttt{DVI} file.

Parameter $s$ contains a fixed-point scale factor that is applied to the
character widths in font $k$; font dimensions in \texttt{TFM} files and other
font files are relative to this quantity, which is always positive and
less than $2^{27}$.
It is given in the same units as the other dimensions of the \texttt{DVI} file.
Parameter $d$ is similar to $s$; it is the ``design size,''
and (like~$s$) it is given in \texttt{DVI} units.
Thus, font $k$ is to be used at $mag\cdot s/1000d$ times its normal size.

The remaining part of a font definition gives the external name of the font,
which is an ASCII string of length $a+l$. The number $a$ is the length
of the ``area'' or directory, and $l$ is the length of the font name itself;
the standard local system font area is supposed to be used when $a=0$.
The $n$ field contains the area in its first $a$ bytes.

Font definitions must appear before the first use of a particular font number.
Once font $k$ is defined, it must not be defined again;
however, we shall see below
that font definitions appear in the postamble as well as in the pages,
so in this sense each font number is defined exactly twice, if at all.
Like \texttt{nop} commands,
font definitions can appear before the first \texttt{bop},
or between an \texttt{eop} and a \texttt{bop}.

\section{The Postamble}
\label{sec:postamble}

The last page in a \texttt{DVI} file is followed by `\texttt{post}';
this command introduces the postamble,
which summarizes important facts that \TeX\ has accumulated about the file,
making it possible to print subsets of the data with reasonable efficiency.
The postamble has the form
%$$\vbox{\halign{\hbox{#\hfil}\cr
%  \texttt{post} |p[4]| |num[4]| |den[4]| |mag[4]| |l[4]| |u[4]| |s[2]| |t[2]|\cr
%  $\langle\,$font definitions$\,\rangle$\cr
%  \texttt{post_post} |q[4]| |i[1]| 223's$[{\G}4]$\cr}}$$
Here $p$ is a pointer to the final \texttt{bop} in the file. The next three
parameters, $num$, $den$, and $mag$, are duplicates of the quantities that
appeared in the preamble.

Parameters $l$ and $u$ give respectively the height-plus-depth of the tallest
page and the width of the widest page, in the same units as other dimensions
of the file. These numbers might be used by a \texttt{DVI}-reading program to
position individual ``pages'' on large sheets of film or paper; however,
the standard convention for output on normal size paper is to position each
page so that the upper left-hand corner is exactly one inch from the left
and the top.
Experience has shown that it is unwise to design \texttt{DVI}-to-printer
software that attempts cleverly to center the output; a fixed position of
the upper left corner is easiest for users to understand and to work with.
Therefore $l$ and~$u$ are often ignored.

Parameter $s$ is the maximum stack depth
(i.e.,
the largest excess of \texttt{push} commands over \texttt{pop} commands)
 needed to process this file.
Then comes $t$, the total number of pages (\texttt{bop} commands) present.

The postamble continues with font definitions,
which are any number of \texttt{fnt\_def} commands as described above,
possibly interspersed with \texttt{nop} commands.
Each font number that is used in the \texttt{DVI} file must be defined
exactly twice: Once before it is first selected by a \texttt{fnt} command,
and once in the postamble.

@ The last part of the postamble, following the \texttt{post\_post} byte
that signifies the end of the font definitions,
contains $q$, a pointer to the \texttt{post} command
that started the postamble.
An identification byte, $i$, comes next;
this currently equals~2, as in the preamble.

The $i$ byte is followed by four or more bytes that are all equal to
the decimal number 223 (i.e., @'337 in octal). \TeX\ puts out four to seven of
these trailing bytes, until the total length of the file is a multiple of
four bytes, since this works out best on machines that pack four bytes per
word; but any number of 223's is allowed, as long as there are at least four
of them. In effect, 223 is a sort of signature that is added at the very end.

This curious way to finish off a \texttt{DVI} file makes it feasible for
\texttt{DVI}-reading programs to find the postamble first, on most computers,
even though \TeX\ wants to write the postamble last. Most operating
systems permit random access to individual words or bytes of a file, so
the \texttt{DVI} reader can start at the end and skip backwards over the 223's
until finding the identification byte. Then it can back up four bytes, read
$q$, and move to byte $q$ of the file. This byte should, of course,
contain the value 248 (\texttt{post}); now the postamble can be read, so the
\texttt{DVI} reader discovers all the information needed for typesetting the
pages. Note that it is also possible to skip through the \texttt{DVI} file at
reasonably high speed to locate a particular page, if that proves
desirable.
This saves a lot of time,
since \texttt{DVI} files used in production jobs tend to be large.

\begin{Verbatim}[fontsize=\scriptsize]
ftp://ftp.rrzn.uni-hannover.de/pub/mirror/tex-archive/systems/knuth/dist/texware/dvitype.web
\end{Verbatim}
\end{document}

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