New doc from Denis

git-svn-id: http://svn.einsteintoolkit.org/cactus/EinsteinInitialData/IDAnalyticBH/trunk@103 6a3ddf76-46e1-4315-99d9-bc56cac1ef84

2 files changed, 396 insertions, 222 deletions

diff --git a/doc/ThornGuide.tex b/doc/ThornGuide.tex
deleted file mode 100644
index c03e09b..0000000
--- a/doc/ThornGuide.tex
+++ /dev/null
@@ -1,132 +0,0 @@
-\documentstyle{report}
-\newcommand{\parameter}[1]{{\it #1}}
-
-\begin{document}
-
-\chapter{IDAnalyticBH}
-
-\begin{tabular}{@{}ll}
-Code Authors & Joan Masso, Paul Walker, Ed Seidel. Gabrielle Allen \\
-Maintained by & Cactus Developers \\
-Documentation Authors & 
-\end{tabular}
-
-\section{Introduction}
-  
-\subsection{Purpose of Thorn}
-
-Thorn IDAnalyticBH provides analytic initial data for vacuum black 
-hole spacetimes. Initial data is provided for the 3-metric, extrinsic
-curvature, and if appropriate the conformal factor and it's spatial 
-derivatives. The current initial data sets are for a single (Schwarzschild)
-black hole in isotropic coordinates, up to four Brill-Lindquist black 
-holes, and any number of Misner-type black holes.
-
-\subsection{Technical Specification}
-
-\begin{itemize}
-
-\item{Implements} einsteinID
-\item{Inherits from} einstein
-\item{Tested with thorns} Einstein
-
-\end{itemize}
-
-\section{Theoretical Background}
-
-
-\section{Algorithmic and Implementation Details}
-
-This thorn uses no special numerical methods, however two points
-are worth noting
-
-\begin{enumerate}
-
-\item{} The solution for Misner is obtained by summing a sequence
-
-\item{} The spatial derivatives of the conformal metric (when required) 
-        are calculated accurately using finite differencing of the 
-        exact solution by a very small spacing
-
-\end{enumerate}
-
-\section{Using the Thorn}
-
-This thorn can provide either the physical metric (use\_conformal=''no'')
-or the conformal metric and a conformal factor (and its spatial derivatives)
-(use\_conformal=''yes''). In general, the option use\_conformal=''yes'' should 
-be used, since ????. 
-
-\section{Parameters}
-
-\subsection{Extended Parameters}
-\begin{tabular}{l|l|l|l}
-&&&\\
-einstein &&&\\
-\hline
-\parameter{initial\_data} & KEYWORD & schwarzschild & One Schwarzschild black hole \\
-& & bl\_bh & Brill Lindquist black holes \\
-& & misner\_bh &Misner black holes \\
-& & multiple\_misner\_bh & Multiple Misner black holes \\
-\parameter{initial\_lapse} & KEYWORD & schwarz & Set lapse to schwarzschild \\
-\end{tabular}
-
-\subsection{Private Parameters}
-
-\begin{tabular}{l|l|l|l|l}
-&&&&\\
-Schwarzschild & & & & \\
-\hline
-\parameter{mass} & {\t CCTK\_REAL} & $(-\infty,\infty)$ & 2.0 & Mass of black hole \\
-&&&&\\
-Multiple Misner & & & & \\
-\hline
-\parameter{mu} & {\t CCTK\_REAL} & $[0,\infty)$ & 1.2 & Misner $\mu$ value \\
-\parameter{nmax} & {\t CCTK\_INT} & $[0,\infty)$ & 30 & Numer of terns to include for Misner series \\
-\parameter{misner\_nmh} & {\t CCTK\_INT} & $[0,10]$ & 1 & Number of Misner black holes \\
-&&&&\\
-Brill Lindquist & & & & \\
-\hline
-\parameter{bl\_nbh} & {\t CCTK\_INT} & $[1,4]$ & 1 & Number of Brill Lindquist black holes\\
-\parameter{bl\_x0\_1} & {\t CCTK\_REAL} &  $(-\infty,\infty)$ & 0.0 & x-position of first BL hole\\
-\parameter{bl\_y0\_1} & {\t CCTK\_REAL} &  $(-\infty,\infty)$ & 0.0 &  y-position of first BL hole\\
-\parameter{bl\_z0\_1} & {\t CCTK\_REAL} &  $(-\infty,\infty)$ & 0.0 &  z-position of first BL hole\\
-\parameter{bl\_M\_1} & {\t CCTK\_REAL} &  $(-\infty,\infty)$ & 1.0 &  mass of first BL hole\\
-\parameter{bl\_x0\_2} & {\t CCTK\_REAL} &  $(-\infty,\infty)$ & 0.0 & x-position of second BL hole\\
-\parameter{bl\_y0\_2} & {\t CCTK\_REAL} &  $(-\infty,\infty)$ & 0.0 &  y-position of second BL hole\\
-\parameter{bl\_z0\_2} & {\t CCTK\_REAL} &  $(-\infty,\infty)$ & 0.0 &  z-position of second BL hole\\
-\parameter{bl\_M\_2} & {\t CCTK\_REAL} &  $(-\infty,\infty)$ & 1.0 &  mass of second BL hole\\
-\parameter{bl\_x0\_3} & {\t CCTK\_REAL} &  $(-\infty,\infty)$ & 0.0 & x-position of third BL hole\\
-\parameter{bl\_y0\_3} & {\t CCTK\_REAL} &  $(-\infty,\infty)$ & 0.0 &  y-position of third BL hole\\
-\parameter{bl\_z0\_3} & {\t CCTK\_REAL} &  $(-\infty,\infty)$ & 0.0 &  z-position of third BL hole\\
-\parameter{bl\_M\_3} & {\t CCTK\_REAL} &  $(-\infty,\infty)$ & 1.0 &  mass of third BL hole\\
-\parameter{bl\_x0\_4} & {\t CCTK\_REAL} &  $(-\infty,\infty)$ & 0.0 & x-position of fourth BL hole\\
-\parameter{bl\_y0\_4} & {\t CCTK\_REAL} &  $(-\infty,\infty)$ & 0.0 &  y-position of fourth BL hole\\
-\parameter{bl\_z0\_4} & {\t CCTK\_REAL} &  $(-\infty,\infty)$ & 0.0 &  z-position of fourth BL hole\\
-\parameter{bl\_M\_4} & {\t CCTK\_REAL} &  $(-\infty,\infty)$ & 1.0 &  mass of fourth BL hole\\
-\end{tabular}
-
-\subsection{Discussion}
-
-
-
-\section{Interaction with Other Thorns}
-
-It is still to be decided how initial data should be supplied to
-for systems of evolution equations which use more or different 
-variables to those in the einstein implementation
-
-\section{Future Development}
-
-Initial data sets which are missing from this thorn include
-
-\begin{itemize}
-
-\item{} Boosted single black hole
-\item{} Single black hole in harmonic spatial coordinates
-\item{} Single black hole in Eddington-Finkelstein coordinates
-
-\end{itemize}
-
-
-\end{document}
diff --git a/doc/documentation.tex b/doc/documentation.tex
index b46dbd4..9c2e870 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -1,97 +1,403 @@
+% /*@@
+%   @file      documentation.tex
+%   @date      28 April 2002
+%   @author    Denis Pollney
+%   @desc 
+%              IDAnalyticBH users guide.
+%   @enddesc 
+%   @version $Header$
+% @@*/
+
+%
+% FIXME: Is the non-conformal schwarzschild correct in the source
+% FIXME:   code???
+% FIXME: Add a reference to the quasi-isotropic Kerr coordinates?
+% FIXME: What is the Cadez lapse for Misner?
+% FIXME: The distance calculation (tmp1) seems wrong in the
+% FIXME:   brill-lindquist code.
+% FIXME: Check that figure was included for Cartoon docs.
+
 \documentclass{article}
+\usepackage{epsfig}
+
+\parskip = 0 pt
+\parindent = 0pt
+\oddsidemargin = 0 cm
+\textwidth = 16 cm
+\topmargin = -1 cm
+\textheight = 24 cm
+
 \begin{document}
+\title{Using \texttt{IDAnalyticBH} (OLD EINSTEIN!!)}
+\author{Denis Pollney}
+\date{April 2002}
 
-\title{IDAnalyticBH}
-\author{Steve Brandt, Carsten Gundlach, Joan Masso, Ed Seidel, Paul Walker}
-\date{1997-1998}
 \maketitle
 
-\abstract{Analytic initial data for vacuum black hole spacetimes}
-
-\section{Purpose}
-  Initial data is provided for the 3-metric, extrinsic curvature, and
-  if appropriate the conformal factor and it's spatial derivatives as
-  well as the lapse and shift. The current initial data sets are:
-  \begin{enumerate} 
-
-	\item single (Schwarzschild) black hole in isotropic
-	coordinates $$ g_{ij} = $$
-
-	\item up to four Brill-Lindquist black holes,
-
-	\item Any number of Misner-type black holes.
-	
-	\item A single Kerr black hole 
-	
- \end{enumerate}
-
-\section{Solutions}
-
-\subsection{Schwarzschild}
-
-\noindent{\bf 3-Metric} 
-
-\begin{eqnarray*}
-g_{xx} &=& 1 + \frac{1}{2Mr^4}\\
-g_{yy} &=& 1 + \frac{1}{2Mr^4}\\
-g_{zz} &=& 1 + \frac{1}{2Mr^4}\\
-g_{xy} &=& 0\\
-g_{xz} &=& 0\\
-g_{yz} &=& 0
-\end{eqnarray*}
-
-\noindent{\bf Conformal 3-Metric} 
-
-\begin{eqnarray*}
-g_{xx} &=& 1 \\
-g_{yy} &=& 1 \\
-g_{zz} &=& 1 \\
-g_{xy} &=& 0\\
-g_{xz} &=& 0\\
-g_{yz} &=& 0
-\end{eqnarray*}
-
-\noindent{\bf Conformal Factor}
-
-$$
-\phi = 1+\frac{1}{2r}
-$$
-
-\noindent{\bf Conformal Factor} 
-
-\begin{eqnarray*}
-K_{xx} &=& 0\\
-K_{yy} &=& 0\\
-K_{zz} &=& 0\\
-K_{xy} &=& 0\\
-K_{xz} &=& 0\\
-K_{yz} &=& 0
-\end{eqnarray*}
-
-\noindent{\bf Lapse}
-
-$$
-\alpha = \frac{2r-M}{2r+M}
-$$
-
-
-\section{Comments}
-This thorn uses no special numerical methods, however two points
-are worth noting
-\begin{itemize}
-  \item The solution for Misner is obtained by summing a sequence
-  \item The spatial derivatives of the conformal metric (when required) 
-        are calculated accurately using finite differencing of the 
-        exact solution by a very small spacing </item>
-\end{itemize}
-
-It is still to be decided how initial data should be supplied to
-for systems of evolution equations which use more or different 
-variables to those in the einstein implementation
-
-% Automatically created from the ccl files by using gmake thorndoc
-\include{interface}
-\include{param}
-\include{schedule}
+\abstract{The \texttt{IDAnalyticBH} thorn contains a number of initial data
+sets for black-hole evolutions which can be specified analytically
+as metric and extrinsic curvature components. The initial data which
+is included in this thorn include single Schwarzschild and Kerr black
+holes, and multiple black hole Misner and Brill-Lindquist solutions.
+}
+
+
+\section{Background}
+
+The \texttt{IDAnalyticBH} thorn exists as a central location to place any
+initial dataset for black hole evolution that can be specified
+analytically in terms of the metric, $g_{ab}$, and extrinsic
+curvature, $K_{ab}$.
+
+The thorn extends the \texttt{einstein::initial\_data} parameter by
+adding the following datasets:
+\begin{description}
+  \item[\texttt{schwarzschild}] Schwarzschild, in isotropic
+  coordinates;
+  \item[\texttt{kerr}] Kerr, in Boyer-Lindquist coordinates;
+  \item[\texttt{misner}] Multiple Misner black holes;
+  \item[\texttt{bl\_bh}] Multiple Brill-Lindquist black holes.
+\end{description}
+Initial data for lapse and shift can also be specified in
+this thorn.\\
+
+The Cactus grid-functions corresponding to the initial data are
+inherited from the thorn \texttt{CactusEinstein/Einstein}, along with
+the conformal factor grid-function, \texttt{psi}, and its derivatives
+which are optionally set based on the value of the parameter
+\texttt{einstein::use\_conformal}.\\
+
+The \texttt{IDAnalyticBH} has been written and augmented over an number of
+years by many Cactus authors. These include John Baker, Steve Brandt,
+Carsten Gundlach, Joan Masso, Ed Seidel, and Paul Walker. The
+following sections describe each of the initial datasets and their
+associated parameters in turn.
+
+\section{Schwarzschild}
+
+The Schwarzschild metric corresponds to a single, static, black hole.
+If the Cactus metric is specified as a conformal metric (by setting
+\texttt{einstein::use\_conformal="yes"}), then the metric is
+set using isotropic coordinates \cite{mtw-isotropic}:
+\begin{equation}
+  ds^2 = -\left(\frac{2r - M}{2r + M}\right)^2
+  + \left(1 + \frac{M}{2r}\right)^4 \left(dr^2 + r^2(d\theta^2
+  + \sin^2\theta d\phi^2)\right),
+\end{equation}
+with the Schwarzschild mass given by the single free parameter $M$.
+Thus, the three metric and extrinsic curvature have the values:
+\begin{eqnarray}
+  \hat{g}_{ab} & = & \psi^4 \delta_{ab}, \\
+  \psi & = & (1 + \frac{M}{2r}), \\
+  K_{ab} & = & 0.
+\end{eqnarray}
+
+The mass is specified using the parameter
+\texttt{idanalyticbh::mass}. The black hole is assumed to reside at
+the origin of the grid, corresponding to the location $x=y=z=0$.\\
+
+If the \texttt{einstein::use\_conformal} parameter has been set, then
+the metric grid-functions (\texttt{einstein::gxx}, $\ldots$,
+\texttt{einstein::gzz}) are given as $\delta_{ab}$, and the conformal
+factor \texttt{einstein::psi} is set to the value specified
+above. The derivatives of the conformal factor
+(\texttt{einstein::psix}, etc.) are determined analytically.
+
+In order to give the lapse an initial profile which corresponds to
+isotropic lapse of the $4$-metric specified above, use the parameter
+\begin{verbatim}
+  idanalyticbh::initial_lapse = "schwarz"
+\end{verbatim}
+This will cause the \texttt{einstein::alp} grid-function to be
+initialised to the value:
+\begin{equation}
+  \alpha = \frac{2r - M}{2r + M}.
+\end{equation}\\
+
+
+Note that the Schwarzschild data has the following non-standard
+behaviour in response to the \texttt{einstein::use\_conformal}
+parameter. If the \emph{physical} metric is requested
+(ie. \texttt{use\_conformal} is set to \texttt{"no"}) then a
+\emph{different} form of the Schwarzschild metric is set:
+Schwarzschild coordinates are set instead of the isotropic
+coordinates:
+\begin{equation}
+  g_{xx} = g_{yy} = g_{zz} = 1 + 2M/r.
+\end{equation}\\
+
+
+In order to carry out an evolution of a single Schwarzschild
+black hole of mass $m=1$, using an initial lapse of $\alpha=1$, you
+could modify your parameter file as follows:
+
+\begin{verbatim}
+  ActiveThorns = "... Einstein IDAnalyticBH ..."
+
+  einstein::use_conformal = "yes"
+
+  einstein::initial_data = "schwarzschild"
+  einstein::initial_lapse = "one"            # or "schwarz" for isotropic lapse
+
+  idanalyticbh::mass = 1.0
+\end{verbatim}
+
+
+\section{Kerr}
+
+Kerr initial data for an isolated rotating black hole is specified
+using the ``quasi-isotropic'' coordinates:
+\begin{equation}
+  ds^2 = \psi^4 (dr^2 + r^2(d\theta^2 + \chi^2\sin^2\theta d\phi^2)),
+\end{equation}
+where
+\begin{eqnarray}
+  \psi^4 & = & - 2\frac{a^2}{r^2}\cos\theta\sin\theta, \\
+  \chi^2 & = & p^2 / \Sigma, \\
+  p^2 & = & a^2 + {r_k}^2 - a B_\phi, \\
+  r_k & = & r + M + \frac{M^2 - a^2}{4r}, \\
+  B_\phi & = & -2 M r_k a \sin^2\theta / \Sigma,\\
+  \Sigma & = & {r_k}^2 + a^2 \cos^2\theta.
+\end{eqnarray}
+The two free parameters are the Kerr mass, $M$, and angular momentum,
+$a$. These are specified using the parameters
+\texttt{idanalyticbh::mass} and \texttt{idanalyticbh::a\_kerr}
+respectively. \emph{(Note that the default values for these parameters
+are $M=2$ and $a=0.1$.)} The black hole is assumed to reside at the
+centre of the coordinate system, at $x=y=z=0$.
+
+The \texttt{einstein::use\_conformal} parameter can be used to specify
+whether the metric should be conformal or not. If the metric is
+conformal, then $\psi$ is initialised as a separate grid function, and
+it's first and second derivatives are calculated analytically and also
+stored as grid functions. Otherwise, the conformal factor is
+multiplied through in the expression for the 3-metric before the
+values of the \texttt{einstein::metric} variables are set. The
+extrinsic curvature is also determined analytically.
+
+The gauge can be set to the Kerr lapse and shift with the parameters
+\begin{verbatim}
+  idanalyticbh::initial_lapse = "kerr"
+  idanalyticbh::initial_shift = "kerr"
+\end{verbatim}
+in which case the formulas
+\begin{eqnarray}
+  \alpha & = &\sqrt{\frac{\Delta}{p^2}}, \\
+  \beta^\phi & = & -2 m r_k a / p^2,
+\end{eqnarray}
+where
+\begin{equation}
+  \sqrt{\Delta} = r - \frac{m^2 - a^2}{4r}.
+\end{equation}
+
+A set of parameters which initialise an evolution to use the Kerr
+intial data with mass $M=1$ and angular momentum $a=0.3$ are:
+\begin{verbatim}
+  ActiveThorns = "... Einstein IDAnalyticBH ..."
+
+  einstein::use_conformal = "yes"
+
+  einstein::initial_data = "kerr"
+  einstein::initial_lapse = "kerr"
+  einstein::initial_shift = "kerr"
+
+  idanalyticbh::mass = 1.0
+  idanalyticbh::a_kerr = 0.3
+\end{verbatim}
+
+\section{Misner}
+
+The earliest suggestion for initial data that might be said to
+corresponding to multiple black holes was given by Misner in 1960
+\cite{misner:1960}. He provided a prescription for writing a metric
+connecting a pair of massive bodies, instaneously at rest, whose
+throats are connected by a wormhole. Using the method of images, this
+solution was generalised to describe any number of black holes whose
+throats connect two identical asymptotically flat spacetimes
+\cite{misner:1963}.
+\begin{figure}
+  \centering
+  \epsfig{file=misner.eps, height=40mm}
+  \caption{The topology of the Misner spacetime is that of a pair of
+  asymptotically flat sheets connected by a number of Einstein-Rosen
+  bridges. By construction, an exact isometry exists between the upper
+  and lower sheet across the throats. The parameter $\mu_0$ is a
+  measure of the distance of a loop in the surface, passing through
+  one throat and out the other.}
+\end{figure}
+
+Two implementations of the Misner data are available. The first of
+these, ``\texttt{misner\_bh}'', is due to Joan Masso, Ed Seidel and
+Karen Camarda, and implements the original two-throat solution. The
+more general solution was implemented by Steve Brandt and Carsten
+Gundlach, and is available as ``\texttt{multiple\_misner\_bh}''.
+
+\subsection{Two-throat Misner data}
+
+The \texttt{misner\_bh} initial data generates a metric of the form
+\begin{equation}
+  ds^2 = -dt^2 + \psi^4 (dx^2 + dy^2 + dz^2),
+\end{equation}
+where the conformal factor $\psi$ is given by
+\begin{equation}
+  \psi = \sum^N_{n=-N}
+  \frac{1}{\sinh(\mu_0 n)}
+  \frac{1}{\sqrt{x^2 + y^2 + (z + \coth(\mu_0 n))^2}}.
+\end{equation}
+
+The parameter $\mu_0$ is a measure of the ration of mass to separation
+of the throats, and is set using the parameter
+\texttt{idanalyticbh::mu}. For values less than $\mu\simeq 1.8$, the
+throats will have a single event horizon.
+
+The summation limit $N$ can be set using the parameter
+\texttt{idanalyticbh::nmax}. Ideally, it should tend to infinity, but
+in practice the default value of $N=30$ works well enough for the
+applications that have been tested. The \texttt{misner\_nbh} parameter
+is only used for the \texttt{multiple\_misner\_bh} multi-throat data,
+and will be ignored for the \texttt{misner\_bh} initial data, which
+assumes two throats.
+
+For the given metric, the ADM mass of the system is determined via
+\begin{equation}
+  m = 4 \sum^N_{n=1} \frac{1}{\sinh(\mu_0 n)}.
+\end{equation}
+This quantity is determined automatically and written to standard
+output.
+
+If the conformal form of the metric is used (via the
+\texttt{einstein::use\_conformal} parameter), then derivatives of the
+conformal factor are computed analytically from the derivatives of the
+above expression for $\psi$.
+
+To make use of the two black hole initial data, a variation of the
+following set of parameters can be used:
+\begin{verbatim}
+  ActiveThorns = "... Einstein IDAnalyticBH ..."
+
+  einstein::use_conformal = "yes"
+
+  einstein::initial_data = "misner_bh"
+  idanalyticbh::mu = 2.2
+\end{verbatim}
+
+
+\section{Multiple-throat Misner data}
+
+The generalisation of the above form of data to multiple black holes
+is available as the \texttt{multiple\_misner\_bh} initial data set. The
+conformal factor is determined by recursively applying a Misner
+isometry condition to each of the black holes relative to the others.
+
+The black holes are arranged at equal-spaced angles on a circle around
+the origin in the $xy$-plane. The radius of the circle is $\coth\mu_0$,
+where $\mu_0$ is given by the \texttt{idanalyticbh::mu} parameter, and
+the first black hole lies on the $x$-axis (as in Figure
+\ref{fig:multi_misner}).
+\begin{figure}
+  \centering
+  \label{fig:multi_misner}
+  \epsfig{file=multi_misner.eps, height=40mm}
+  \caption{Configuration for three Misner throats using the
+  \texttt{multiple\_misner\_bh} initial data.}
+\end{figure}
+
+The number of throats is given by the parameter
+\texttt{idanalyticbh::misner\_nbh}, which defaults to 1 and has a
+hard-coded upper limit of 10. The number of terms used in the Misner
+expansion is controlled by the parameter
+\texttt{idanalyticbh::nmax}, which has a default value of 30.
+
+For this version of the Misner data, derivatives of the conformal
+factor $\psi$ are determined numerically by finite differencing,
+using values of $\psi$ calculated at small distances from the point at
+which the derivative is to be evaluated. The size of the numerical
+stencil is hardcoded at $dx=10^-6$.
+
+As an example, a parameter file implementing 3 Misner black holes on a
+circle of radius $\cosh 4$ would use the following parameters:
+\begin{verbatim}
+  ActiveThorns = "... Einstein IDAnalyticBH ..."
+
+  einstein::use_conformal = "yes"
+
+  einstein::initial_data = "multiple_misner_bh"
+
+  idanalyticbh::misner_nbh = 3
+  idanalyticbh::mu = 4
+\end{verbatim}
+
+
+\section{Brill-Lindquist}
+
+The Brill-Lindquist initial data is an alternate form of multi-throat
+data which differs from the Misner data mainly in its choice of
+spacetime topology. Whereas the Misner data presumes that the throats
+connect a pair of asymptotically flat spacetimes which are identical
+to each other, the Brill-Lindquist data connects each throat to a
+separate asymptotically flat region \cite{brill-lindquist:1963}.
+\begin{figure}
+  \centering
+  \epsfig{file=brill_lindquist.eps, height=40mm}
+  \caption{Two Brill-Lindquist throats connecting separate
+    asymptotically flat regions.}
+\end{figure}
+The form of the conformal factor is:
+\begin{equation}
+  \psi = 1 + \sum_{i=1}^N \frac{m_i}{2r_i},
+\end{equation}
+where the $m_i$ and $r_i$ are the masses and positions of the $i$
+particles.
+
+The parameter specifying the number of black holes is
+\texttt{idanalyticbh::bl\_nbh}. A maximum of four black holes can be
+specified. The mass and $(x,y,z)$ position of the first black hole is
+given by \texttt{bl\_M\_1}, \texttt{bl\_x0\_1}, \texttt{bl\_y0\_1},
+\texttt{bl\_z0\_1}, with corresponding parameters for the second to
+fourth black holes. Note that the default values for each of the
+position coordinates are $0.0$, so that only the coordinates off
+of the axes must be specified.
+
+If the conformal metric is used, then derivatives of the conformal
+factor are calculated from the analytic derivatives of the above
+expression for the conformal factor.
+
+To initialise a run with a pair of Brill-Lindquist black holes with
+masses $1$ and $2$ and located at $\pm 1$ on the $y$-axis, a set of
+parameters such as the following could be used:
+\begin{verbatim}
+  ActiveThorns = "... Einstein IDAnalyticBH ..."
+
+  einstein::use_conformal = "yes"
+
+  einstein::initial_data = "bl_bh"
+
+  idanalyticbh::bl_nbh = 2
+
+  idanalyticbh::bl_M_1 = 1.0
+  idanalyticbh::bl_y0_1 = 1.0
+
+  idanalyticbh::bl_M_2 = 2.0
+  idanalyticbh::bl_y0_2 = -1.0
+\end{verbatim}
+
+\begin{thebibliography}{9}
+  \bibitem{mtw-isotropic}
+    See, for instance, p. 840 of:
+    Misner, C. W., Thorne, K. S., and Wheeler, J. A. (1973)
+    \emph{Gravitation}, W. H. Freeman, San Francisco.
+  \bibitem{misner:1960}
+    Misner, Charles W. (1960)
+    \emph{Wormhole Initial Conditions},
+    Phys. Rev., \textbf{118}, 1110--1111.
+  \bibitem{misner:1963}
+    Misner, Charles W. (1963)
+    \emph{The Method of Images in Geometrostatics},
+    Ann. Phys., \textbf{24}, 102--117.
+  \bibitem{brill-lindquist:1963}
+    Brill, Dieter R., and Lindquist, Richard W. (1963)
+    \emph{Interaction Energy in Geometrostatics}
+    Phys. Rev., \textbf{131}, 471--476.
+\end{thebibliography}
 
 \end{document}