\documentclass[../../main.tex]{subfiles}

\begin{document}

Implementation was done using .NET {\Csharp} and its wrappers for \ac{OpenCV} library. It could be easily reasoned by the fact that it is better to deal with the complicated tasks using the tool that you know and can use to reach the goal. On the contrary, {\Csharp} is a great tool with many convenient helpers to make implementation quicker and less painful.
Multiple \ac{OpenCV} wrappers were used in the implementation on different stages of development process. OpenCvSharp was good enough on the whole way before, however, it was not able to do specific operations for the \ac{PTAM} code base. Thus \ac{EmguCV} was applied later as a replacement for OpenCvSharp.

All various logic units were split into the separate static classes for exact purposes. The project was also split into some set of library projects in order to separate \ac{OpenCV}, Rubik's cube and rendering code bases. The project is called framework thus every library can be easily substituted with another one. The project contains 2 modules for camera calibration with \ac{EmguCV}.

\subsubsection*{Extraction}

Extraction logic is contained in $RubiksCube.OpenCV$ project and its $FaceDetector$ and $FaceExtractor$ classes. The work-flow is as follows, $FaceDetector$ calls another utility class $ContourUtil$ to find specific contours. These contours are those who passes specified in the configuration threshold values and whose approximation shows 4 corners and convex structure. Afterwards, found contours are distinguished by the center of mass, it means that contours with similar or close enough center of mass are rejected to keep only one of them. This is done with \ac{OpenCV} method $Cv2.Moments$ and specific {\Csharp} \ac{Linq} code, see figure \ref{fig:impl_filtering_contours}.

\begin{figure} [!ht]
  \centering
    \lstset{style=sharpc}
        \begin{lstlisting}
            var matched_countours = ContourUtil.FindContours(copy);
            matched_countours = matched_countours.Distinct(...(x, y) =>
            {
                double mx = GetMassCenter(x);
                double my = GetMassCenter(y);
                double dx = Math.Abs(mx.X - my.X);
                double dy = Math.Abs(mx.Y - my.Y);
                double distance = Math.Sqrt(dx * dx + dy * dy);
                return mx == my || distance < 5 && distance > 0;
            })).ToList();
        \end{lstlisting}
  \caption{Linq code that filters contours by center of mass.}
  \label{fig:impl_filtering_contours}
\end{figure}

After that, filtered contours are checked for having the same angle to the horizon. With 9 distinct contours under the same angle it is supposed that 9 face's pieces are found. They form a cube face thus it is needed to find 4 extremums of the group that are supposed to be face's corners. If some points appear to be the same or to close then additional filtering logic is applied. It is needed to extract the found face thus $FaceExtractor$ utility class is called to extract \ac{OpenCV} $Mat$ class containing extracted and transformed in perspective face's image. With the help of $FaceUniquenessDetector$ utility class the extracted $Mat$ object is checked for its originality.

\begin{figure} [!ht]
\centering
\lstset{style=sharpc}
    \begin{lstlisting}
    Mat faceHsv = face.CvtColor(ColorConversionCodes.BGR2HSV);
    Mat faceHistogram = new Mat();
    Cv2.CalcHist(new Mat[] { faceHsv }, channels, new Mat(), faceHistogram, 2, histSize, ranges, true, false);
    Cv2.Normalize(faceHistogram, faceHistogram, 0, 1, NormTypes.MinMax, -1, new Mat());
    \end{lstlisting}
\caption{OpenCV code to calculate histogram.}
\label{fig:impl_fcalc_hist}
\end{figure}

It is done with \ac{OpenCV} $Cv2.CalcHist$ and $Cv2.CompareHist$ methods (figure \ref{fig:impl_fcalc_hist}), in short. If the correlation between the current face and any of the previous ones is too high, the current face is not unique. The last step is extracting colors from unique faces and forming some data structure to pass it to the next stage. $ColorsExtractor$ utility class is used to extract colors, see figure \ref{fig:impl_extract_color}.

\begin{figure} [!ht]
\centering
\lstset{style=sharpc}
    \begin{lstlisting}
    Mat sub = new Mat(face, new Rect(i * subWidth, j * subHeight, subWidth, subHeight));
    var intensity = sub.At<Vec3b>(centerX, centerY);

    byte blue = intensity.Item0;
    byte green = intensity.Item1;
    byte red = intensity.Item2;
    \end{lstlisting}
\caption{OpenCV code to extract RGB data.}
\label{fig:impl_extract_color}
\end{figure}

It has to segment a face into specified (in the configuration) number of pieces and take color probe from the center pixel of each piece in order to convert it to the .NET $Color$ class. Later this colors are compared to six possible cube face colors and converted to the closest to them using $ClosestColorHue$ of $ColorsExtractor$, see figure \ref{fig:impl_hue_color}.

\begin{figure} [!ht]
\centering
\lstset{style=sharpc}
    \begin{lstlisting}
    public static Color ClosestColorHue(Color target)
    {
        var hue1 = target.GetHue();
        var diffs = Colors.Select(n => GetHueDistance(n.GetHue(), hue1));
        var diffMin = diffs.Min(n => n);
        var index = diffs.ToList().FindIndex(n => n == diffMin);
        return Colors[index];
    }
    \end{lstlisting}
\caption{{\Charp} code that computes cube's color from the detected color.}
\label{fig:impl_hue_color}
\end{figure}

Finally, extracted colors are sent to be mapped to the Rubik's cube operational and rendering models.
On the other hand, \ac{PTAM} was another implemented algorithm but since its code was initially written in C++ and some currently unsupported libraries it was decided to write another simplified version of \ac{PTAM}. It does not allow to track key points when they are out of the view however while camera sees them everything is as designed. All main stages are included. \ac{PTAM} like approach is implemented in $RubiksCube.OpenCV.TestCase$ $PtamLileAlgorithm$ class split into 3 main stages: bootstrapping, bootstrap tracking and tracking. The most interesting for extraction stage is bootstrap tracking logic. Firstly, it computes optical flow with $CvInvoke.CalcOpticalFlowPyrLK$, then it validates if enough key points survived optical flow (see figure \ref{fig:impl_calc_optical_flow}).

\begin{figure} [!ht]
\centering
\lstset{style=sharpc}
    \begin{lstlisting}
CvInvoke.CalcOpticalFlowPyrLK(prevGray, currGray, Utils.GetPointsVector(trackedFeatures), corners, status, errors, new Size(11, 11), 3, new MCvTermCriteria(30, 0.01));
if (CvInvoke.CountNonZero(status) < status.Size * 0.8)
    throw new Exception("Tracking failed.");
    \end{lstlisting}
\caption{EmguCV code that computes Optical Flow.}
\label{fig:impl_calc_optical_flow}
\end{figure}

Homography validation follows next to check how many key points survived at the current step in comparison with the initial value. If the value fails threshold, the process is considered to be failed. Secondly, stereo vision approaches are used. The implemented solution estimates the rigid transformation with $CvInvoke.EstimateRigidTransform$ to validate camera motion between bootstrapped image and the currently observed. If the motion is sufficient it performs points triangulation. It is very interesting process, implemented in $OpenCvUtilities$ class. It finds fundamental matrix with $CvInvoke.FindFundamentalMat$ (see figure \ref{fig:impl_fundamental_matrix}) and checks how many key points survived.

\begin{figure} [!ht]
\centering
\lstset{style=sharpc}
    \begin{lstlisting}
    Mat f = new Mat();
    VectorOfByte status = new VectorOfByte();
    CvInvoke.FindFundamentalMat(trackedFeaturesPts, bootstrapPts, f, FmType.Ransac, 0.006 * maxVal, 0.99, status);
    var fMat = new Matrix<double>(f.Rows, f.Cols, f.DataPointer);
    int inliersNum = CvInvoke.CountNonZero(status);
    \end{lstlisting}
\caption{EmguCV code that computes fundamental matrix.}
\label{fig:impl_fundamental_matrix}
\end{figure}

Afterwards, essential matrix is computed from the intrinsic camera parameters and fundamental matrix. Essential matrix is decomposed with \ac{SVD} (see figure \ref{fig:impl_svd}) and two rotation matrices and two translation vectors are produced. These results are mixed into four possible projection matrices. To check what projection matrix is correct the triangulation procedure is run until the matrix is found.

\begin{figure} [!ht]
\centering
\lstset{style=sharpc}
    \begin{lstlisting}
    CvInvoke.SVDecomp(e, w, u, vt, SvdFlag.ModifyA);
    r1 = u * wMat * vt;
    r2 = u * wMatTranspose * vt;
    um.GetCol(2).CopyTo(t1);
    um.GetCol(2).CopyTo(t2);
    \end{lstlisting}
\caption{EmguCV's SVD.}
\label{fig:impl_svd}
\end{figure}

This process is also very important, at this point 3D points are projected back to the image and re-projection error is computed. This error helps to understand how many points have survived and successfully been triangulated. Hence, they can be used for tracking. Finding 3D points is important because the aim is to find information about face's plane in 3D space.

\begin{figure} [!ht]
\centering
\lstset{style=sharpc}
    \begin{lstlisting}
    Mat projected = new Mat();
    CvInvoke.PCAProject(trackedFeatures3Dm, mean, eigenvectors, projected);
    var projectedMatrix = new Matrix<double>(projected.Rows, projected.Cols, projected.DataPointer);
    projectedMatrix.GetCol(2).SetValue(0);
    projectedMatrix.CopyTo(trackedFeatures3Dm);
    \end{lstlisting}
\caption{EmguCV's PCA.}
\label{fig:impl_pca}
\end{figure}

With the help of \ac{PCA} using $CvInvoke.PCACompute$ (see figure \ref{ig:impl_pca}) it finds eigenvectors and mean of the known 3D point matrix. Afterwards, \ac{PCA} of $Accord$ library is used because $EmguCV$ does not return eigenvalues. Retrieved data is used to find planes normal and its inliers (3D points that lie in the same plane). Described analysis is what was needed for extraction logic.

\subsubsection*{Tracking}

\ac{PTAM} like approach makes tracking possible. In comparison with bootstrap tracking of a plane simple tracking is done much easier. It also uses optical flow with the same code base as in the previous step. The difference is that it does not need to triangulate points again. It uses already found 3D points and their 2D positions on the current image.

\subsubsection*{Mapping}

Extracted colors should be mapped to the cube model in order to solve and render it. Data is mapped to $ScrarchEngine.Libraries.RubiksCube.Models.RubiksCubeModel$ class that represents a Rubik's cube in the project. This model has multiple methods for rotating cube's layers, flipping it or checking for cubes consistency. The mapping also includes face orientation analyses implemented through the iterative face orientation checkup. Faces positions are simply determined on the basis of their central pixels relation.

\subsubsection*{Solving}

Beginner solving algorithm was implemented to solve any 3 by 3 Rubik's cube. $BeginnerSolver$ class is inherited from $BaseSolver$ thus new solver can be easily created and applied. To simplify and replace solution hard-coding the declarative \ac{JSON} structure was created. Solution formulas now could be written in \ac{JSON} where the name of the formula, its phase, state that should be to run the formula and moves are written in the specific globally known notation.

\begin{figure} [!ht]
  \centering
    \lstset{style=sharpc}
        \begin{lstlisting}
            [
               {
                    "Name": "Up Front cubie on right|front",
                    "Phase": "FirstCross",
                    "IsFinal": true,
                    "StateFrom": {
                      "Right": [
                        [ null, null, null ],
                        [ "Up", null, null ],
                        [ null, null, null ]
                      ],
                      "Front": [
                        [ null, null, null ],
                        [ null, null, "Front" ],
                        [ null, null, null ]
                      ]
                    },
                    "Moves": "F"
                  },
            ]
        \end{lstlisting}
  \caption{Example of json formula declaration.}
  \label{jsonsolformuladecl}
\end{figure}

As can be seen from the listing \ref{jsonsolformuladecl} the state is declared as face's 2-dimensional array. This array should contain related face's names at specific positions. For instance, from the above listing, Up-Front cubie is on the Right-Front sides thus it is written like this and if the cube front layer will be rotated clockwise the cubie will be placed where it should be. $IsFinal$ flag displays that this algorithm puts cubie in its place and no more formulas should be used after this. In other cases, the solver will run formulas until the cubie is in place.
On the other hand, this \ac{JSON} notation is not yet perfect, since algorithms are for humans, cube must be flipped and rotated to run formulas when handling cube at some specific position. Currently, it is necessary to write some code within the solver class inherited from $BaseSolver$ for specific algorithm stages or flips, they cannot be reflected in \ac{JSON} yet.

\subsubsection*{Rendering}

To render the cube self-written software rendering engine oriented on cube was used. $RenderingControl$ was created with inheritance from $UserControl$. This class includes rendering and mouse handling split into partial classes. This class encapsulates rendering and updating loops with abstract $Update()$ and $Render()$ methods used to write the logic of the game. Rendering control allows to zoom and rotate displayed image. To render the cube the $RubiksCubeModel$ is split into cubies, imitating real puzzle pieces and each of them is converted to the 3D cube while only visible pieces are colored (others are black). Every cube is rotated with respect to its position, it means with respect to layers containing it. These manipulations are performed in $GenerateCubes3D$ and the result is a list of 3D cubes with specific positions and rotations in 3D space. Afterwards, cubes are projected on the screen. At each step of update loop described transformation code is performed to translate $RubiksCubeModel$ to the list of polygons represented as $Face3D$ in order to be rendered with render loop.

\end{document}


% Due Date: 7/14/14

\chapter{A Full-Scale Production Application: S3D}
\label{chapter:s3d}

Instead of evaluating Legion on many small benchmark
applications, we decided to evaluate Legion on a single
full-scale production application. The reason for this
decision is two-fold.  First, evaluating Legion features
in isolation is difficult because many of them only make
sense within the context of a Legion implementation.
Testing our Legion implementation in an end-to-end fashion
at scale demonstrates that our design decisions lead
to an efficient implementation and that all components
of Legion operate in concert to achieve high performance.

Our second reason for performing an end-to-end evaluation
of Legion at scale is that evaluating benchmarks at
smaller scales often fails to translate to high performance
for applications run over thousands of nodes
on real machines. At such scales, many features
of a system are tested and bottlenecks are discovered
that are not obvious at smaller scales. Due to this
phenomenon, we decided that a better evaluation of
the capability of Legion would be a comparison to
an existing application written using current tools
that has been developed and optimized by experts.
By performing a comparison at full production
scale, we would truly test the advantages of the
Legion programming model.

For our comparison application we selected S3D
\cite{S3D09}. S3D is a combustion simulation used
by researchers from the United States Department
of Energy to study the chemical and physical
properties of fuel mixtures for internal combustion
engines. S3D simulates the turbulent processes
involved in combustion by performing a direct
numerical simulation (DNS) of the Navier-Stokes
equations for fluid flow. The simulation for S3D
operates on regular Cartesian grid of points with
many values being stored on each point. The
application iterates through time using a six
stage, fourth order Runge-Kutta (RK) method. The
RK method requires that the {\em right-hand side
function} (RHSF) be evaluated six times per
time step, requiring considerable computational
resources. There are many (often independent)
phases involved in computing the RHSF function
for all points, resulting in considerable task-
and data-level parallelism.

While the framework of S3D is general, S3D is
parametrized by the kind of {\em chemical
mechanism} being simulated. A chemical mechanism
is constituted of a collection of species (molecules)
and reactions that govern the chemistry of the
underlying simulation. For actual combustion,
there are usually on the order of thousands of
species and tens of thousands of reactions.
Performing a computational simulation of a
mechanism with perfect fidelity is computationally
intractable. Instead, {\em reduced} mechanisms
are developed that represent tractable approaches
to simulating combustion. Much of the original
science done using S3D involved simulating the
{\tt H2} mechanism consisting of 9 chemical
species and 15 reactions. More recently S3D
is being used to simulate larger chemical
mechanisms. Figure~\ref{fig:s3dmech} shows
details of the chemical mechanisms used for
our experiments involving Legion. Each chemical
mechanism models a specific number of species
and reactions. In many cases, species with
similar behavior are aliased resulting in a
smaller number of {\em unique} species. In some
cases, certain groups of species need to appear
to be in a quasi-steady state, requiring a
quasi-steady state approximation (QSSA). Additional
computation will be required for QSSA species.
Stiff species are those whose rates of change are
often volatile and are therefore subject to
additional damping computations.

\begin{figure}
\centering
\begin{tabular}{c|ccccc}
Mechanism & Reactions & Species & Unique & QSSA & Stiff \\ \hline
DME       &  175      &  39     &   30   &  9   &  22   \\
Heptane   &  283      &  68     &   52   &  16  &  27   \\
PRF       &  861      &  171    &   116  &  55  &  93   \\
\end{tabular}
\caption{Summary of Chemical Mechanisms Used in
Legion S3D Experiments\label{fig:s3dmech}}
\end{figure}

S3D has been developed over the course of thirty
years by a number of scientists and engineers.
There are currently two primary versions of S3D.
The first version of S3D is the baseline version
developed primarily by the scientists and is
used for active research. This version consists
of approximately 200K lines of Fortran code and
uses MPI \cite{MPI} for performing inter-node
communication when necessary. The choice of
Fortran as the base language for S3D has allowed
scientists to take advantage of the many advances
made by Fortran compilers (developed by both
Cray and Intel) for generating both multi-threaded
and vectorized code. Many of the larger computational
loops are automatically partitioned across threads
and auto-vectorized leading to good performance
on homogeneous CPU-only clusters. While this version
of S3D was sufficient for performing science on
traditional clusters, it is challenging to scale
to modern machines and is currently unable to take
advantage of the heterogeneous processors (e.g. GPUs)
available on most modern supercomputers.

The second version of S3D developed more recently
combines MPI with OpenACC \cite{OpenACC} to target
modern heterogeneous supercomputers \cite{S3DACC12}.
This version of S3D was ported from the baseline
version by a team consisting of both scientists
as well as engineers from Cray and NVIDIA. By
leveraging both CPUs and GPUs, this version of S3D
was made considerably faster than the baseline
version of S3D. Due to its higher performance
we chose this version of S3D to serve as our
baseline for performance comparisons with Legion.

In order to avoid porting all 200K lines of S3D
into Legion, we decided instead to port the RHSF
function to Legion and leave the remaining
start-up/tear-down code as well as the RK loop
in the original Fortran. The RHSF function represents
between 95-97\% of the execution for a time step
in S3D (depending on chemical mechanism and
hardware), thereby representing the bulk of S3D's
computational workload. Ultimately we ported
approximately 100K lines of Fortran into Legion
C++ code. By only porting a portion of S3D into
Legion, we also showcase Legion's ability to
act as a library capable of inter-operating with
existing MPI code. By developing a path for
inter-operability we also demonstrate an
evolutionary path for applications to be ported
into Legion that does not require all code to
be moved into Legion.

The rest of this chapter describes our implementation
of S3D in Legion. We begin by describing the
machine-independent implementation of the S3D in
Legion based on logical regions and tasks in
Section~\ref{sec:s3dimpl}. In this section we
also describe how Legion is able to inter-operate
with MPI so only a portion of S3D is required to
be ported into Legion. We cover the details of
how the Legion mapping interface allowed us to
experiment with different mapping approaches in
Section~\ref{sec:s3dmap}. Finally, we illustrate
the performance benefits of Legion when compared to
MPI and OpenACC in Section~\ref{sec:s3dperf}.

\section{S3D Implementation}
\label{sec:s3dimpl}
Our Legion implementation of the RHSF function in
S3D operates differently from a stand-alone Legion
application. Since most of the S3D code for starting
and analyzing an S3D run is in MPI-Fortran, we use
MPI to start-up a separate process on each
node (in contrast to having GASNet start-up a process
on each node for the normal Legion initialization procedure).
Our Legion implementation of S3D is implemented as a
library and we add a Fortran call into our library
that triggers the initialization of the necessary
data structures on each node. Consequently, Legion
is initialized within the same process as MPI. While
this is less than an ideal situation (we would have
preferred cooperating processes with isolation),
alternative approaches are limited by the poor quality
of software tools (e.g. mpirun and aprun) for
supporting cooperating jobs with different binaries.

\subsection{Interoperating with Fortran}
\label{subsec:interop}
The call to initialize the Legion runtime triggers
the execution of the top-level task for our S3D Legion
application. Unlike a standard Legion application, our
top-level task for S3D doesn't immediately start
execution of S3D. Instead it begins by launching a
sub-task on every processor in the Legion system that
synchronizes with the MPI process on the target node.
These sub-tasks synchronize with the MPI thread in
each process and determine the mapping from Legion
processors (and therefore memory and nodes) to MPI
processes. This mapping is necessary for ensuring
proper interoperation with MPI. Further sub-tasks
are then launched to distribute the mapping result
to each of the different mappers within the system.

After computing and distributing the mapping of
Legion processors to MPI ranks, the top-level task
prepares to launch a separate sub-task for each
of the different MPI ranks. We refer to these
different sub-tasks as {\em distributed} sub-tasks.
Whereas normal Legion tasks actively execute an
application, these tasks instead are long-running
tasks that are responsible for synchronizing with
the MPI ranks of S3D and only performing the RHSF
functions for a time step when directed to do so by
the MPI code. It is often the case that these
distributed sub-tasks need to communicate with each
other for exchanging information such as ghost
cell data. To support this, the top-level task
creates explicit ghost cell regions (that we describe
in more detail in Section~\ref{subsec:s3dghost}) and uses
simultaneous coherence in conjunction with a must epoch
index space task launch to ensure that all the task are
executed at the same time (see
Section~\ref{sec:mustepochs} for details on must
epoch task launches).

Each distributed sub-task begins execution by
creating logical regions for storing the necessary
simulation data. We cover the the creation of
these regions in further detail in
Section~\ref{subsec:rhsfregs}. Once these regions
are created, each of the distributed sub-tasks
launches an {\tt AwaitMPI} sub-task that is
responsible for synchronizing with the MPI code
and copying in data from Fortran arrays into
logical regions. To perform the synchronization,
each distributed sub-task creates a {\em handshake}
object that mediates coordination between MPI and
Legion. For each time step of an S3D simulation
there are two handshakes between Legion and MPI.
In the first handshake, MPI signals to the
{\tt AwaitMPI} task that it is safe to begin
executing a time step. As part of this handshake
the {\tt AwaitMPI} task also receives pointers to
the Fortran array in the local rank containing data
that needs to be copied over to logical regions.
The {\tt AwaitMPI} sub-task requests privileges
for writing into the target logical regions,
allowing the distributed sub-tasks to run ahead
launching additional sub-tasks that will naturally
wait based on region dependences for the
{\tt AwaitMPI} task to finish.

The second handshake occurs after a time step
has completed.  The MPI rank will block waiting
on the second handshake from the Legion side of
the application. At the end of a time step, each
distributed sub-task launches a {\tt HandoffToMPI}
task that requests read-only privileges the necessary
logical regions containing state. Naturally, Legion
dependence analysis ensures these tasks do not run
until all data dependences have been satisfied.
When run, the {\tt HandoffToMPI} tasks copy data
from logical regions back to Fortran arrays and
then completes the handshake by signaling to the
Fortran side, that it is safe to continue execution.

The handshaking model is an effective one that
allows for part of an application to be ported to
Legion without requiring that all code be transitioned.
The down-side to this approach is that either all
of the computational resources of the machine are
being used for performing Legion work or MPI work,
but never both at the same time. For some future
applications it may be beneficial to provide a means
for taking advantage of parallelism between both
Legion and MPI computations simultaneously.

While the handshaking model is currently performed
using an approach that is specific to S3D, we believe
that it can be easily generalized to additional
existing MPI codes. Further support by the Legion
runtime for automatically computing the mapping
between processors and MPI ranks would greatly aid
in porting applications to Legion. In the future,
we plan to provide direct support for MPI and
Legion interoperability based on experiences with S3D.

\subsection{Explicit Ghost Regions}
\label{subsec:s3dghost}
In order to provide a communication substrate for
exchanging ghost cell data between distributed tasks,
our Legion implementation uses explicit ghost cell
regions mapped with simultaneous coherence. S3D has
a straight-forward nearest neighbors communication
pattern between each rank. Each neighbor must
communicate ghost cell information with its six
adjacent neighbors (two in each dimension). Based
on this communication pattern, our Legion implementation
creates six ghost cell logical regions for each of
the distributed tasks.

The ghost cell logical regions are much smaller than
the logical regions that will be created to store
the state of the simulation for each distributed
task (see Section~\ref{subsec:rhsftasks}). For the
general S3D simulation, most ghost cell regions need
only be four cells deep (for fourth-order stencils)
on each face. Each explicit ghost cell region only
needs to allocate fields in its field space for
fields that will be the subject of stencil
computations. In practice this normally is on the
order of three times the number of species as exist
in the mechanism (there are three primary stencil
phases in S3D). Since all explicit ghost cell regions
are used for the same stencils, they can all share
the same field space.

In addition to creating explicit ghost cell regions,
the top-level task also creates phase barriers
(see Section~\ref{subsec:phasebarriers}) for
synchronizing ghost cell exchange between different
distributed tasks. Two phase barriers are created for
every field on each explicit ghost cell region. The
first phase barrier is used to describe when a field
has been written by the producer distributed
task. The second phase barrier is used for communicating
that the results have been finished being used by
the consumer task and it is safe to write the next
version of the ghost cells. Both phase barriers are
registered as having a single producer necessary to
trigger the barrier. Unlike MPI barriers, Legion phase
barriers are first class objects that are stored in
their own logical region. Each distribute task
also receives privileges on the phase barrier regions
necessary for synchronization of its sub-task operations.

When the distribute tasks are launched, projection
region requirements are used for computing which explicit
ghost cell regions are assigned to each point task. Each
distributed task receives twelve ghost cell regions: the
six that it owns as well as the six from its corresponding
neighbors. Simultaneous coherence is used to remove any
interference between the different sub-tasks. A must epoch
launch is performed to guarantee that all of the tasks
are executing at the same time, thereby ensuring that
phase barriers can be used for synchronization between
the distributed tasks.

\subsection{RHSF Logical Regions}
\label{subsec:rhsfregs}
When the distribute tasks initially begin running
they first create logical regions for storing the state
necessary for running S3D. Each distribute task creates
four local logical regions for storing state: a
region $r_q$ for storing the input state, a region
$r_{rhs}$ for storing the output state, a region
$r_{state}$ for storing state that it is iteratively
preserved between time steps, and a region $r_{temp}$
that stores temporary data used within each time
step. Each of these regions is sized by a three
dimensional index space of the same size as the
Fortran code (usually with $48^3$, $64^3$, or
$96^3$ elements). While each of these logical regions
persists throughout the duration of the distributed
tasks, they are commonly represented by many different
logical sub-regions.

Each of the different state logical regions for a
distributed task have different field spaces. The
$r_q$ and $r_{rhs}$ regions have the smallest field
spaces containing $N+6$ fields where $N$ is the
number of species in the chemical mechanism being
simulated. The $r_{state}$ and $r_{temp}$ logical
regions contain between hundreds and thousands of
fields for storing all the temporary values created
as part of the execution of an S3D time step. For
example, the $r_{temp}$ logical region requires
630, 1048, and 2264 fields for the DME, Heptane,
and PRF mechanisms respectively. The number of
fields required for these logical regions motivated
many of the optimizations discussed in
Chapters~\ref{chapter:logical} and
\ref{chapter:physical} for optimizing the representation
of fields with field masks.

Each of the distributed tasks also partition each of
the four state logical regions in two different ways.
First, a disjoint partition is made of each logical
region for describing how to partition cell data for
assignment to different CPUs within the local node.
The second partition is also a disjoint partition that
describes how to break up data for each of the
different GPUs available within a node. Both partitioning
schemes are performed using tunable variables
(see Section~\ref{subsec:tunablevars}) for selecting
the number of sub-regions in each partition. Note
that because each of the four state logical regions
use the same index space, the two partitions only need
to be computed once and the necessary sub-regions already
exist for each of the different state logical regions.

\subsection{RHSF Tasks}
\label{subsec:rhsftasks}
After each of the distribute tasks are initialized they
begin launching sub-tasks for performing time steps.
Each time step begins with the launch of an {\tt AwaitMPI}
task that will block waiting for synchronization with
the MPI side of the computation. Each {\tt AwaitMPI} task
requests privileges on the $r_q$ logical region and its
fields, ensuring that other tasks that depend on this
data cannot begin running until data is copied from the
Fortran arrays into the $r_q$ logical region by the
{\tt AwaitMPI} task. The distributed tasks continue
executing and in the process launch hundreds of sub-tasks for
each time step. Each sub-task names different logical regions
and fields with various privileges that it requires to
execute. Based on region usage, field usage, and privileges
the Legion runtime automatically infers considerable task
and data level parallelism. At the end of each time step,
the distributed task also issues a {\tt HandoffToMPI} task
to synchronize again and pass both data and control back
to the MPI Fortran part of S3D. The natural back pressure
applied by the Legion runtime by controlling the maximum
number of outstanding tasks in a context and the back
pressure of the mapping process all limit how far the
distributed task can run in advance of actual
application execution.

When stencil computations are performed, the distributed
tasks use explicit region-to-region copy operations to
perform the data movement between the state logical regions
and instances of the explicit ghost logical regions on
remote nodes. Phase barrier triggering is directly tied to
the result of the copy, ensuring that it too is performed
asynchronously. When using the explicit ghost cell regions
to perform stencil computations, acquire and release operations
are employed to remove any restrictions on mapping decisions
associated with the use of simultaneous coherence (see
Section~\ref{subsec:relaxedcompose}). The second phase barrier
for marking that it is safe to issue the next copy operation
on each field is also triggered as part of the completion
of the release operation for a given field. The computation
of each stencil therefore directly mirrors the simple
stencil example shown in Figure~\ref{fig:stencilex} from
Section~\ref{sec:completeex}.

Tasks that are independent of any specific chemical
mechanism are represented as separate classes in C++. Each
task class represents a different kind of task and
static member functions are used to provide the implementation
of different variants of the code. The static nature of
the tasks reflects that tasks in Legion can be written in
an imperative language, but are primarily functional with
side-effects on logical regions. Task classes also have
other static member functions explicitly used for registering
task variants as well as for constructing region requirements
and launching sub-tasks. This approach results in very
modular code where all the components of a Legion task
including the registration, launching, and implementation
are all co-located. When contrasted with the original
MPI-Fortran code, Legion code is significantly easier to
both read and maintain.

While many of the tasks in S3D are independent of the
chemical mechanism or easily parametrized by the number
of fields, some task implementations are dependent upon
the chemical mechanism. For these tasks we developed a
simple DSL compiler called Singe that takes as input
combustion specific files (a CHEMKIN reaction file and
two files containing tables of thermodynamic and transport
coefficients for different species) and generates optimized
implementations of the necessary kernels for both CPUs
and GPUs. The Singe compiler performs many interesting
optimizations that are beyond the scope of this
thesis \cite{Singe14}.

\section{S3D Mapping}
\label{sec:s3dmap}
In Chapter~\ref{chapter:intro}, we claimed that decoupling
an application's specification from how it is mapped to
a target architecture is important for both performance
and portability. S3D is an excellent example of an
application that showcases the need for this decoupling.
The dynamic dependence graph for S3D is sufficiently
complex that it would be very difficult for any human
programmer to directly pick the best mapping of tasks
onto CPU and GPU processors on their first or even
second guess. By using the explicit mapping interface
provided by Legion, we were able to explore more than
100 different mapping possibilities for each combination
of chemical mechanism and target architecture in order to
find the best performing versions. As we will shortly
see, the best mapping for S3D depends directly upon the
machine being targeted.

The first step in mapping S3D is to compute the mapping
for the distributed tasks to processors on different
nodes. We compute the mapping of these tasks based on
the relationship between processors and MPI ranks. We
send each distributed task to a processor on the node
with the same MPI rank ID as the point for the distributed
task in the index space task launch. We also
are careful about mapping region instances so that we
satisfy all the restricted constraints on explicit
ghost regions for the must epoch task launch. In general
we attempt to map all of the physical instances for
the explicit ghost regions into {\em registered memory}
(pinned memory accessible directly by NIC hardware for
performing one-sided asynchronous sends and receives)
and fall back to {\em system memory} (e.g. DRAM) when
space is not available. In some cases, the explicit
ghost cell regions are actually mapped into memories
that are not directly visible from the processor
running the distributed tasks. The runtime permits
this behavior because the application sets a flag
indicating that the distributed task implementations
will never request accessors to these regions, but
instead only access them using explicit
region-to-region copies.

One downside to inter-operating with MPI is that
there are cases where mapping decisions can impact
correctness. For example, failing to map distributed
tasks to a processor on the node with the corresponding
MPI rank can result in incorrect exchanges of ghost
cell data. This is an unfortunate consequence of
inter-operability. When an application is entirely
contained within Legion, we can guarantee that mapping
decisions do not impact correctness. However, when
inter-operating with another programming system,
mapping decisions must be made in such a way as to
align with the implicit mapping decisions made in the
other programming system.

As the distribute tasks begin running, they start
performing time steps and launching sub-tasks for each
of the different phases of an S3D time step. The mapping
decisions made for these many sub-tasks strongly impact
the ultimate performance of an S3D run. However, the
complex nature of the dependence graph makes it very
difficult to easily infer the best mapping decisions.
Specifically, it is very difficult to determine which
tasks should be assigned to CPUs and which should be
scheduled on the GPUs. Furthermore, determining the
best placement of data is not entirely obvious. GPU
framebuffers are regularly much smaller than a node's
system memory, requiring that applications with larger
working sets actively manage which data is placed
in the framebuffer. To explore these many trade-offs
we relied heavily on the programmability afforded by
the Legion mapping interface.

To test different mapping strategies, we developed
a collection of specialized mappers, each of which
deployed a different mapping strategy for assigning
tasks to CPUs and GPUs as well as assigning data
to either the system memory on the CPU-side of the
PCI-E bus or the framebuffer memory on the GPU-side
of the PCI-E bus. In general, we found that there
was one particular set of fields whose
placement significantly impacted the performance
of a mapping scheme. The decision about whether to
place the derivatives of the diffusive flux fields
on the CPU-side or GPU-side of the PCI-E express
bus tended to dictate the mapping of the tasks
that depend on them. There are $3N$ diffusive flux
derivatives in the number of species per cell,
requiring a considerable amount of memory to store
regardless of the problem size. In general, we
found that there was insufficient work to hide the
latency of moving these fields across the PCI-E
bus. Therefore, all three of the different chains
of dependent tasks that require the diffusive
flux derivatives were always executed on the
the same side of the PCI-E bus as where the
values were generated.

\begin{figure}
\centering
\includegraphics[scale=0.8]{figs/MixedMapping.pdf}
\caption{Example Mixed Mapping Strategy for S3D on a Titan Node\label{fig:mixedmap}}
\end{figure}

Ultimately, we referred to these two different
mapping approaches for S3D as {\em mixed} and
{\em all-GPU} mapping strategies. Figures~\ref{fig:mixedmap}
and \ref{fig:allgpumap} illustrate the differences
for the mixed and all-GPU mapping strategies
respectively. Each picture shows the performance of
the utility processors, CPUs, and GPUs on a single
Titan node for one RHSF invocation of the Heptane
mechanism\footnote{Interestingly, in the case of
the utility processors, they are actually performing
the dynamic analysis for the RHSF invocation that
occurs two steps later in the Runge-Kutta method.
This demonstrates the ability of Legion's deferred
execution model to permit the runtime to perform
analysis well in advance of where the actual
application is executing.}. In the mixed
strategy, the diffusive flux derivatives are computed
on the CPU-side of the PCI-E bus, leading to the
majority of the tasks that depend on those values
to also be mapped to CPU processors. Only the most
computationally expensive kernels (e.g. transport
and chemistry kernels) are mapped to the GPU. While
this leads to a relatively balanced workload between
CPUs and GPUs (depending on the relative performance
between the CPUs and GPUs), in general, the CPUs
are always busy while the GPUs are under-loaded.
The alternative approach is to map the diffusive
flux derivative computations onto GPU processors,
which generates the values in the framebuffer. This
then moves the majority of dependent tasks down
to the GPU. Since both these tasks as well as the
computationally expensive tasks are all on the
GPU, the GPU processors are much more heavily
loaded, while the CPU processors have very few
tasks to perform (hence the all-GPU mapping name).

\begin{figure}
\centering
\includegraphics[scale=0.7]{figs/AllGPUMapping.pdf}
\caption{Example All-GPU Mapping Strategy for S3D on a Titan Node\label{fig:allgpumap}}
\end{figure}

Importantly, one commonly observed problem when
mapping code to accelerators also occurs in S3D.
In many cases, problem sizes are sometimes too
large to fit in the limited amount of framebuffer
memory for an accelerator\footnote{As of the writing
of this document, most accelerators have between
6 and 12 GB of either DRAM or GDDR5 memory.}. For
many codes, this will result in crashes due to
out-of-memory errors. However, in the case of
Legion, it is easy to adjust to new larger
problem sizes with dynamic mapping strategies.
Figure~\ref{fig:largemap} shows an approach to
mapping a $96^3$ cells per node Heptane problem onto
a Titan node. Only a limited number of tasks can
be mapped to the GPU as there is limited space in
the 6 GB framebuffer memory. Under this scenario,
the field-aware nature of Legion is crucial. Legion
understands precisely which fields are necessary for
executing the tasks mapped to the GPU, which means
only those fields are moved down to the GPU
framebuffer. The mapper can therefore dynamically
manage the working set of the GPU and ensure that
the code can run unlike the case today where
significant refactoring would be required.

\begin{figure}
\centering
\includegraphics[scale=0.7]{figs/LargeMapping.pdf}
\caption{Mapping Strategy for a Large S3D Problem Size\label{fig:largemap}}
\end{figure}

The crucial insight provided by our experience
mapping S3D is that we would never have discovered
either of these mapping strategies without the
decoupled nature of the Legion mapping interface.
We tried more than a hundred different mapping
implementations before settling on the two primary
approaches described above. The Legion mapping
interface provided the flexibility to try many
different mapping strategies without having to be
concerned with correctness. Furthermore, as we will
show in Section~\ref{sec:s3dperf}, the determination
of which mapping strategy performs better is
architecture dependent.

\section{Performance Results}
\label{sec:s3dperf}
In order to evaluate our implementation of S3D in
Legion, we ran experiments on two different
supercomputers: Keeneland \cite{Keeneland} and
Titan \cite{Top500}. Keeneland is a 250 node cluster
with an Infiniband interconnect. Each Keeneland
node contains 2 CPU sockets with an 8-core Intel
Sandybridge chip in each socket, 3 NVIDIA Fermi
M2090 GPUs, and 32 GB of DRAM partitioned between
the two sockets. Titan is the number two supercomputer
in the world (as of the writing of this document)
consisting of more than 18000 nodes with a Cray
Gemini Interconnect. Each Titan node has one CPU
socket with a 16-core AMD Interlagos chip, one
NVIDIA Kepler K20 GPU, and 32 GB of DRAM partitioned
across four primary Interlagos NUMA domains.
There is an interesting mismatch between CPU and
GPU pairings as we will see. The CPUs and GPUs
on Keeneland are relatively evenly matched, while
on Titan there is a difference of several generations
between the CPU cores and GPU cores. These differences
will show different performance under different
mapping strategies as we will observe.

For both or our target machines, we experimented
with three different chemical mechanisms (DME, Heptane,
and PRF) for three different problem sizes. The numerical
formulation of the S3D simulation is designed for
weak-scaling (keeping a fixed problem size per node
and trying to maintain uniform throughput per node).
For the DME and Heptane mechanisms, we experimented
with problem sizes of $48^3$, $64^3$, and $96^3$ cells
per node.  For the larger PRF mechanism we used smaller
problem sizes of $32^3$, $48^3$, and $64^3$ cells per
node. For different problem sizes, we also experimented
with each of our two mapping strategies.

% Re-ranking
To test for weak scaling we ran experiments starting
with one node and scaling up by powers of two. (Our
implementation of Legion S3D performs equally well
for node counts that are not powers of two.) For
Keeneland, we show scaling through 128 nodes, while
for Titan we show scaling through 8192 nodes. As a
baseline version, we use the combination OpenACC
and MPI version of S3D that was independently
hand optimized by engineers from NVIDIA and Cray
over the course of a year.

For all experiments run on 1024 nodes or more, we
found that a node re-ranking script was necessary
for taking into account network topology performance
effects. We use the genetic algorithm re-ranking script
described in \cite{GAMPI} to perform the re-ranking.
The script uses a genetic algorithm to discover
better assignments of ranks to nodes to minimize
latency for S3D (and applications with a nearest
neighbors communication pattern). While we could
have computed a topologically aware re-ranking in our
custom S3D Legion mappers, we use the same re-ranking script
for both MPI/OpenACC and Legion versions of S3D so
we can compare the latency hiding abilities of
both versions directly.

\begin{figure}
\centering
\includegraphics[scale=0.4]{figs/dme_scaling.pdf}
\caption{S3D Weak Scaling Performance for DME Mechanism\label{fig:dmescale}}
\end{figure}

Figures~\ref{fig:dmescale} and \ref{fig:heptscale}
plot the per-node throughput of the
DME and Heptane mechanisms respectively for several
different problem sizes on both the Titan and Keeneland
supercomputers. Higher lines show better performance
and flat lines are indicative of good weak scaling (tail-offs
are inefficiencies). For the Legion runs, performance at a
given problem size is shown for the best performing
mapping strategy. On Keeneland, the best mapping strategy
is to use the mixed CPU-GPU approach to leverage the
relatively balanced computational capabilities of the
CPUs and GPUs. On Titan, the best mapping strategy is
to use the all-GPU approach due to the extreme imbalance
between the CPUs and the GPUs: the Kepler K20 GPU is many
times more powerful than all the Bulldozer CPU cores combined.
One important detail is that because the MPI-OpenACC
version of the code effectively has its mapping hard-coded
to place the majority of work on the GPU, it is unable
to run a $96^3$ problem size without exhausting the
available memory in the GPU framebuffer.

\begin{figure}
\centering
\includegraphics[scale=0.4]{figs/hept_scaling.pdf}
\caption{S3D Weak Scaling Performance for Heptane Mechanism\label{fig:heptscale}}
\end{figure}

As we can see in Figures~\ref{fig:dmescale} and
\ref{fig:heptscale}, in general larger
problem sizes achieve higher throughput as both the MPI-OpenACC
and Legion versions of S3D can use the additional work to
better overlap computation and communication. The one
exception to this trend is with the $96^3$ problem size
for Legion on Titan. In this case, in order to fit the
problem size within a Titan node, we had to use the
mixed CPU-GPU mapping, which is not as efficient due to
the slow Bulldozer CPU cores. We therefore notice a fall
off in performance compared to the $64^3$ problem size.

Overall, Legion significantly outperforms the MPI-OpenACC
code. Between 1024 and 8192 nodes, when compared to the
MPI-OpenACC code, the Legion version of S3D is 1.71-2.33X
faster for the DME mechanism and 1.75-2.85X faster for
the Heptane mechanism. On the Heptane mechanism, Legion
does particularly well at discovering additional parallel
work and using it to better overlap computation and
communication (both inter-node as well as intra-node over
the PCI-E bus). Both the Legion and MPI-OpenACC versions
experience a falloff in performance at 8192 nodes. This
is due to the failure of the genetic algorithm re-ranking
script to fully explore the space of possible re-rankings
given a fifteen minute time limit. Interestingly, for the
Heptane mechanism, Legion is able to mitigate this effect
by discovering further work to hide the additional latency.
Note that this effect is even more pronounced for larger
problem sizes.

\begin{figure}
\centering
\includegraphics[scale=0.4]{figs/legion_dme_titan.pdf}
\caption{Mapping Strategies for the S3D DME Mechanism\label{fig:dmemap}}
\end{figure}

Figures~\ref{fig:dmemap} and \ref{fig:heptmap}
illustrate the performance of different
Legion mapping strategies for all problem sizes on Titan.
On Titan, the severe performance mismatch between the CPUs
and the GPUs results in the best mapping being to place as
much work as possible on the GPUs. In contrast, on Keeneland,
the best mapping strategy is always to evenly distribute work
between CPUs and GPUs to ensure that all processing elements
are fully utilized. Mismatches in processor capabilities are
just another form of heterogeneity that programmers need to
contend with as part of writing code for current and future
architectures. By leveraging the Legion mapping interface
we were easily able to deal with this form of heterogeneity
without needing to make any code changes to the machine
independent Legion code; we simply wrote different
mappers for Titan and Keeneland.

\begin{figure}
\centering
\includegraphics[scale=0.4]{figs/legion_hept_titan.pdf}
\caption{Mapping Strategies for the S3D Heptane Mechanism\label{fig:heptmap}}
\end{figure}

In addition to the performance gains on existing mechanisms,
Legion is also able to support the PRF mechanism that is much
larger than the DME and Heptane mechanisms currently supported
by the MPI-OpenACC code. Each new mechanism that is significantly
different in size or computational intensity requires the
MPI-OpenACC code to be refactored in order to tune for performance,
often necessitating many man hours of work. Our Legion version of
S3D requires no refactoring and only slight modifications
to the customized mapper (no more than 10 lines of code). (We
do use the Singe DSL compiler to generate new leaf task kernel
implementations for the additional chemistry, but the base
S3D code is unmodified.) Figure~\ref{fig:prfperf} shows performance results
for the PRF mechanism running on Titan for three different
problem sizes with different mapping options. Note that, unlike
smaller mechanisms, there is no performance cliff at 8192 nodes
for the PRF mechanism, as Legion is able to discover sufficient
work in the PRF mechanism to automatically hide all of the
communication latency. Being able to adapt to new mechanisms and
automatically scale with just a few changes to a custom mapper
truly illustrates the power of the Legion programming model.

\begin{figure}
\centering
\includegraphics[scale=0.4]{figs/legion_prf_titan.pdf}
\caption{Performance of Legion S3D for PRF Mechanism\label{fig:prfperf}}
\end{figure}

\section{Programmability}
\label{sec:s3dprogram}

The final criteria on which we evaluate our Legion implementation
of S3D is programmability. While this is qualitative metric, it
is an important one, as the cost of programmer productivity and
software maintenance can often exceed the cost of doing production
runs. In the process of tuning our Legion version of S3D for both
the Titan and Keeneland machines, we were able to try hundreds of
different mapping strategies all without needing to modify the
machine-independent specification of S3D. This demonstrates the
power of our core Legion design goal to decouple an application
specification from its mapping. In the future, we anticipate this
property will allow us to easily port S3D to new architectures
simply by developing new mapping strategies.


\chapter{Dynamic Causal Modeling for fMRI \label{Chap:DCM_fmri}}

\section{Theoretical background}
Dynamic Causal Modelling (DCM) is a method for making inferences about neural processes that underlie measured time series, e.g. fMRI data.  The general idea is to estimate the parameters of a reasonably realistic neuronal system model such that the predicted blood oxygen level dependent (BOLD) signal, which results from converting the modeled neural dynamics into hemodynamic responses, corresponds as closely as possible to the observed BOLD time series.  This section gives a short introduction to the theoretical background of DCM for fMRI; details can be found in \cite{dcm}.  Note that DCMs can be formulated, in principle, for any measurement technique.  Depending on the spatio-temporal properties of a given measurement technique, one needs to define an adequate state equation and an observation model. See Fig~\ref{dcm_fig1} for a summary of the differences between DCM implementations for fMRI and Event-Related Potentials (ERPs).

\begin{figure}[ht]
\begin{center}
\includegraphics[width=100mm]{dcm/Fig1}
\caption{\em A schematic overview of the differences between between the DCM implementations for fMRI and ERPs (as measured by EEG or MEG).  Whereas the state equation of DCM for fMRI is bilinear and uses only a single state variable per region, that for ERPs is more complex and requires 8 state variables per region.  Moreover, DCM for ERPs models the delays of activity propagation between areas.  At the level of the observation model, DCM for fMRI is more complex than DCM for ERPs.  While the former uses a non-linear model of the hemodynamic response that contains a cascade of differential equations with five state variables per region, the latter uses a simple linear model for predicting observed scalp data.\label{dcm_fig1}}
\end{center}
\end{figure}

As in state-space models, two distinct levels constitute a DCM (see Figure~\ref{dcm_fig2}).  The hidden level, which cannot be directly observed using fMRI, represents a simple model of neural dynamics in a system of $k$ coupled brain regions.  Each system element $i$ is represented by a single state variable $z_i$, and the dynamics of the system is described by the change of the neural state vector  over time.

The neural state variables do not correspond directly to any common neurophysiological measurement (such as spiking rates or local field potentials) but represent a summary index of neural population dynamics in the respective regions.  Importantly, DCM models how the neural dynamics are driven by external perturbations that result from experimentally controlled manipulations.  These perturbations are described by means of external inputs $u$ that enter the model in two different ways:  they can elicit responses through direct influences on specific regions (``driving'' inputs, e.g. evoked responses in early sensory areas) or they can change the strength of coupling among regions (``modulatory'' inputs, e.g. during learning or attention).

Overall, DCM models the temporal evolution of the neural state vector, i.e. , as a function of the current state, the inputs $u$ and some parameters  that define the functional architecture and interactions among brain regions at a neuronal level ($n$  denotes ``neural''):
\begin{equation}
\left[ \begin{array}{l}
  \dot{z}_1 \\
  \dot{z}_2 \\
  .. \\
  \dot{z}_k \\  \end{array} \right] = \dot{z}= \frac{dz}{dt} = F(z,u,\theta^n)
\end{equation}
In this neural state equation, the state $z$ and the inputs $u$ are time-dependent whereas the parameters are time-invariant. In DCM, $F$ has the bilinear form
 \begin{equation}
\dot{z}=Az+\sum_{j=1}^m u_j B_j z + Cu
\end{equation}
The parameters of this bilinear neural state equation, $\theta^n=\{A,B_1,...,B_m,C\}$, can be expressed as partial derivatives of $F$:
\begin{eqnarray}
A & = & \frac{\partial F}{\partial z} = \frac{\partial \dot{z}}{\partial z} \\ \nonumber
B_j & = & \frac{\partial^2 F}{\partial z \partial u_j} = \frac{\partial}{\partial u_j}\frac{\partial \dot{z}}{\partial z}  \\ \nonumber
C & = & \frac{\partial F}{\partial u}
\end{eqnarray}
These parameter matrices describe the nature of the three causal components which underlie the modeled neural dynamics:  (i) context-independent effective connectivity among brain regions, mediated by anatomical connections ($k \times k$ matrix $A$), (ii) context-dependent changes in effective connectivity induced by the $j$th input $u_j$ ($k \times k$ matrices $B_1$, ..., $B_m$), and (iii) direct inputs into the system that drive regional activity ($k \times m$ matrix $C$).  As will be demonstrated below, the posterior distributions of these parameters can inform us about the impact that different mechanisms have on determining the dynamics of the model.  Notably, the distinction between ``driving'' and ``modulatory'' is neurobiologically relevant: driving inputs exert their effects through direct synaptic responses in the target area, whereas modulatory inputs change synaptic responses in the target area in response to inputs from another area.  This distinction represents an analogy, at the level of large neural populations, to the concept of driving and modulatory afferents in studies of single neurons.

\begin{figure}[ht]
\begin{center}
\includegraphics[width=130mm]{dcm/Fig2}
\caption{\em Schematic summary of the conceptual basis of DCM.  The dynamics in a system of interacting neuronal populations (orange boxes), which are not directly observable by fMRI, is modeled using a bilinear state equation (grey box).  Integrating the state equation gives predicted neural dynamics ($z$) that enter a model of the hemodynamic response ($\lambda$) to give predicted BOLD responses ($y$) (green boxes).  The parameters at both neural and hemodynamic levels are adjusted such that the differences between predicted and measured BOLD series are minimized.  Critically, the neural dynamics are determined by experimental manipulations.  These enter the model in the form of ``external'' or ``driving'' inputs.  Driving inputs ($u_1$; e.g. sensory stimuli) elicit local responses directly that are propagated through the system according to the intrinsic connections.  The strengths of these connections can be changed by modulatory inputs ($u_2$; e.g. changes in cognitive set, attention, or learning).\label{dcm_fig2}}
\end{center}
\end{figure}

DCM combines this model of neural dynamics with a biophysically plausible and experimentally validated hemodynamic model that describes the transformation of neuronal activity into a BOLD response.  This so-called ``Balloon model'' was initially formulated by Buxton and colleagues and later extended by \cite{balloon}.  Briefly summarized, it consists of a set of differential equations that describe the relations between four hemodynamic state variables, using five parameters ($\theta^h$).  More specifically, changes in neural activity elicit a vasodilatory signal that leads to increases in blood flow and subsequently to changes in blood volume $v$ and deoxyhemoglobin content $q$.  The predicted BOLD signal $y$ is a non-linear function of blood volume and deoxyhemoglobine content. Details of the hemodynamic model can be found in other publications \cite{balloon}.
By combining the neural and hemodynamic states into a joint state vector x and the neural and hemodynamic parameters into a joint parameter vector $\theta=[\theta^n, \theta^h]^T$, we obtain the full forward model that is defined by the neural and hemodynamic state equations
\begin{eqnarray}
\dot{x} & = & F(x,u,\theta) \\ \nonumber
y & = & \lambda(x)
\end{eqnarray}
For any given set of parameters $\theta$ and inputs $u$, the joint state equation can be integrated and passed through the output nonlinearity $\lambda$ to give a predicted BOLD response $h(u,\theta)$.  This can be extended to an observation model that includes observation error $e$ and confounding effects $X$ (e.g. scanner-related low-frequency drifts):
\begin{equation}
y = h(u,\theta) + X \beta + e
\end{equation}
This formulation is the basis for estimating the neural and hemodynamic parameters from the measured BOLD data, using a fully Bayesian approach with empirical priors for the hemodynamic parameters and conservative shrinkage priors for the neural coupling parameters.

Details of the parameter estimation scheme, which rests on a Fisher scoring gradient ascent scheme with Levenburg-Marquardt regularisation, embedded in an expectation maximization (EM) algorithm, can be found in the original DCM publication (Friston et al. 2003).  In brief, under Gaussian assumptions about the posterior distributions, this scheme returns the posterior expectations $\eta_{\theta | y}$ and posterior covariance  $C_{\theta | y}$ for the parameters as well as hyperparameters for the covariance of the observation noise, $C_e$.

After fitting the model to measured BOLD data, the posterior distributions of the parameters can be used to test hypotheses about the size and nature of effects at the neural level.  Although inferences could be made about any of the parameters in the model, hypothesis testing usually concerns context-dependent changes in coupling (i.e. specific parameters from the $B$ matrices; see Fig.~\ref{dcm_fig4}).  As will be demonstrated below, at the single-subject level, these inferences concern the question of how certain one can be that a particular parameter or, more generally, a contrast of parameters, $c^T \eta_{\theta | y}$, exceeds a particular threshold  $\gamma$ (e.g. zero).

Under the assumptions of the Laplace approximation, this is easy to test ($\Phi_N$ denotes the cumulative normal distribution):
\begin{equation}
p(c^T \eta_{\theta | y} > \gamma) = \Phi_N \left(\frac{c^T \eta_{\theta | y} - \gamma}{c^T C_{\theta | y} c} \right)
\end{equation}
For example, for the special case $c^T \eta_{\theta | y} = \gamma$ the probability is $p(c^T \eta_{\theta | y} > \gamma)=0.5$, i.e. it is equally likely that the parameter is smaller or larger than the chosen threshold $\gamma$.
We conclude this section on the theoretical foundations of DCM by noting that the parameters can be understood as rate constants (units: $1/s = Hz$) of neural population responses that have an exponential nature.  This is easily understood if one considers that the solution to a linear ordinary differential equation of the form $\dot{z}=Az$ is an exponential function (see Fig. ~\ref{dcm_fig3}).
\begin{figure}[ht]
\begin{center}
\includegraphics[width=120mm]{dcm/Fig3}
\caption{\em A short mathematical demonstration, using a simple linear first-order differential equation as an example, explaining why the coupling parameters in a DCM are inversely proportional to the half-life of the modelled neural responses and are therefore in units of 1/s = Hertz.\label{dcm_fig3}}
\end{center}
\end{figure}

\section{Bayesian model selection \label{mc}}

A generic problem encountered by any kind of modeling approach is the question of model selection:  given some observed data, which of several alternative models is the optimal one?  This problem is not trivial because the decision cannot be made solely by comparing the relative fit of the competing models.  One also needs to take into account the relative complexity of the models as expressed, for example, by the number of free parameters in each model.

Model complexity is important to consider because there is a trade-off between model fit and generalizability (i.e. how well the model explains different data sets that were all generated from the same underlying process).  As the number of free parameters is increased, model fit increases monotonically whereas beyond a certain point model generalizability decreases.  The reason for this is ``overfitting'':  an increasingly complex model will, at some point, start to fit noise that is specific to one data set and thus become less generalizable across multiple realizations of the same underlying generative process.

    Therefore, the question ``What is the optimal model?'' can be reformulated more precisely as ``What is the model that represents the best balance between fit and complexity?''. In a Bayesian context, the latter question can be addressed by comparing the evidence, $p(y|m)$, of different models. According to Bayes theorem
\begin{equation}
p(\theta|y,m) = \frac{p(y|\theta,m)p(\theta|m)}{p(y|m)}
\end{equation}
the model evidence can be considered as a normalization constant for the product of the likelihood of the data and the prior probability of the parameters, therefore
\begin{equation}
p(y|m) = \int p(\theta|y,m) p(\theta|m) d\theta
\end{equation}
Here, the number of free parameters (as well as the functional form) are considered by the integration.  Unfortunately, this integral cannot usually be solved analytically, therefore an approximation to the model evidence is needed. One such approximation used by DCM, and many other models in SPM, is to make use of the Laplace approximation~\footnote{This should perhaps more correctly be referred to as a fixed-form variational approximation, where the fixed form is chosen to be a Gaussian. The model evidence is approximated by the negative free energy, $F$.}.

As shown in \cite{cdcm}, this yields the following expression for the natural logarithm ($ln$) of the model evidence ( $\eta_{\theta | y}$ denotes the posterior mean, $C_{\theta | y}$ is the posterior covariance of the parameters, $C_e$  is the error covariance, $\theta_p$ is the prior mean of the parameters, and $C_p$ is the prior covariance):
\begin{eqnarray}
ln p(y|m) & = & accuracy(m) - complexity (m) \\ \nonumber
& = & \left[ -\frac{1}{2} ln |C_e| - \frac{1}{2} (y-h(u,\eta_{\theta | y}))^T C_e^{-1} (y-h(u,\eta_{\theta | y}))\right] \\ \nonumber
& - & \left[ \frac{1}{2} ln |C_p| -\frac{1}{2}ln |C_{\theta | y}| + \frac{1}{2} (\eta_{\theta | y}-\theta_p)^T C_p^{-1} (\eta_{\theta | y}-\theta_p) \right]
\end{eqnarray}

This expression properly reflects the requirement, as discussed above, that the optimal model should represent the best compromise between model fit (accuracy) and model complexity.  The complexity term depends on the prior density, for example, the prior covariance of the intrinsic connections.

Two models can then be compared using the Bayes factor:
\begin{equation}
BF_{ij} = \frac{p(y|m_i)}{p(y|m_j)}
\end{equation}
Given uniform priors over models, the posterior probability for model $i$ is greater 0.95 if $BF_{ij}$ is greater than twenty.

This results in a robust procedure for deciding between competing hypotheses represented by different DCMs. These hypotheses can concern any part of the structure of the modeled system, e.g. the pattern of intrinsic connections or which inputs affect the system and where they enter. Note, however, that this comparison is only valid if the data $y$ are identical in all models.  This means that in DCM for fMRI, where the data vector results from a concatenation of the time series of all areas in the model, only models can be compared that contain the same areas. Therefore, model selection cannot be used to address whether or not to include a particular area in the model.  In contrast, in DCM for ERPs, the data measured at the sensor level are independent of how many neuronal sources are assumed in a given model.  Here, model selection could also be used to decide which sources should be included.

\section{Practical example}

The following example refers to the ``attention to visual motion'' data set available from the SPM web site\footnote{Attention to visual motion dataset: \url{http://www.fil.ion.ucl.ac.uk/spm/data/attention/}}. This data set was obtained by Christian Buchel and is described in \cite{buchel97}.

The archive contains the smoothed, spatially normalised, realigned, slice-time corrected images in the directory \texttt{functional}. The directory \texttt{structural} contains a spatially normalised structural image. All processing took place using SPM99, but the image files have been converted into NIfTI format.

Making a DCM requires two ingredients: (i) a design matrix and (ii) the time series, stored in VOI files.  The regressors of the design matrix define the inputs for the DCM.  Note that this means that the design matrix that is optimal for a given DCM is often somewhat different than the one for the corresponding GLM. DCM does not require the design matrix to be part of an estimated model, however. It just needs to be defined.

\subsection{Defining the GLM}
The present experiment consisted of 4 conditions: (i) fixation (F), (ii) static (S, non-moving dots), (iii) no attention (N, moving dots but no attention required), (iv) attention (A). The GLM analyses by Christian showed that activity in area V5 was not only enhanced by moving stimuli, but also by attention to motion.  In the following, we will try to model this effect in V5, and explain it as a context-dependent modulation or ``enabling'' of V5 afferents, using a DCM. First, we need to set up the GLM analysis and extract our time series from the results. In this example, we want to use the same design matrix for GLM and DCM, therefore we recombine the above regressors to get the following three conditions:
\begin{enumerate}
 \item \textbf{photic}: this comprises all conditions with visual input, i.e. S, N, and A.
 \item \textbf{motion}: this includes all conditions with moving dots, i.e. N and A.
 \item \textbf{attention}: this includes the attention-to-motion (A) condition only.
\end{enumerate}
Now we need to define and estimate the GLM. This is not the main topic of this chapter so you should already be familiar with these procedures, see \ref{Chap:fmri_spec} and \ref{Chap:fmri_est} for more information. Here are the relevant details for this data set that you need to set up the GLM:
\begin{itemize}
 \item The onsets for the conditions can be found in the file \texttt{factors.mat}. They are named \texttt{stat} (static), \texttt{natt} (no attention) and \texttt{att} (attention) and are defined in scans (not seconds). They are blocks of 10 TRs each.
 \item The TR is 3.22 seconds.
 \item There are 360 scans.
\end{itemize}

Let's specify a batch that will specify the model and estimate it.

\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 normalised T1 structural volume
  \item File \texttt{factors.mat}.
  \item You will also need to make a new directory called \texttt{GLM} that will contain the analysis.
 \end{enumerate}
 \item In \matlab\ type
\begin{verbatim}
>> cd GLM
>> spm fmri
\end{verbatim}
 \item From the main SPM window, click on the \textsc{Batch} button.
 \item From the SPM menu at the top of the Batch Editor, select ``Stats $>$ fMRI model specification''.
 \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 Click \textsc{Data \& Design}, Choose \textsc{New "Subject/Session"}
 \item Click \textsc{Scans} and choose all the functional scans \texttt{snffM00587\_00xx.img}. There should be 360 \texttt{*.img} files.
 \item Load the MAT-file containing the individual conditions in \matlab\ workspace:
\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 Create 3 \textsc{New: Condition} under \textsc{Conditions} so that:
 \begin{itemize}
  \item Condition 1: \textsc{Name} = \texttt{Photic}, \textsc{Onsets} = \texttt{[att natt stat]} and \textsc{Durations} = \texttt{10}.
  \item Condition 2: \textsc{Name} = \texttt{Motion}, \textsc{Onsets} = \texttt{[att natt]} and \textsc{Durations} = \texttt{10}.
  \item Condition 3: \textsc{Name} = \texttt{Attention}, \textsc{Onsets} = \texttt{att} and \textsc{Durations} = \texttt{10}.
 \end{itemize}
 \item From the SPM menu at the top of the Batch Editor, select ``Stats $>$ model estimation''.
 \item For \textsc{Select SPM.mat}, click on the \textsc{Dependency} button and choose the proposed item (the output from the previous module).
 \item You should now be able to press the \textsc{Run} green arrow at the top of the Batch Editor window. This will specify and estimate the GLM.
\end{enumerate}

\subsection{Extracting time series}

Once you have specified and estimated the GLM, you should define t-contrasts that test for photic, motion, and attention, respectively. These serve to locate areas that show effects due to visual stimulation (e.g. in V1), motion (e.g. V5) and attention (e.g. V5 and superior parietal cortex, SPC). Because V5 shows both motion and attention effects, it is useful to mask the motion-contrast inclusively with the attention-contrast when extracting time series for V5. You should also compute the usual ``effects of interest'' F-contrast, this is needed for mean-correcting the extracted time series (see below).

\begin{enumerate}
 \item From the main SPM window, click on the \textsc{Batch} button.
 \item Add a module ``SPM $>$ Stats $>$ Contrast manager''.
 \item For \textsc{Select SPM.mat}, enter the one that has been created in the previous step.
 \item Under \textsc{Contrast Sessions}, choose one \textsc{New: F-contrast} and three \textsc{New: T-contrast} and enter
 \begin{itemize}
  \item F-contrast: \textsc{Name} = \texttt{Effects of interest}, \textsc{F contrast vector} = \texttt{eye(3)}.
  \item T-contrast: \textsc{Name} = \texttt{Photic}, \textsc{T contrast vector} = \texttt{[1 0 0]}.
  \item T-contrast: \textsc{Name} = \texttt{Motion}, \textsc{T contrast vector} = \texttt{[0 1 0]}.
  \item T-contrast: \textsc{Name} = \texttt{Attention}, \textsc{T contrast vector} = \texttt{[0 0 1]}.
 \end{itemize}
 \item Press the \textsc{Run} green arrow at the top of the Batch Editor window. This will specify and estimate these 4 contrasts.
\end{enumerate}

Here is now a step-by-step example for extracting the V5 time series:
\begin{enumerate}
 \item Press \textsc{Results}.
 \item Select the \texttt{SPM.mat} file.
 \item Choose the t-contrast for the \texttt{Motion} condition.
 \item Mask with other contrasts: Yes
 \item Choose the t-contrast for the \texttt{Attention} condition.
 \item Mask inclusively and choose a threshold of $p \leq 0.05$ uncorrected.
 \item Select the global maxima that looks V5-ish, e.g. \texttt{[-36 -87 -3]} (by overlaying the activations onto the normalised structural image you should be able to identify V5 more easily).
 \item Press the \textsc{eigenvariate} button.
 \item Name of region: \texttt{V5}
 \item Adjust data for: \texttt{Effects of interest} (this effectively mean-corrects the time series)
 \item VOI definition: \texttt{sphere}
 \item VOI radius(mm): e.g. \texttt{8} mm
\end{enumerate}
SPM now computes the first principal component of the time series from all voxels included in the sphere. The result is stored (together with the original time series) in a file named \texttt{VOI\_V5\_1.mat} in the working directory (the ``1'' refers to session 1).

You can now proceed to select time series for V1 (using the \textsc{Photic} contrast) with an \texttt{8} mm sphere centered on the global maxima (\texttt{[0 -93 18]}). Same thing with SPC (using the \textsc{attention} contrast with a $p \leq 0.001$ uncorrected threshold) and a sphere centered on the local maxima around \texttt{[-27 -84 36]}. This will create files \texttt{VOI\_V1\_1.mat} and \texttt{VOI\_SPC\_1.mat}.

\subsection{Specifying and estimating the DCM}

Now we have defined the inputs (via the design matrix) and the time series, we are ready to build the DCM. We will look at a simplified version of the model described in \cite{dcm}.  In our example here, we will model a hierarchically connected system comprising V1, V5 and SPC, i.e. reciprocal connections between V1-V5 and V5-SPC, but not between V1-SPC. We will assume that (i) V1 is driven by any kind of visual stimulation (direct input ``photic''), (ii) motion-related responses in V5 can be explained through an increase in the influence of V1 onto V5 whenever the stimuli are moving (i.e. ``motion'' acts as modulatory input onto the $V1 \rightarrow V5$ connection) and (iii) attention enhances the influence of SPC onto V5 (i.e. ``attention'' acts as modulatory input onto the $SPC \rightarrow V5$ connection). This DCM is shown schematically in Figure~\ref{bwd}, and can be made
\begin{figure}[ht]
\begin{center}
\includegraphics[width=100mm]{dcm/dcm_mod_bwd}
\caption{\em DCM with attentional modulation of backwards connection. Dotted lines denote modulatory connections.\label{bwd}}
\end{center}
\end{figure}
as follows:
\begin{enumerate}
\item Press the large \texttt{Dynamic Causal Modelling} button.
\item Choose \textsc{specify}.
\item Select the \texttt{SPM.mat} file you just created when specifying the GLM.
\item Name for \texttt{DCM\_???.mat}:  e.g. \texttt{mod\_bwd} (for ``attentional modulation of backward connection'').
\item Select all VOIs in order \texttt{VOI\_V1\_1}, \texttt{VOI\_V5\_1}, \texttt{VOI\_SPC\_1}.
\item Include \texttt{Photic}: Yes
\item Include \texttt{Motion}: Yes
\item Include \texttt{Attention}: Yes
\item Specify slice timings for each area. The default values are set to the last slice of the data, which was the default in the original DCM version. For sequential (as opposed to interleaved) data, this modelling option allows to use DCM in combination with any TR (slice timing differences) \cite{sjk_dcm_slicetiming}. Here, we proceed with the default values.
\item Enter \texttt{0.04} for ``Echo Time, TE[s]''.
\item Modulatory effects: \texttt{bilinear}
\item States per region: \texttt{one}
\item Stochastic effects: \texttt{no}
\item Define the following intrinsic connections: V1 to V5, V5 to V1, V5 to SPC, SPC to V5, i.e. a hierarchy with reciprocal connections between neighbouring areas. Note that the columns specify the source of the connection and the rows specify its target. Your connectivity matrix should look like the one in Fig.~\ref{dcm_fig4}.
\item Specify Photic as a driving input into V1.  See Fig.~\ref{dcm_fig4}
\item Specify Motion to modulate the connection from V1 to V5.  See Fig.~\ref{dcm_fig4}
\item Specify Attention to modulate the connection from SPC to V5.  See Fig.~\ref{dcm_fig4}
\end{enumerate}
A polite ``Thank you'' completes the model specification process. A file called \texttt{DCM\_mod\_bwd.mat} will have been generated.

\begin{figure}
\begin{center}
\includegraphics[width=70mm]{dcm/Fig4}
\includegraphics[width=70mm]{dcm/Fig5}
\includegraphics[width=70mm]{dcm/Fig6}
\includegraphics[width=70mm]{dcm/Fig7}
\caption{\em Specification of model depicted in Fig~\ref{bwd}. \textbf{Top left:} Filled circles define the structure of the intrinsic connections $A$ such that eg. there are no connections from V1 to SPC or from SPC to V1. \textbf{Top right:} The filled circle specifies that the input \texttt{Photic} connects to region V1. \textbf{Bottom left:} The filled circle indicates that the input \texttt{Motion} can modulate the connection from V1 to V5. This specifies a ``modulatory'' connection. \textbf{Bottom right:} The filled circle indicates that \texttt{Attention} can modulate the connection from SPC to V5. \label{dcm_fig4}}
\end{center}
\end{figure}

You can now estimate the model parameters, either by pressing the DCM button again and choosing \textsc{estimate}, or by typing
\begin{verbatim}
>> spm_dcm_estimate('DCM_mod_bwd');
\end{verbatim}
from the \matlab\ command line.

\begin{figure}
\begin{center}
\includegraphics[width=100mm]{dcm/dcm_mod_fwd}
\caption{\em DCM with attentional modulation of forwards connection. Dotted lines denote modulatory connections.\label{fwd}}
\end{center}
\end{figure}

\begin{figure}[ht]
\begin{center}
\includegraphics[width=140mm]{dcm/Fig8}
\caption{\em Plot of predicted and observed response, after convergence and conditional expectation of the parameters.\label{dcm_fig8}}
\end{center}
\end{figure}

Once this is completed, you can review the results as follows:
\begin{enumerate}
\item Press the DCM button.
\item Choose \textsc{review}.
\item Select \texttt{DCM\_mod\_bwd.mat}
\item Threshold: \texttt{0}
\end{enumerate}
Now you have multiple options, e.g. you can revisit the fit of the model (``Outputs'') or look at the parameter estimates for the intrinsic connections (``Intrinsic connections'') or for the parameters associated with the driving or modulatory inputs (``Effects of Photic'', ``Effects of Motion'', ``Effects of Attention'').

Also, you can use the ``Contrasts'' option to determine how confident you can be that a contrast of certain parameter estimates exceeds the threshold you chose in step 4.
Of course, you can also explore the model results at the level of the \matlab\ command line by loading the model and inspecting the parameter estimates directly. These can be found in \texttt{DCM.Ep.A} (intrinsic connections), \texttt{DCM.Ep.B} (modulatory inputs) and \texttt{DCM.Ep.C} (driving inputs).

\subsection{Comparing models}

Let us now specify an alternative model and compare it against the one that we defined and estimated above. The change that we are going to make is to assume that attention modulates the $V1 \rightarrow V5$ connection (as opposed to the $SPC \rightarrow V5$ connection in the previous model). For defining this model, you repeat all the steps from the above example, the only differences being that the model gets a new name (e.g. \verb!mod_fwd!) and that attention now acts on the forward connection. This DCM is shown schematically in Figure~\ref{fwd}.

Once you have estimated this new model, you can perform a Bayesian model comparison as follows:
\begin{enumerate}
 \item Press the ``DCM'' button.
 \item Choose \textsc{Compare}.
 \item In the Batch Editor window that opened, fill in the ``BMS: DCM'' module:
 \begin{enumerate}
   \item \texttt{Directory}: choose current directory,
   \item \texttt{Data}: add a New Subject with a New Session and select the two models, e.g. in the order \texttt{DCM\_mod\_bwd.mat} and \texttt{DCM\_mod\_fwd.mat},
   \item \texttt{Inference method}: choose ``Fixed effects (FFX)''.
 \end{enumerate}
 \item Press Run (the green triangle in the Batch Editor).
\end{enumerate}

The Graphics window, Fig.~\ref{dcm_fig9}, now shows a bar plot of the model evidence. You can see that our second model is better than the first one.

\begin{figure}[ht]
\begin{center}
\includegraphics[width=140mm]{dcm/Fig9}
\caption{\em Model 2 (shown in Fig~\ref{fwd}) is preferred to model 1 (shown in Fig~\ref{bwd}).\label{dcm_fig9}}
\end{center}
\end{figure}


% !TEX root = atlas_iros_16.tex
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Compliance Loss Compensation}
\label{sec:comp_obs}

\subsubsection{Loss of Compliance with Disturbance Compensation}
\label{sec:comp_obs_loss}
%
\begin{figure}
\centering
\includegraphics[]{./figures/ObserverStiff/ObsFeedthroughStiff_compare.pdf}
\caption{Position error $\Delta x$ and measured Cartesian external force $f_x$ are compared for two experiments with enabled ($\kappa_{\varepsilon}=1$) and disabled ($\kappa_{\varepsilon}=0$) disturbance compensation.
The end-effector was pushed manually and held at a certain displacement.}
\label{fig:stiff_observer_feedthrough}
\SkipBeforePicture
\end{figure}
%
The increased stiffness of the system, when using the disturbance compensation ($\kappa_{\varepsilon}=1$) was experimentally verified. For this, the robot end-effector was pushed with and without activated disturbance compensation, see Fig.~\ref{fig:stiff_observer_feedthrough}.
% Prozentuale Aussagen zu Kraft, Positionsfehler und Steifigkeit stammen aus ObserverFeedthroughStiff_Format.m
With enabled disturbance compensation the applied force was about $93$\% larger than without disturbance compensation (Fig.~\ref{fig:stiff_observer_feedthrough}~a) while the arm was only pushed back $67$\% in position (Fig.~\ref{fig:stiff_observer_feedthrough}~b).
This increased stiffness of about $187$\% is limited by the cutoff value for the estimated disturbance torque of $30$~Nm for safety reasons, as the observer was tuned to be near the (unknown) stability limit to ensure the fastest possible convergence.
However, with $\bm{K}_\mathrm{o}$ as chosen above, instabilities could not be observed during the experiments.

\subsubsection{Regaining Compliance with Force/Torque Sensing}
\label{sec:comp_obs_regain}
% Bild erstellt mit atlas_joint_impctrl_sqrt_damping_test_extforce_comp.m
\begin{figure}
\centering
\parbox{\columnwidth}{
\includegraphics[width=\linewidth]{simulations/SimExp_ObsExtForce.pdf}
}
\vspace*{-1ex}
\caption{Simulation results: An external force step of 50~N is applied normal to the end-effector at $t=0.5~\mathrm{s}$ and released at $t=3.5~\mathrm{s}$.
Joint position $q_1$, external joint torque $\tau_{\mathrm{ext,1}}$, and observed disturbance torque $\hat{\tau}_{\varepsilon,1}$ are plotted for disabled disturbance compensation DC ($\kappa_\varepsilon=0$), DC without EFC ($\kappa_\mathrm{ext}=0$) and DC with EFC ($\kappa_\mathrm{ext}=1$).}
\label{fig:DistTorque}
\SkipBeforeText
\end{figure}
%
Since the wrist wrench sensor of the real system was not yet fully operational, the ability to eliminate external forces from the disturbance observer via (\ref{eqn:regainComp}) was validated in simulation.
The continuous time forward dynamics derived from (\ref{eqn:invdyn}) of the arm was implemented with viscous and Coulomb friction and parameters from Table~\ref{tab:errors_tracking_left}.
The observer gain was chosen to be uniformly $k_{\mathrm{o},i}=10~\mathrm{s}^{-1}$, stiffness $k_i=150~\mathrm{Nm/rad}$ and modal damping $d_{\xi,i}=0.3$.
The Controller (\ref{eqn:controller}) was implemented with model errors and sensor noise $\bm{\delta}$.
The model errors were generated with uniformly distributed pseudo random numbers between $\pm 10\%$ as a scaling factor to all masses, inertias, center of mass coordinates and friction coefficients.
The sensor noise was (component-wise) uniformly distributed between \mbox{$\pm 3.4\cdot10^{-4}~\mathrm{rad}$} for joint position, \mbox{$\pm 5.5\cdot10^{-2}~\mathrm{rad/s}$} for velocity, \mbox{$\pm 2\cdot10^{-4}~\mathrm{m/s^2}$} for the gravity vector, \mbox{$\pm 7.3\cdot10^{-2}~\mathrm{Nm}$} for the joint torque and \mbox{$\pm 2.3~\mathrm{N}$} for the external forces, respectively.
These values were obtained from the measurement data of the hydraulic joints during the starting phase of the experiment in Fig.~\ref{fig:stiff_observer_feedthrough}.

For this setup, a step change of the external force acting on the end-effector was performed with different observer settings.
The results are shown in Fig.~\ref{fig:DistTorque}.
For $\kappa_\varepsilon=0$, i.e. applying no disturbance compensation, compliant behavior is achieved. Using the disturbance compensation without EFC ($\kappa_\mathrm{ext}=0$) leads to a very stiff response according to (\ref{eqn:compLoss}), with $\hat{\tau}_{\varepsilon,1}$ converging to $\tau_{\mathrm{ext,1}}$.
When selecting $\kappa_\mathrm{ext}=1$, the observer torque remains near zero, as it only observes the model errors.
In addition, the compliance is the same as without disturbance compensation, i.e. as expected from (\ref{eqn:regainComp}).
Therefore, the simulation results imply, that this approach allows to compensate for model errors, while correctly reacting compliant to end-effector contacts at the same time.
%
\begin{figure}
\centering
\parbox{\columnwidth}{
\includegraphics[width=\linewidth]{simulations/SimExp_MdlNoiseExtForce.pdf}
}
\caption{Simulation results: The experiment of Fig.~\ref{fig:DistTorque} was done multiple times with different model errors.
The normalized mean squared integrated error is plotted over the maximum parameter noise level.
The results for $\kappa_\mathrm{ext}=0$ and $\kappa_\mathrm{ext}=1$ are shown in the top and the bottom plot respectively.}
\label{fig:MdlNoise}
\SkipBeforePicture
\vspace*{-1ex}
\end{figure}
%
\begin{figure}
\centering
\parbox{\columnwidth}{
\includegraphics[width=\linewidth]{simulations/SimExp_MesNoiseExtForce.pdf}
}
\caption{Simulation results: The experiment from Fig.~\ref{fig:DistTorque} was done multiple times with different measurement errors.
The normalized mean squared error is depicted over the scaling factor applied to all measurement noise levels from the simulation of Fig.~\ref{fig:DistTorque}.}
\label{fig:MesNoise}
\SkipBeforeText
\end{figure}
%
\subsubsection{Robustness of Disturbance Compensation with EFC against Model Errors}
Further simulations (as in Fig.~\ref{fig:DistTorque}) were performed to investigate the robustness of the above method.
First, the influence of model errors is investigated.
The model errors were introduced by scaling the masses, the center of gravity positions of the links, the link inertias and the friction parameters by uniformly distributed random factors.
The normalized mean squared integrated error (MSIE)
\begin{equation}
\mathrm{MSIE}=\frac{1}{n_{\mathrm{j}}T_\mathrm{f}}\sum_{i=1}^{n_{\mathrm{j}}}\int_0^{T_\mathrm{f}} \left(q_i(t)-q_i^{\mathrm{ref}}(t)\right)^2\mathrm{d}t
\end{equation}
is depicted over the maximum noise factor for limits from 1\% to 30\% in Fig.~\ref{fig:MdlNoise} for the controller with and without EFC.
The norm $\|\mathrm{MSIE}\|=\mathrm{MSIE}/\max(\mathrm{MSIE})$ is calculated for Fig.~\ref{fig:MdlNoise} and Fig.~\ref{fig:MesNoise} separately.
The compliant behavior of the controller without disturbance compensation and without model errors or measurement noise was selected as reference $\bm{q}^\mathrm{ref}$.
In order to gain comparable results, the model errors were the same in both plots.
It can be seen that the influence of the model errors is similar for both cases and the results with EFC remain close to the reference case. The order of magnitude between the results with and without EFC stays the same for all model error levels.
%Therefore, the deviation from the desired compliant behavior increases slightly
Even with an identification error of up to $30\%$, the controller can cope with the resulting model errors for this quasi-static movement.

\subsubsection{Robustness of Disturbance Compensation with EFC against Sensor Noise}

Figure~\ref{fig:MesNoise} depicts the influence of measurement noise on controller performance.
The measurement noise levels from above were scaled by factors of 1 to 30 and the MSIE is compared for the controller with ($\kappa_\mathrm{ext}=1$) and without EFC ($\kappa_\mathrm{ext}=0$).
It can be seen that for noise levels amplified up to 10 times, the deviation from the reference behavior does not change noticeably in either case, i.e. the compliance rendering of the controller remains the same despite increased noise.

For larger measurement noise the deviation from the desired behavior becomes smaller for $\kappa_\mathrm{ext}=0$ since the limitation of the observer output prevents the compensation of external forces for high measurement noise.
This effect even leads to a behavior closer to the desired one with \mbox{$\kappa_\mathrm{ext}=0$} instead of \mbox{$\kappa_\mathrm{ext}=1$} for very high measurement noise (at least 25 times as high as observed in the experiments).
In term, Fig.~\ref{fig:MesNoise} implies that the controller is able to cope with measurement noise about 10 times higher than found in our experimental setup.
To cope with larger measurement noise, one would have to use filtering or increase the output limit of the observer.