Debian Codegraph @

inst/doc/elliptic.Rnw

raw
1 \documentclass[nojss]{jss}
2
3 \usepackage{dsfont}
4 \usepackage{bbm}
5 \usepackage{amsfonts}
6 \usepackage{wasysym}
7 \usepackage{wrapfig2}
8
9 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
10 %% declarations for jss.cls %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
12
13
14 %% just as usual
15 \author{Robin K. S. Hankin}
16 \title{Introducing \pkg{elliptic}, an \proglang{R} package for elliptic and
17 modular functions}
18 %\VignetteIndexEntry{A vignette for the elliptic package}
19 %% for pretty printing and a nice hypersummary also set:
20 %% \Plainauthor{Achim Zeileis, Second Author} %% comma-separated
21 \Plaintitle{Introducing elliptic, an R package for elliptic and
22 modular functions}
23 \Shorttitle{Elliptic functions with \proglang{R}}
24
25 %% an abstract and keywords
26 \Abstract{
27
28 To cite the package in publications, use \citet{hankin2006}.
29 This paper introduces the \pkg{elliptic} package of \proglang{R} routines, for
30 numerical calculation of elliptic and related functions. Elliptic
31 functions furnish interesting and instructive examples of many ideas
32 of complex analysis, and package \pkg{elliptic} illustrates these
33 numerically and visually. A statistical application in fluid
34 mechanics is presented.
35 }
36
37 \Keywords{Elliptic functions, modular functions, Weierstrass elliptic
38 functions, visualization of complex functions}
39
40 \Address{
41 Robin K. S. Hankin\\
42 The University of Stirling\\
43 E-mail: \email{[email protected]}
44 }
45
46
47 %% need no \usepackage{Sweave.sty}
48 \SweaveOpts{echo=FALSE}
49 \begin{document}
50
51
52 <<requirepackage,echo=FALSE,print=FALSE>>=
53 require(elliptic,quietly=TRUE)
54 @
55
56
57 <<setOverallImageQuality>>=
58 n <- 400
59 n_BACCO <- 40
60 @
61
62 \section{Introduction}
63
64
65 \begin{wrapfigure}{r}{30mm}
66 \includegraphics[width=1in]{\Sexpr{system.file("help/figures/elliptic.png",package="elliptic")}}
67 \end{wrapfigure}
68 %
69 The elliptic functions crop up here and there in diverse areas of
70 applied mathematics such as cosmology~\citep{kraniotis2002}, chemical
71 engineering~\citep{koopman1991}, dynamical systems~\citep{kotus2003},
72 and quantum mechanics~\citep{chow2002}; here they are applied to fluid
73 mechanics~\citep{johnson2004,johnson2005}. They also provide
74 interesting and instructive non-elementary examples of many results in
75 complex analysis such as Cauchy's integral theorem and the residue
76 theorem.
77
78 In this paper I introduce \pkg{elliptic}, a new \proglang{R} package
79 for numerical calculation of Weierstrass and Jacobi elliptic
80 functions, theta functions and modular functions; it is based
81 on~\citet{hankin2006}. The emphasis is on efficient numerical
82 calculation, and informative visualization techniques.
83
84 The package is available on CRAN,
85 \url{https://CRAN.R-project.org/package=elliptic} \citep{rcore2005}.
86
87 \section{Elliptic functions}\label{section:introduction}
88
89 This section gives a very brief introduction to elliptic functions.
90 For more detail and rigorous derivations, the reader is referred to
91 the classic literature: the standard reference would
92 be~\cite{whittaker1952}. \cite{chandrasekharan1985} approaches the
93 field from a more modern perspective, and \cite{abramowitz1965}
94 provide the definitive reference work for the case of real invariants.
95
96 A meromorphic function~$f$ is said to be elliptic
97 if~$\exists\,\omega_1,\omega_2\in\mathbbm{C}$
98 with~$\omega_2/\omega_1\in\mathbbm{C}\backslash\mathbbm{R}$ such that
99
100 \begin{equation}
101 f(z)=f(z+2m\omega_1+2n\omega_2)
102 \end{equation}
103 whenever~$f(z)$ is defined and~$m,n\in\mathbbm{Z}$. Notation in this
104 paper is consistent with that of~\citet{abramowitz1965}; $\omega_1$
105 and~$\omega_2$ are called the {\em half periods}. In 1862,
106 Weierstrass introduced his~$\wp$ function which is defined as
107 \begin{equation}\label{direct.sum}
108 \wp(z)=
109 \frac{1}{z^2}+
110 \sum_{m,n\in\mathbbm{Z}\atop m,n\neq 0}
111 \left\{
112 \frac{1}{\left(z-2m\omega_1-2n\omega_2\right)^2}
113 -\frac{1}{\left( 2m\omega_1+2n\omega_2\right)^2}
114 \right\}.
115 \end{equation}
116 The~$\wp$ function is, in a well defined sense, the simplest
117 nontrivial elliptic function~\citep{whittaker1952}. Given this, we
118 have a Laurent expansion of the form
119 \begin{equation}
120 \wp(z)-z^{-2}=\frac{1}{20}g_2z^2+\frac{1}{28}g_3z^4+O(z^6)
121 \end{equation}
122 with
123 \begin{equation}
124 g_2=60{\sum}'\frac{1}{\left(2m\omega_1+2n\omega_2\right)^4},
125 \qquad
126 g_3=140{\sum}'\frac{1}{\left(2m\omega_1+2n\omega_2\right)^6},
127 \end{equation}
128 where a prime indicates summation over~$\mathbbm{Z}^2$
129 excluding~$(m,n)=(0,0)$. For reasons to be made clear in
130 section~\ref{section.unimodularity}, $g_2$ and~$g_3$ are known as the
131 {\em invariants}. Other equivalent forms for~$\wp$ include its
132 differential equation
133 \begin{equation}\label{P.differential.eqn.definition}
134 \left(\frac{d\wp}{dz}\right)^2=4\wp^3-g_2\wp-g_3
135 \end{equation}
136 and the relation
137 \begin{equation}\label{P.integral.definition}
138 z=\int_{t=w}^\infty\frac{dt}{\sqrt{4t^3-g_2t-g_3}}
139 \end{equation}
140 which is equivalent to~$w=\wp(z)$.
141
142 Related functions include the zeta function~$\zeta(z)$, defined by
143 \begin{equation}\label{zeta.definition}
144 \frac{d\zeta(z)}{dz}=-\wp(z)
145 \end{equation}
146 and the sigma function~$\sigma(z)$, defined by
147 \begin{equation}\label{sigma.definition}
148 \frac{d\log\sigma(z)}{dz}=\zeta(z),\qquad{\lim_{\mbox{\tiny $z\longrightarrow
149 0$}}}\left[\frac{\sigma(z)}{z}\right]=1
150 \end{equation}
151 (neither~$\sigma(z)$ nor~$\zeta(z)$ is elliptic). It may be
152 shown\label{zeta.analytic} that~$\zeta(z)$ is analytic except for
153 points on the lattice of periods, at which it has simple poles with
154 residue~1. One classic result is due to Legendre:
155 if~$\omega_1,\omega_2$ is a pair of basic periods\footnote{A pair of
156 basic periods is one that generates the period lattice. Basic periods
157 are not unique as many pairs of periods may generate the same lattice.
158 However, there is one pair of basic periods, the {\em fundamental}
159 periods that are, in a well-defined sense,
160 optimal~\citep{chandrasekharan1985}.},
161 with~$\rm{Im}(\omega_2/\omega_1)>0$, then
162 \begin{equation}
163 \eta_1\omega_2-\eta_2\omega_1=\pi i\label{legendre}
164 \end{equation}
165 where~$\eta_1=\zeta(\omega_1)$ and~$\eta_2=\zeta(\omega_2)$.
166
167 \subsection{Jacobian elliptic functions}
168 Jacobi approached the description of elliptic functions from a
169 different perspective~\citep{weisstein2005}. Given~$m=k^2$ and~$m_1$
170 with~$m+m_1=1$, Jacobi showed that if
171 \[
172 u=\int_{t=0}^\phi\frac{dt}{\sqrt{(1-t^2)(1-mt^2)}}
173 \]
174 the functions~${\rm sn}(u,k)$, ${\rm cn}(u,k)$ and~${\rm dn}(u,k)$
175 defined by
176 \begin{equation}\label{sn.definition}
177 {\rm sn} u=\sin\phi,\qquad
178 {\rm cn} u=\cos\phi,\qquad
179 {\rm dn} u=\sqrt{1-k^2\sin^2\phi}
180 \end{equation}
181 are elliptic with periods
182 \begin{equation}
183 K=\int_{\theta=0}^{\pi/2}\frac{d\theta}{\sqrt{1-m\sin^2\theta}}
184 \end{equation}
185 and
186 \begin{equation}
187 iK'=i\int_{\theta=0}^{\pi/2}\frac{d\theta}{\sqrt{1-m_1\sin^2\theta}}.
188 \end{equation}
189 The Jacobian elliptic functions are encountered in a variety of
190 contexts and bear a simple analytical relation with the
191 Weierstrass~$\wp$ function.
192
193 \section{Numerical evaluation and Jacobi's theta functions}
194
195 Although equation~\ref{direct.sum} is absolutely convergent, it
196 converges too slowly to be of use in practical work, and an alternative
197 definition is needed.
198
199 Jacobi presented his four theta functions in 1829 and, although they
200 have interesting properties in their own right, here they are used to
201 provide efficient numerical methods for calculation of the elliptic
202 functions above. They are defined as follows:
203
204 \begin{eqnarray}\label{theta.defn}
205 \theta_1(z,q)&=&2q^{1/4}\sum_{n=0}^\infty(-1)^nq^{n(n+1)}\sin(2n+1)z\\
206 \theta_2(z,q)&=&2q^{1/4}\sum_{n=0}^\infty q^{n(n+1)}\cos(2n+1)z\\
207 \theta_3(z,q)&=&1+2\sum_{n=1}^\infty q^{n^2}\cos 2nz\\
208 \theta_4(z,q)&=&1+2\sum_{n=1}^\infty(-1)^n q^{n^2}\cos 2nz
209 \end{eqnarray}
210 It may be seen that, provided~$|q|<1$, the series converges for
211 all~$z\in\mathbbm{C}$. Indeed, the convergence is very rapid: the
212 number of correct significant figures goes as the square of the number
213 of terms. It should be noted that there are different notations in
214 use, both for the four function names, and for the independent
215 variables.
216
217 All the functions described in section~\ref{section:introduction} may
218 be expressed in terms of the theta functions. This is the default
219 method in \pkg{elliptic}, although alternative algorithms are
220 implemented where possible to provide a numerical and notational
221 check.
222
223 For example, Weierstrass's~$\wp$ function is given by
224 \begin{equation}\label{P.in.terms.of.theta}
225 \wp(z)=
226 \frac{\pi^2}{4\omega_1^2}\left(
227 \frac{\theta_1'(0,q)\theta_2(v,q)}{\theta_2(0,q)\theta_1(v,q)}
228 \right)^2
229 \end{equation}
230 where~$q=e^{i\omega_2/\omega_1}$; the other functions have similar
231 theta function definitions.
232
233 <<require_packages, echo=FALSE,print=FALSE>>=
234 <<results=hide>>=
235 require(elliptic)
236 require(emulator)
237 require(calibrator)
238 @
239
240 \section[Package ''elliptic'' in use]{Package \pkg{elliptic} in use}
241
242 This section shows \pkg{elliptic} being used in a variety of contexts.
243 First, a number of numerical verifications of the code are presented;
244 then, elliptic and related functions are visualized using the function
245 \code{view()}; and finally, the package is used to calculate flows
246 occurring in an oceanographic context.
247
248 The primary function in package \pkg{elliptic} is~\code{P()}: this
249 calculates the Weierstrass~$\wp$ function, and may take named
250 arguments that specify either the invariants~\code{g} or half
251 periods~\code{Omega}:
252 <<simple_usage_of_P,echo=TRUE,print=FALSE>>=
253 z <- 1.9+1.8i
254 P(z,g=c(1,1i))
255 P(z,Omega=c(1,1i))
256 @
257
258 \subsection{Numerical verification}
259
260 Work in the field of elliptic functions is very liable to
261 mistakes\footnote{\cite{abramowitz1965} state that there is a
262 ``bewildering'' variety of notations in use; the situation has become
263 more confusing in the intervening 40 years.}, and package
264 \pkg{elliptic} includes a number of numerical checks to guard against
265 notational inexactitude. These checks generally use the convenient
266 (trivial) function \code{maxdiff()} that shows the maximum absolute
267 difference between its two arguments:
268 <<define_maxdiff,echo=TRUE,print=FALSE>>=
269 maxdiff <- function(x,y){max(abs(x-y))}
270 @
271
272 For example, we may compare the output of \code{P()}, which uses
273 equation~\ref{P.in.terms.of.theta}, against the straightforward
274 Laurent expansion, used by \code{P.laurent()}:
275
276 <<laurent,echo=TRUE,print=FALSE>>=
277 g <- c(3,2+4i)
278 z <- seq(from=1,to=0.4+1i,len=34)
279 <<maxdiff_laurent,echo=TRUE,print=TRUE>>=
280 maxdiff(P(z,g), P.laurent(z,g))
281 @
282
283 showing reasonable agreement; note that function \code{P()} uses the
284 conceptually distinct theta function formula of
285 equation~\ref{P.in.terms.of.theta}. Package \pkg{elliptic} includes a
286 large number of such numerical verification tests in the \code{test}
287 suite provided in the package, but perhaps more germane is the
288 inclusion of named identities appearing in \cite{abramowitz1965}. For
289 example, consider function~\code{e18.10.9()}, named for the equation
290 number of the identity appearing on page 650. This function returns
291 the difference between the (algebraically identical) left and right
292 hand side of three grouped identities:
293 \begin{eqnarray}
294 12\omega_1^2e_1 &=& \hphantom{-}\pi^2\left[\theta_3^4(0,q)+\theta_4^4(0,q)\right]\nonumber\\
295 12\omega_1^2e_2 &=& \hphantom{-}\pi^2\left[\theta_2^4(0,q)-\theta_4^4(0,q)\right]\\
296 12\omega_1^2e_3 &=& - \pi^2\left[\theta_3^4(0,q)+\theta_4^4(0,q)\right]\nonumber
297 \end{eqnarray}
298 where~$q=e^{-\pi K'/K}$. From the manpage:
299
300 <<abs_e18.10.9,echo=TRUE,print=TRUE>>=
301 abs( e18.10.9(parameters(g=g)))
302 @
303 again showing reasonably accurate numerical results, but perhaps
304 more importantly explicitly verifying that the notational scheme used
305 is internally consistent.
306
307 Although the examples above use the invariants~\code{g2} and \code{g3}
308 to define the elliptic function and its periods, sometimes the
309 fundamental periods are known and the invariants are desired. This is
310 done by function \code{g.fun()}, which takes the fundamental periods
311 as arguments and returns the two invariants~$g_2$ and~$g_3$. Observe
312 that there are many pairs of basic periods that generate the same
313 lattice---see figure~\ref{latplot}---but it usual to specify the
314 unique {\em fundamental periods} as this pair usually has desirable
315 numerical convergence properties.
316
317 \begin{figure}[htbp]
318 \begin{center}
319 <<lattice_figure,fig=TRUE>>=
320 jj <- parameters(g=c(1+1i,2-3i))$Omega
321 latplot(jj,xlim=c(-4,4),ylim=c(-4,4),xlab="Re(z)",
322 ylab="Im(z)")
323 polygon(Re(c(jj[1],sum(jj),jj[2],0)),
324 Im(c(jj[1],sum(jj),jj[2],0)),lwd=2,col="gray90",pch=16,cex=3)
325
326 kk <- -c(3*jj[1] + 2*jj[2] , jj[1] + jj[2]) #det(matrix(c(3,2,1,1),2,2,T)==1
327
328 polygon(Re(c(kk[1],sum(kk),kk[2],0)),
329 Im(c(kk[1],sum(kk),kk[2],0)),lwd=2,col="gray30",pch=16,cex=3)
330 @
331 \caption{The\label{latplot} lattice generated by~$\wp(z;1+i,2-3i)$;
332 fundamental period parallelogram shown in light gray and a basic
333 period parallelogram shown in darker gray}
334 \end{center}
335 \end{figure}
336
337 \subsubsection{Unimodularity}\label{section.unimodularity}
338 Many functions of the package are {\em unimodular}. The
339 invariants~$g_2$ and~$g_3$ are defined in terms of a pair of basic
340 periods~$\omega_1$ and~$\omega_2$. However, any pair of basic periods
341 should have the same invariants, because any pair of basic periods
342 will define the same elliptic function (hence the name). Basic period
343 pairs are related by a unimodular transformation:
344 if~$\omega_1,\omega_2$ and~$\tilde{\omega}_1,\tilde{\omega}_2$ are two
345 pairs of basic periods then there exist integers~$a,b,c,d$
346 with~$ad-bc=1$ and
347 \[
348 \left(
349 \begin{array}{cc}
350 a&b\\
351 c&d
352 \end{array}
353 \right)
354 \left(
355 \!\!
356 \begin{array}{c}
357 \omega_1\\
358 \omega_2
359 \end{array}
360 \!\!
361 \right)=
362 \left(\!\!
363 \begin{array}{c}
364 \tilde{\omega}_1\\
365 \tilde{\omega}_2
366 \end{array}
367 \!\!
368 \right)
369 \]
370
371 Formally, a
372 unimodular function~$f(\cdot,\cdot)$ is one with arity~2---it is
373 conventional to write~$f(\mathbf{v})=f(a,b)$---and for which
374 \begin{equation}
375 f(\mathbf{v})=f(\mathbf{M}\mathbf{v})\end{equation} where~$\mathbf{M}$
376 is unimodular: that is, an integer matrix with a determinant of unity.
377 In this context, unimodular matrices (and the transformations they
378 define) are interesting because any two pairs of basic periods are
379 related by a unimodular transformation.
380
381 The package includes
382 functions that generate unimodular matrices. The underlying function
383 is \code{congruence()}, which generates~$2\times 2$ integer matrices
384 with a determinant of~1, given the first row. For example:
385 <<congruence,echo=TRUE,print=TRUE>>=
386 M <- congruence(c(4,9))
387 @
388 (observe that the determinant of~$\mathbf{M}$ is unity) and thus we
389 may verify the unimodularity of, for example, \code{g.fun()} by
390 evaluating the invariants for a pair of fundamental periods, and
391 comparing this with the invariants calculated for a pair of basic
392 periods that are related to the fundamental periods by a unimodular
393 transformation (here~$\mathbf{M}$). In \proglang{R} idiom:
394 <<define_o,echo=TRUE,print=FALSE>>=
395 o <- c(1,1i)
396 <<maxdiff_o,echo=TRUE,print=TRUE>>=
397 maxdiff(g.fun(o), g.fun(M %*% o,maxiter=800))
398 @
399 showing that the invariants for period pair~$o=(1,i)^T$ are almost
400 identical to those for period
401 pair~$o'=\mathbf{M}o=(4+9i,3+7i)^T$. Observe that the latter
402 evaluation requires many more iterations for accurate numerical
403 evaluation: this behaviour is typically encountered when considering
404 periods whose ratio is close to the real axis.
405
406 In addition, function \code{unimodular()} generates unimodular
407 matrices systematically, and function \code{unimodularity()} checks
408 for a function's being unimodular.
409
410 \subsubsection{Contour integration and the residue theorem}
411
412 As noted in section~\ref{zeta.analytic}, the zeta function~$\zeta(z)$
413 possesses a simple pole of residue~1 at the origin. The residue
414 theorem would imply that
415 \[
416 \varoint\zeta(z)\,dz=2\pi i
417 \]
418 when the contour is taken round a path that encircles the origin but
419 no other poles. This may be verified numerically using
420 \pkg{elliptic}'s \code{myintegrate} suite of functions, which
421 generalize the \pkg{stats} package's \code{integrate()} function to
422 the complex plane. Here, function \code{integrate.contour()} is used
423 to integrate round the unit circle. This function takes three
424 arguments: first, the function to be integrated; second, a function
425 that describes the contour to be integrated along; and third, a
426 function that describes the derivative of the contour. We may now
427 integrate over a closed loop, using arguments~\code{u}
428 and~\code{udash} which specify a contour following the unit circle:
429
430 <<u_udash,echo=FALSE,print=FALSE>>=
431 u <- function(x){exp(pi*2i*x)}
432 udash <- function(x){pi*2i*exp(pi*2i*x)}
433 Zeta <- function(z){zeta(z,g)}
434 Sigma <- function(z){sigma(z,g)}
435 WeierstrassP <- function(z){P(z,g)}
436 @
437
438 <<integrate,echo=TRUE,print=FALSE>>=
439 jj <- integrate.contour(Zeta,u,udash)
440 <<maxdiff_integrate,echo=TRUE,print=TRUE>>=
441 maxdiff(jj, 2*pi*1i)
442 @
443 showing reasonable numerical accuracy. Compare Weierstrass's~$\wp$
444 function, which has a second order pole at the origin:
445 <<abs_integrate,echo=TRUE,print=TRUE>>=
446 abs(integrate.contour(WeierstrassP,u,udash))
447 @
448
449 \subsubsection[The PARI system]{The \proglang{PARI} system}
450 Perhaps the most convincing evidence for numerical accuracy and
451 consistency of notation in the software presented here is provided by
452 comparison of the package's results with that of
453 \proglang{PARI}~\citep{batut2000}. The \proglang{PARI} system is an open-source project
454 aimed at number theorists, with an emphasis on pure mathematics; it
455 includes some elliptic function capability. Function \code{P.pari()}
456 of package \pkg{elliptic} calls the \code{pari} system directly to
457 evaluate elliptic functions from within an \proglang{R} session, enabling quick
458 verification:
459
460 \begin{Schunk}
461 \begin{Sinput}
462 > omega <- c(1,1i)
463 \end{Sinput}
464 \end{Schunk}
465 \begin{Schunk}
466 \begin{Sinput}
467 > z <- seq(from=pi,to=pi*1i,len=10)
468 \end{Sinput}
469 \end{Schunk}
470 \begin{Schunk}
471 \begin{Sinput}
472 > maxdiff(P.pari(z,Omega=omega), P(z,params=parameters(Omega=omega)))
473 \end{Sinput}
474 \begin{Soutput}
475 [1] 2.760239e-14
476 \end{Soutput}
477 \end{Schunk}
478
479 again showing reasonable agreement, this time between two independent
480 computational systems.
481
482 \subsection{Visualization of complex functions}
483
484 In the following, a Weierstrass elliptic function with invariants
485 of~$1+i$ and~$2-3i$ will be considered. The half periods
486 $\omega_1,\omega_2$ are first evaluated:
487
488 <<jj_omega,echo=TRUE,print=FALSE>>=
489 jj.omega <- half.periods(g=c(1+1i,2-3i))
490 @
491 and these may be visualized by using \code{latplot()}, as in
492 figure~\ref{latplot}. Figure~\ref{P.persp.re} shows the real part of
493 such a function, shown over part of the complex plane, and
494 figure~\ref{P.view} shows the same function using the \code{view()}
495 function.
496
497 <<calculate_wp_figure,echo=FALSE,print=FALSE,cache=TRUE>>=
498 x <- seq(from=-4, to=4, len=n)
499 y <- x
500 z <- outer(x,1i*x, "+")
501 f <- P(z, c(1+1i,2-3i))
502 @
503
504
505 %% Thanks to Dario Strbenac for the following structure
506 <<wp_figure_file>>=
507 png("wp_figure.png",width=800,height=800)
508 @
509
510 <<label=wp_figure_plot>>=
511 persp(x, y, limit(Re(f)), xlab="Re(z)",ylab="Im(z)",zlab="Re(P(z))",
512 theta=30, phi=30, r=1e9, border=NA, shade=0.8, expand=0.6)
513 @
514
515 <<label=wp_figure_close>>=
516 null <- dev.off()
517 @
518
519 \begin{figure}[htbp]
520 \begin{center}
521 \includegraphics{wp_figure.png}
522 \caption{Real part of~$\wp(z,1,1+2i)$. Note \label{P.persp.re}
523 the second order poles at each lattice point}
524 \end{center}
525 \end{figure}
526
527
528 <<thallerfig_file>>=
529 png("thallerfig.png",width=800,height=800)
530 @
531
532 <<label=thallerfig_plot>>=
533 par(pty="s")
534 view(x,y,f,code=0,real.contour=FALSE, imag.contour=FALSE,drawlabel=FALSE,col="red",axes=FALSE,xlab="Re(z)",ylab="Im(z)")
535 axis(1,pos = -4)
536 axis(2,pos = -4)
537 lines(x=c(-4,4),y=c(4,4))
538 lines(y=c(-4,4),x=c(4,4))
539 @
540
541 <<label=thallerfig_close>>=
542 null <- dev.off()
543 @
544
545
546 \begin{figure}[htbp]
547 \begin{center}
548 \includegraphics{thallerfig.png}
549 \caption{Visualization of~$\wp(z,1,1+2i)$\label{P.view} using the
550 scheme of \cite{thaller1998}: white corresponds to a pole, black
551 to a zero, and full saturation to~$|\wp(z)|=1$. The poles
552 of~$\wp(z)$ occur on a regular lattice, and the zeros on two
553 shifted lattices. Note how each of the poles is surrounded by
554 two cycles of hue, indicating that they are of second order; and
555 each of the zeros is surrounded by one cycle of hue, indicating
556 that they are simple roots}
557 \end{center}
558 \end{figure}
559
560 The~$\sigma$ function with the same invariants is visualized in
561 figure~\ref{sigma.green}, showing that its zeros lie on the same
562 lattice as figure~\ref{latplot}.
563
564 <<sigma_green_calc,cache=TRUE,echo=FALSE,print=FALSE>>=
565 x <- seq(from= -12, to=12, len=n)
566 y <- x
567 z <- outer(x, 1i*y, "+")
568 f <- sigma(z, c(1+1i,2-3i))
569 @
570
571 <<sigma_green_file>>=
572 png("sigma_green.png",width=800,height=800)
573 @
574
575 <<sigma_green_plot>>=
576 par(pty="s")
577 view(x,y,f,scheme=4,real.contour=FALSE,drawlabels=FALSE,axes=FALSE, xlab="Re(z)",ylab="Im(z)")
578 axis(1,pos= -12)
579 axis(2,pos= -12)
580 lines(x=c(-12,12),y=c(12,12))
581 lines(y=c(-12,12),x=c(12,12))
582 lines(x=c(-12,12),y=-c(12,12))
583 lines(y=c(-12,12),x=-c(12,12))
584 @
585
586
587 <<sigma_green_close>>=
588 null <- dev.off()
589 @
590
591 \begin{figure}[htbp]
592 \begin{center}
593 \includegraphics{sigma_green.png}
594 \caption{Visualization of~$f=\sigma(z,1,1+2i)$ using
595 \code{view()}; colour indicates~${\rm Arg}(f)$. Thus points at
596 which~$f(z)$ is on the negative real axis, that is
597 $\{z\colon f(z)\in\mathbbm{R}^-\}$, are visible as discontinuities of
598 (colourimetric) value. These discontinuities are semi-infinite;
599 note that the zeros of~$f$ occur, \label{sigma.green} at the
600 (finite) end of each line, on a regular lattice. As~$|z|$
601 increases, each discontinuity threads its way through an
602 increasing number of other discontinuities and zeros, and the
603 spacing between the discontinuities becomes less and less}
604 \end{center}
605 \end{figure}
606
607 Figure~\ref{zeta.thaller} shows the zeta function, and
608 figure~\ref{sn.thaller} shows Jacobi's ``sn'' function.
609
610 <<calculate_zeta,echo=FALSE,print=FALSE,cache=TRUE>>=
611 zeta.z <- zeta(z, c(1+1i,2-3i))
612 @
613
614 <<zetafig_file>>=
615 png("zetafig.png",width=800,height=800)
616 @
617
618 <<label=zetafig_plot>>=
619 par(pty="s")
620 view(x,y,zeta.z,scheme=0,real.contour=FALSE,drawlabels=FALSE,xlab="Re(z)",ylab="Im(z)")
621 @
622
623 <<label=zetafig_close>>=
624 null <- dev.off()
625 @
626
627 \begin{figure}[htbp]
628 \begin{center}
629 \includegraphics{zetafig.png}
630 \caption{Visualization of~$\zeta(z,1,1+2i)$ using \code{view()}
631 and the colouring scheme of Thaller. Poles appear as white
632 regions, and zeros as black regions. \label{zeta.thaller} Each
633 pole is of single order, each zero is a simple root (one cycle of
634 hue). The poles occur on a lattice; there is no simple pattern to
635 the zeros. Note the overall tendency towards the edges of the
636 square to whiteness: $|f|$ increases with~$|z|$ as per
637 equation~\ref{zeta.definition}}
638 \end{center}
639 \end{figure}
640
641 <<calculate_sn,echo=FALSE,print=FALSE,cache=TRUE>>=
642 jj <- seq(from=-40,to=40,len=n)
643 m <- outer(jj,1i*jj,"+")
644 f <- sn(u=5-2i,m=m,maxiter=1000)
645 @
646
647 <<sn_figure_file>>=
648 png("sn_figure.png",width=800,height=800)
649 @
650
651 <<sn_figure_plot>>=
652 par(pty="s")
653 view(jj,jj,f,scheme=0,r0=1/5,real=T,imag=F,levels=c(0,-0.4,-1),drawlabels=F,xlab="Re(m)",ylab="Im(m)")
654 @
655
656 <<sn_figure_close>>=
657 null <- dev.off()
658 @
659
660 \begin{figure}[htbp]
661 \begin{center}
662 \includegraphics{sn_figure.png}
663 \caption{Jacobi's ``sn'' function\label{sn.thaller} using the elliptic
664 package. Here, $f={\rm sn}(5-2i,m)$ is visualized, with background
665 utilizing Thaller's scheme, and contours of equal~${\rm Re}(f)$ at
666 three selected values shown as black lines. Note the aperiodic
667 arrangement of poles (white areas) and zeros (black areas)}
668 \end{center}
669 \end{figure}
670
671
672 \subsection{Potential flow}
673
674 One application of complex analysis is to fluid dynamics. In
675 particular, potential flow (steady, two-dimensional, inviscid,
676 incompressible) may be studied with the aid of analytic complex
677 functions. Here I show how the elliptic functions discussed in this
678 paper may be used to simulate potential flow in a rectangular domain.
679
680 Although the tenets of potential flow appear to be absurdly
681 idealized\footnote{\cite{feynman1966} famously described potential flow
682 as the study of ``dry water''}, it is nevertheless a useful technique
683 in many branches of practical fluid mechanics: it is often used to
684 calculate a ``theoretical'' flowfield with which measured velocities
685 may be compared. A short sketch of potential theory is given here but
686 the reader is referred to~\cite{milne1949} for a full exposition.
687 Briefly, we define a {\em complex potential} $w(z)$ to be a complex
688 function
689 \[
690 w(z)=\phi+i\psi\] and observe that both~$\phi$ and~$\psi$ obey
691 Laplace's equation if~$w$ is differentiable. Given this, we may take
692 the velocity vector~$\mathbf{v}=(v_x,v_y)$ of the fluid to be
693 \[
694 v_x=\frac{\partial\phi}{\partial x},\qquad
695 v_y=\frac{\partial\phi}{\partial y},\qquad
696 \]
697 and observe that streamlines are given by contours of equal~$\psi$;
698 contours of equal~$\phi$ are called equipotential lines. The two
699 systems of lines cross at right angles (this follows from the
700 Cauchy-Riemann conditions).
701
702 Consider, for example, the function~$w(z)=z^2$, whose associated flow
703 field is shown in figure~\ref{z.squared.pot.flow}. This corresponds
704 to a stagnation point, at which the speed vanishes; the streamlines
705 (solid) intersect the equipotential lines (dashed) at right angles.
706
707 <<stag_calc,echo=FALSE,print=FALSE,cache=TRUE>>=
708 f <- function(z){1i*z^2}
709 x <- seq(from=-6,to=6,len=n)
710 y <- seq(from=-6,to=6,len=n)
711 z <- outer(x,1i*y,"+")
712 @
713
714
715 <<stag_point_file>>=
716 png("stag_point.png",width=800,height=800)
717 @
718
719 <<stag_point_plot>>=
720 par(pty="s")
721 view(x,y,f(z),nlevels=14,imag.contour=TRUE,real.cont=TRUE,scheme=-1,
722 drawlabels=FALSE,
723 axes=FALSE,xlab="Re(z)",ylab="Im(z)")
724 axis(1,pos=-6)
725 axis(2,pos=-6)
726 lines(x=c(-6,6),y=c(6,6))
727 lines(y=c(-6,6),x=c(6,6))
728 d1 <- c(-0.1,0,0.1)
729 d2 <- c( 0.1,0,0.1)
730 lines(x=d1,y=1+d2)
731 lines(x=d1,y=-1-d2)
732 lines(x=1-d2,y=d1)
733 lines(x=-1+d2,y=d1)
734 @
735
736 <<stag_point_close>>=
737 null <- dev.off()
738 @
739
740 \begin{figure}[htbp]
741 \begin{center}
742 \includegraphics{stag_point.png}
743 \caption{Potential flow on the complex plane:
744 field\label{z.squared.pot.flow} corresponding to the
745 function~$(z)=z^2$. Solid lines represent streamlines and dotted
746 lines represent equipotentials; these intersect at right angles.
747 Note stagnation point at the origin}
748 \end{center}
749 \end{figure}
750
751 Now consider a slightly more complicated case. A point source of
752 strength~$m$ at~$z_0$ may be represented by the function
753 \[m\log(z-z_0)\] (a sink corresponds to~$m<0$). Any finite number
754 of sources or sinks may be combined, as in~$\sum_i m_i\log(z-z_i)$
755 where the~$i^{\rm th}$ source is at~$z_i$ and has strength~$m_i$,
756 because the system is linear\footnote{It is often more convenient to
757 work with the algebraically equivalent form~$\log\left(\prod
758 (z-z_i)^{m_i}\right)$, as there are fewer branch cuts to deal with.}.
759 Figure~\ref{upper.halfplane.flow} shows two sources and two sinks, all
760 of equal strength. Because the flowfield is symmetric with respect to
761 the real axis, there is no flux across it; we may therefore ignore the
762 flow in the lower half plane (ie~$\{z\colon \rm{Im}(z)<0\}$) and consider
763 the flow to be bounded below by the real axis. This is known as {\em
764 the method of images}~\citep{milne1949}.
765
766
767 <<two_calc,echo=FALSE,print=FALSE,cache=TRUE>>=
768 f <- function(z){1i*log((z-1.7+3i)*(z-1.7-3i)/(z+1-0.6i)/(z+1+0.6i))}
769 x <- seq(from=-6,to=6,len=n)
770 y <- seq(from=-6,to=6,len=n)
771 z <- outer(x,1i*y,"+")
772 @
773
774
775 <<two_sources_two_sinks_file>>=
776 png("two_sources_two_sinks.png",width=800,height=800)
777 @
778 <<label=two_sources_two_sinks_plot>>=
779 par(pty="s")
780 view(x,y,f(z),nlevels=24,imag.contour=TRUE,real.cont=TRUE,scheme=17,power=0.1,drawlabels=FALSE,axes=FALSE,xlab="Re(z)",ylab="Im(z)")
781 axis(1,pos=-6)
782 axis(2,pos=-6)
783 lines(x=c(-6,6),y=c(6,6))
784 lines(y=c(-6,6),x=c(6,6))
785 @
786
787 <<two_sources_two_sinks_close>>=
788 null <- dev.off()
789 @
790
791 \begin{figure}[htbp]
792 \begin{center}
793 \includegraphics{two_sources_two_sinks.png}
794 \caption{Potential flow in on the complex plane: two sources and
795 two sinks, all of equal strength. Solid
796 \label{upper.halfplane.flow} lines denote streamlines, dotted
797 lines equipotentials; colour scheme uses the \code{hcl()} system:
798 hue varies with the argument, and chrominance varies with the
799 modulus, of the potential. There is no flux between the lower and
800 the upper half plane, but there is flux out of, and in to, the
801 diagram. Note the stagnation point at approximately $5+0i$}
802 \end{center}
803 \end{figure}
804
805 Now, one may transform a potential flowfield into another form using a
806 conformal mapping from the~$z$- plane to the~$\zeta$- plane,
807 traditionally denoted
808 \[
809 \zeta=f(z).
810 \]
811
812 This technique finds application when flow is desired (in the~$\zeta$-
813 plane) that obeys some specific boundary condition that is simple to
814 specify in the~$z$- plane.
815
816 %In the present case, we make use of the Schwartz-Christoffel theorem,
817 %which states that if~$a,b,c,\ldots$ are~$n$ points on the real axis of
818 %the~$\zeta$- plane with~$a<b<c<\ldots$,
819 %and~$\alpha,\beta,\gamma,\ldots$ the interior angles of a simple
820 %closed polygon of~$n$ vertices, then
821 %\begin{equation}
822 %\frac{dz}{d\zeta}=K
823 %\left(\zeta-a\right)^{\alpha/\pi-1}
824 %\left(\zeta-b\right)^{\beta/\pi-1}
825 %\left(\zeta-c\right)^{\gamma/\pi-1}
826 %\ldots
827 %\end{equation}
828 %transforms the real axis of the~$\zeta$- plane into the boundary of a
829 %closed polygon in the~$z$- plane with interior
830 %angles~$\alpha,\beta,\ldots$. If the polygon is simple, then the
831 %upper half of the~$\zeta$- plane maps to the interior of the polygon.
832 %
833 %Here the Schwartz Christoffel theorem~\cite{milne1949} is applied to a
834 %rectangle, in which~$\alpha=\beta=\gamma=\delta=\pi/2$. With suitably
835 %chosen~$a,b,c,d$ we see that the map from the upper half plane of
836 %the~$\zeta$- plane to a rectangle in the~$z$- plane is given by
837
838 In this case, we seek a conformal transformation that maps the upper
839 half plane to a rectangle. If we consider the flowfield shown in
840 figure~\ref{upper.halfplane.flow}, then the map given by
841 \[
842 \zeta=\int\frac{dz}{\sqrt{(1-a^2z^2)(1-z^2)}}
843 \]
844 takes the upper half plane of the~$\zeta$- plane to a rectangle in
845 the~$z$- plane ~\citep{milne1949}. Using
846 equation~\ref{sn.definition}, this is equivalent to~$z={\rm
847 sn}(\zeta;m)$, where~${\rm sn}(\cdot,\cdot)$ is a Jacobian elliptic
848 function and~$m$ a constant of integration.
849
850 Figure~\ref{box.flow} shows the resulting flow field: observe how the
851 flow speed, which is proportional to the spacing between the
852 streamlines, is very small near the left-hand edge of the rectangle.
853
854
855 <<rect_calc3,echo=FALSE,print=FALSE,cache=TRUE>>=
856 m <- 0.5
857 K <- K.fun(m)
858 iK <- K.fun(1-m)
859
860 #b <- sn(1.8 + 0.8i, m=m) # 1.8 to the right and 0.8 up.
861 #b <- 0 # middle bottom
862 b <- sn(0 + 1i*iK/2,m=m) #dead centre of the rectangle.
863 #b <- -1 # lower left
864 #b <- 1/sqrt(m) # top right
865 #b <- -1/sqrt(m) # top left
866 #b <- 1e9*1i # top centre
867
868
869 a <- 1 #bottom right hand side corner
870
871
872 f <- function(z){1i*log((z-a)*(z-Conj(a))/(z-b)/(z-Conj(b)))}
873
874 x <- seq(from=-K,to=K,len=n)
875 y <- seq(from=0,to=iK,len=n)
876 z <- outer(x,1i*y,"+")
877 fsn <- f(sn(z,m=m))
878 @
879
880
881 <<rectangle_pot_flow_file>>=
882 png("rectangle_pot_flow.png",width=800,height=800)
883 @
884
885 <<rectangle_pot_flow_plot>>=
886 view(x,y,fsn,nlevels=44,imag.contour=FALSE,real.cont=TRUE,scheme=17,power=0.1,drawlabels=FALSE,axes=FALSE,xlab="",ylab="")
887 rect(-K,0,K,iK,lwd=3)
888 @
889
890 <<rectangle_pot_flow_close>>=
891 null <- dev.off()
892 @
893
894 \begin{figure}[htbp]
895 \begin{center}
896 \includegraphics{rectangle_pot_flow.png}
897 \caption{Potential flow in a rectangle of aspect ratio~2: source
898 and sink of equal \label{box.flow} strength. Colour scheme as in
899 figure~\ref{upper.halfplane.flow}. Note the dividing streamline
900 which terminates in a stagnation point on the rectangle boundary}
901 \end{center}
902 \end{figure}
903
904 \subsection{Bayesian analysis of potential flow}
905
906 When considering potential flows, it is often necessary to infer the
907 locations of singularities in the flow from sparse and imperfect
908 data~\citep{johnson2004}.
909
910 Here, I apply the methods of~\cite{kennedy2001}
911 and~\cite{kennedy2001a} (hereafter KOH and KOHa respectively) using
912 the~\pkg{BACCO} package~\citep{hankin2005} to assess some
913 characteristics of potential flow in a rectangle.
914
915 Kennedy and O'Hagan considered the following inference problem for a
916 set of parameters~$\theta\in{\mathcal R}^q$ that are inputs to a
917 computer program. Given an independent variable~$x\in{\mathcal R}^n$,
918 and a set of scalar (``field'') observations~$z=z(x)$, they assume
919
920 \begin{equation}
921 z(x)=\rho\cdot\eta\left(x,\theta\right)+
922 \delta(x)+\epsilon
923 \end{equation}
924 where~$\rho$ is a constant of proportionality (notionally unity);
925 $\eta(\cdot,\cdot)$ a Gaussian process with unknown coefficients;
926 $\theta$ the true, but unknown parameter values; $\delta(\cdot)$ a
927 model inadequacy term (also a Gaussian process with unknown
928 coefficients); and~$\epsilon\sim N(0,\lambda^2)$ uncorrelated normal
929 observational errors.
930
931 Inferences about~$\eta(\cdot,\cdot)$ are made from point observations
932 of the process: Kennedy and O'Hagan call these the ``code
933 observations'' on the grounds that their chief motivation was the
934 understanding of complex computer codes.
935
936 Here, potential flow in a rectangle is considered. The source is at
937 one corner of the rectangle, which is considered to have lower left
938 point~$(-1,0)$ and upper right point~$(1,1)$. The position of the
939 sink is unknown.
940
941 I now show how the position of the sink may be inferred from a sparse
942 and noisy set of observed fluid speeds. Similar inference problems
943 are encountered in practice when considering oceanographic flows such
944 as those occurring near deep sea vents, although the geometry is
945 generally more complex than considered here.
946
947 The independent variable~$\mathbf{x}$ is the two-dimensional position
948 within the rectangle, and the field observation~$z(\mathbf{x})$ is the
949 fluid speed at that point, plus obervational error~$\epsilon$. The
950 parameter set~$\theta$ thus has two degrees of freedom corresponding
951 to the $x-$ and $y-$ coordinates of the sink.
952
953 Field observations will be obtained numerically, using the
954 \pkg{elliptic} package. The simulated flowfield has a sink at a {\em
955 known} position---in this case the geometric centre of the
956 rectangle---and Bayesian methods will be used to infer its position
957 using only fluid speed data.
958
959 In the terminology of KOHa, dataset~\code{y} corresponds to modelled
960 fluid speed, obtained from the appropriate simulations carried out
961 with the sink placed at different locations within the rectangle.
962 Dataset~\code{z} corresponds to field observations, which in this
963 case is fluid speed at several points in the rectangle, obtained from
964 simulations with the sink at the centre of the rectangle.
965
966 <<bacco_flow,echo=FALSE,print=FALSE,cache=TRUE>>=
967 # Choose the size of the computational mesh:
968 n <- n_BACCO
969
970 # Choose the number of code observations for D1:
971 n.code.obs <- 30
972
973 # And the number of field observations for D2:
974 n.field.obs <- 31
975
976 # First, up the D1 design matrix. Recall that D1 is the set of code
977 # observations, which here means the observations of fluid speed when
978 # the sink is at a known, specified, position.
979
980 suppressWarnings(RNGversion("3.5.0"))
981 set.seed(0)
982
983 latin.hypercube <- function (n, d){
984 sapply(seq_len(d), function(...) { (sample(1:n) - 0.5)/n })
985 }
986
987
988 D1.elliptic <- latin.hypercube(n.code.obs , 4)
989 colnames(D1.elliptic) <- c("x","y","x.sink","y.sink")
990 D1.elliptic[,c(1,3)] <- (D1.elliptic[,c(1,3)] -0.5)*2
991 #D1.elliptic[,c(2,4)] <- D1.elliptic[,c(2,4)] *iK
992
993 # now a D2 design matrix. This is field observations: observations of
994 # fluid speed when the sink is at the true, unknown, specified,
995 # position.
996 D2.elliptic <- latin.hypercube(n.field.obs , 2)
997 colnames(D2.elliptic) <- c("x","y")
998 D2.elliptic[,1] <- (D2.elliptic[,1] -0.5)*2
999
1000
1001 # Now a function that, given x and y and x.sink and y.sink, returns
1002 # the log of the fluid speed at x,y:
1003
1004 fluid.speed <- function(x.pos, y.pos, x.sink, y.sink){
1005
1006 a <- 1 #bottom right hand side corner
1007 b <- sn(x.pos/K + 1i*iK*y.pos,m=m) #position (x.pos , y.pos)
1008 f <- function(z){1i*log((z-a)*(z-Conj(a))/(z-b)/(z-Conj(b)))}
1009
1010 x <- seq(from=-K,to=K,len=n)
1011 y <- seq(from=0,to=iK,len=n)
1012 z <- outer(x,1i*y,"+")
1013 potential <- f(sn(z,m=m))
1014
1015 get.log.ke <- function(x,y,potential){
1016 jj <- Re(potential)
1017 jj.x <- cbind(jj[,-1]-jj[,-ncol(jj)],0)
1018 jj.y <- rbind(jj[-1,]-jj[-nrow(jj),],0)
1019 kinetic.energy <- jj.x^2 + jj.y^2
1020 n.x <- round(n * (x-(-1))/2)
1021 n.y <- round(n * y)
1022 return(log(kinetic.energy[n.x , n.y]+0.01))
1023 }
1024
1025 return(get.log.ke(x.pos,y.pos,potential))
1026 }
1027
1028 # now fill in code outputs y:
1029 y.elliptic <- rep(NA,nrow(D1.elliptic))
1030 for(i in 1:length(y.elliptic)){
1031 jj <- D1.elliptic[i,,drop=TRUE]
1032 y.elliptic[i] <- fluid.speed(jj[1],jj[2],jj[3],jj[4])
1033 }
1034
1035
1036 # Now do the field observations; here the source is known to be at the
1037 # centre of the rectangle:
1038
1039 z.elliptic <- rep(NA,nrow(D2.elliptic))
1040 for(i in 1:length(z.elliptic)){
1041 jj <- D2.elliptic[i,,drop=TRUE]
1042 z.elliptic[i] <- fluid.speed(jj[1],jj[2],0,0.5)
1043 }
1044
1045 # Create design matrix plus observations for didactic purposes:
1046 D1 <- round(cbind(D1.elliptic,observation=y.elliptic),2)
1047 D2 <- round(cbind(D2.elliptic,observation=z.elliptic),2)
1048
1049
1050 # create a data vector:
1051 d.elliptic <- c(y.elliptic , z.elliptic)
1052
1053 #now a h1.toy() equivalent:
1054 h1.elliptic <- function(x){
1055 out <- c(1,x[1])
1056 }
1057
1058 #now a H1.toy() equivalent:
1059 H1.elliptic <-
1060 function (D1)
1061 {
1062 if (is.vector(D1)) {
1063 D1 <- t(D1)
1064 }
1065 out <- t(apply(D1, 1, h1.elliptic))
1066 colnames(out)[1] <- "h1.const"
1067 return(out)
1068 }
1069
1070 h2.elliptic <-
1071 function(x){
1072 c(1,x[1])
1073 }
1074
1075 H2.elliptic <-
1076 function(D2){
1077 if (is.vector(D2)) {
1078 D2 <- t(D2)
1079 }
1080 out <- t(apply(D2, 1, h2.elliptic))
1081 colnames(out)[1] <- "h2.const"
1082 return(out)
1083 }
1084
1085
1086 #Now an extractor function:
1087 extractor.elliptic <-
1088 function (D1)
1089 {
1090 return(list(x.star = D1[, 1:2, drop = FALSE], t.vec = D1[,
1091 3:4, drop = FALSE]))
1092 }
1093
1094 # Now a whole bunch of stuff to define a phi.fun.elliptic()
1095 # and, after that, to call it:
1096 phi.fun.elliptic <-
1097 function (rho, lambda, psi1, psi1.apriori, psi2, psi2.apriori,
1098 theta.apriori, power)
1099 {
1100 "pdm.maker.psi1" <- function(psi1) {
1101 jj.omega_x <- diag(psi1[1:2])
1102 rownames(jj.omega_x) <- names(psi1[1:2])
1103 colnames(jj.omega_x) <- names(psi1[1:2])
1104 jj.omega_t <- diag(psi1[3:4])
1105 rownames(jj.omega_t) <- names(psi1[3:4])
1106 colnames(jj.omega_t) <- names(psi1[3:4])
1107 sigma1squared <- psi1[5]
1108 return(list(omega_x = jj.omega_x, omega_t = jj.omega_t,
1109 sigma1squared = sigma1squared))
1110 }
1111 "pdm.maker.psi2" <- function(psi1) {
1112 jj.omegastar_x <- diag(psi2[1:2])
1113 sigma2squared <- psi2[3]
1114 return(list(omegastar_x = jj.omegastar_x, sigma2squared = sigma2squared))
1115 }
1116 jj.mean <- theta.apriori$mean
1117 jj.V_theta <- theta.apriori$sigma
1118 jj.discard.psi1 <- pdm.maker.psi1(psi1)
1119 jj.omega_t <- jj.discard.psi1$omega_t
1120 jj.omega_x <- jj.discard.psi1$omega_x
1121 jj.sigma1squared <- jj.discard.psi1$sigma1squared
1122 jj.discard.psi2 <- pdm.maker.psi2(psi2)
1123 jj.omegastar_x <- jj.discard.psi2$omegastar_x
1124 jj.sigma2squared <- jj.discard.psi2$sigma2squared
1125 jj.omega_t.upper <- chol(jj.omega_t)
1126 jj.omega_t.lower <- t(jj.omega_t.upper)
1127 jj.omega_x.upper <- chol(jj.omega_x)
1128 jj.omega_x.lower <- t(jj.omega_x.upper)
1129 jj.a <- solve(solve(jj.V_theta) + 2 * jj.omega_t, solve(jj.V_theta,
1130 jj.mean))
1131 jj.b <- t(2 * solve(solve(jj.V_theta) + 2 * jj.omega_t) %*%
1132 jj.omega_t)
1133 jj.c <- jj.sigma1squared/sqrt(det(diag(nrow = nrow(jj.V_theta)) +
1134 2 * jj.V_theta %*% jj.omega_t))
1135 jj.A <- solve(jj.V_theta + solve(jj.omega_t)/4)
1136 jj.A.upper <- chol(jj.A)
1137 jj.A.lower <- t(jj.A.upper)
1138 list(rho = rho, lambda = lambda, psi1 = psi1, psi1.apriori = psi1.apriori,
1139 psi2 = psi2, psi2.apriori = psi2.apriori, theta.apriori = theta.apriori,
1140 power = power, omega_x = jj.omega_x, omega_t = jj.omega_t,
1141 omegastar_x = jj.omegastar_x, sigma1squared = jj.sigma1squared,
1142 sigma2squared = jj.sigma2squared, omega_x.upper = jj.omega_x.upper,
1143 omega_x.lower = jj.omega_x.lower, omega_t.upper = jj.omega_t.upper,
1144 omega_t.lower = jj.omega_t.lower, a = jj.a, b = jj.b,
1145 c = jj.c, A = jj.A, A.upper = jj.A.upper, A.lower = jj.A.lower)
1146 }
1147
1148 # OK, that's the function defined. Now to create some jj.* variables
1149 # to call it:
1150
1151 jj.psi1 <- c(rep(1,4),0.3)
1152 names(jj.psi1)[1:4] <- colnames(D1.elliptic)
1153 names(jj.psi1)[5] <- "sigma1squared"
1154
1155 jj.mean.psi1 <- rep(1,5)
1156 names(jj.mean.psi1) <- names(jj.psi1)
1157
1158 jj.sigma.psi1 <- diag(0.1,nrow=5)
1159 rownames(jj.sigma.psi1) <- names(jj.psi1)
1160 colnames(jj.sigma.psi1) <- names(jj.psi1)
1161
1162 jj.psi2 <- c(1,1,0.3)
1163 names(jj.psi2)[1:2] <- colnames(D2.elliptic)
1164 names(jj.psi2)[3] <- "sigma2squared"
1165
1166 jj.mean.psi2 <- rep(1,4)
1167 names(jj.mean.psi2) <- c("x.sink", "y.sink","rho","lambda")
1168
1169 jj.sigma.psi2 <- diag(0.1,4)
1170 rownames(jj.sigma.psi2) <- names(jj.mean.psi2)
1171 colnames(jj.sigma.psi2) <- names(jj.mean.psi2)
1172
1173 jj.mean.th <- c(1,0.5)
1174 names(jj.mean.th) <- colnames(D1.elliptic)[3:4]
1175
1176 jj.sigma.th <- diag(rep(1,2))
1177 rownames(jj.sigma.th) <- colnames(D1.elliptic)[3:4]
1178 colnames(jj.sigma.th) <- colnames(D1.elliptic)[3:4]
1179
1180 # Now call phi.fun.elliptic():
1181 phi.elliptic <-
1182 phi.fun.elliptic(
1183 rho=1,
1184 lambda=0.1,
1185 psi1=jj.psi1,
1186 psi2=jj.psi2,
1187 psi1.apriori=list(mean=jj.mean.psi1, sigma=jj.sigma.psi1),
1188 psi2.apriori=list(mean=jj.mean.psi2, sigma=jj.sigma.psi2),
1189 theta.apriori=list(mean=jj.mean.th, sigma=jj.sigma.th),
1190 power=2
1191 )
1192
1193 # Now an E.theta.elliptic():
1194 E.theta.elliptic <-
1195 function (D2 = NULL, H1 = NULL, x1 = NULL, x2 = NULL, phi, give.mean = TRUE)
1196 {
1197 if (give.mean) {
1198 m_theta <- phi$theta.apriori$mean
1199 return(H1(D1.fun(D2, t.vec = m_theta)))
1200 }
1201 else {
1202 out <- matrix(0, 2,2)
1203 rownames(out) <- c("h1.const","x")
1204 colnames(out) <- c("h1.const","x")
1205 return(out)
1206 }
1207 }
1208
1209 #Now an Edash.theta.elliptic(). Because the basis vector is not a
1210 #function of theta, this is a bit academic as we can use a function
1211 #that is identical to Edash.theta.toy():
1212
1213 Edash.theta.elliptic <-
1214 function (x, t.vec, k, H1, fast.but.opaque = FALSE, a = NULL,
1215 b = NULL, phi = NULL)
1216 {
1217 if (fast.but.opaque) {
1218 edash.mean <- a + crossprod(b, t.vec[k, ])
1219 }
1220 else {
1221 V_theta <- phi$theta.apriori$sigma
1222 m_theta <- phi$theta.apriori$mean
1223 omega_t <- phi$omega_t
1224 edash.mean <- solve(solve(V_theta) + 2 * omega_t, solve(V_theta,
1225 m_theta) + 2 * crossprod(omega_t, t.vec[k, ]))
1226 }
1227 jj <- as.vector(edash.mean)
1228 names(jj) <- rownames(edash.mean)
1229 edash.mean <- jj
1230 return(H1(D1.fun(x, edash.mean)))
1231 }
1232
1233
1234
1235 # Define a wrapper for equation 8:
1236 # First, calculate the constant to subtract to ensure that
1237 # the support has a maximum of about zero:
1238
1239 maximum.likelihood.support <- p.eqn8.supp(theta=c(0,1/2), D1=D1.elliptic, D2=D2.elliptic, H1=H1.elliptic, H2=H2.elliptic, d=d.elliptic, include.prior=FALSE, lognormally.distributed=FALSE, return.log=TRUE, phi=phi.elliptic)
1240
1241 support <- function(x){
1242 p.eqn8.supp(theta=x, D1=D1.elliptic, D2=D2.elliptic, H1=H1.elliptic, H2=H2.elliptic, d=d.elliptic, include.prior=FALSE, lognormally.distributed=FALSE, return.log=TRUE, phi=phi.elliptic) - maximum.likelihood.support
1243 }
1244
1245 #define a local function called optim() for aesthetic reasons (ie it
1246 # improves the appearance of the call to optim():
1247
1248 optim <-
1249 function(par,fn){
1250 stats::optim(par=par,fn=fn,control=list(fnscale = -1))$par
1251 }
1252
1253 @
1254
1255 The code evaluation design matrix~\code{D1} is chosen according to a
1256 random Latin hypercube design, and the observation is calculated using
1257 the \pkg{elliptic} package:
1258
1259 <<head_D1,echo=TRUE,print=TRUE>>=
1260 head(D1)
1261 @
1262
1263 So the first line shows a simulation with the sink
1264 at~(\Sexpr{D1[1,3]},\Sexpr{D1[1,4]}); the log of the fluid speed
1265 at~(\Sexpr{D1[1,1]}, \Sexpr{D1[1,2]}) is~\Sexpr{D1[1,5]}. There are a
1266 total of~\Sexpr{n.code.obs} such observations. Figure~\ref{code.obs}
1267 shows these points superimposed on the ``true'' flow field.
1268
1269 The field observations are similarly determined:
1270 <<head_D2,echo=TRUE,print=TRUE>>=
1271 head(D2)
1272 @
1273
1274 showing that the first field observation, at~(\Sexpr{D2[1,1]},
1275 \Sexpr{D2[1,2]}), is~\Sexpr{D2[1,3]}. There are a total
1276 of~\Sexpr{n.field.obs} such observations. Figure~\ref{field.obs}
1277 shows the first code observation in the context of the ``true'' flow
1278 field.
1279
1280 <<calc_b_sn,echo=FALSE,print=FALSE,cache=TRUE>>=
1281 b <- sn(D1[1,3] + 1i*D1[1,4],m=m) #point corresponding to first line of D1
1282 fsnz2 <- f(sn(z,m=m))
1283 @
1284
1285 <<code_obs_file>>=
1286 png("code_obs.png",width=800,height=800)
1287 @
1288
1289 <<code_obs_plot>>=
1290 view(x,y,fsnz2,nlevels=44,imag.contour=FALSE,real.cont=TRUE,scheme=-1,drawlabels=FALSE,axes=FALSE,xlab="",ylab="")
1291 points(x=K*D1[1,1],y=D1[1,2]*iK,pch=4)
1292 rect(-K,0,K,iK,lwd=3)
1293 @
1294
1295 <<code_obs_close>>=
1296 null <- dev.off()
1297 @
1298
1299 \begin{figure}[htbp]
1300 \begin{center}
1301 \includegraphics{code_obs.png}
1302 \caption{Streamlines\label{code.obs} of first code
1303 observation point; field observation point shown as a cross.
1304 The sink is at~(\Sexpr{D1[1,3]},\Sexpr{D1[1,4]})}
1305 \end{center}
1306 \end{figure}
1307
1308 <<calc_b2,echo=FALSE,print=FALSE,cache=TRUE>>=
1309 b <- sn(0 + 1i*iK/2,m=m)
1310 fsnzz <- f(sn(z,m=m))
1311 @
1312
1313
1314 <<true_flow_file>>=
1315 png("true_flow.png",width=800,height=800)
1316 @
1317
1318 <<true_flow_plot>>=
1319 view(x,y,fsnzz,nlevels=44,imag.contour=FALSE,real.cont=TRUE,scheme=-1,drawlabels=FALSE,axes=FALSE,xlab="",ylab="")
1320 points(x=K*D2[,1],y=D2[,2]*iK,pch=4)
1321 rect(-K,0,K,iK,lwd=3)
1322 @
1323
1324 <<true_flow_close>>=
1325 null <- dev.off()
1326 @
1327
1328 \begin{figure}[htbp]
1329 \begin{center}
1330 \includegraphics{true_flow.png}
1331 \caption{Streamlines\label{field.obs}
1332 of ``true'' flow; field observation points shown as crosses}
1333 \end{center}
1334 \end{figure}
1335
1336 Kennedy and O'Hagan give, {\em inter alia,} an expression for the
1337 likelihood of any value of $\theta$ being the true parameter set (in
1338 this case, the true position of the sink) in terms of the code
1339 evaluations and field observations.
1340
1341 Here, function \code{support()} calculates the log-likelihood for a
1342 pair of coordinates of the sink. This may be evaluated at the centre
1343 of the rectangle, and again at the top left corner:
1344
1345
1346 <<support,echo=TRUE,print=TRUE>>=
1347 support(c(0,1/2)) #centre of the rectangle
1348 support(c(-1,1)) #top left corner
1349 @
1350
1351 showing, as expected, that the support is very much larger at the
1352 centre of the rectangle than the edge (here the arbitrary additive
1353 constant is such that the support at \code{c(0,1/2)} is exactly zero).
1354 It is now possible to identify the position of the sink that
1355 corresponds to maximum support using numerical optimization
1356 techniques:
1357
1358
1359 <<mle_calc,echo=FALSE,print=FALSE,cache=TRUE>>=
1360 mle <- optim(c(0,1/2),support)
1361 @
1362
1363 \begin{Schunk}
1364 \begin{Sinput}
1365 (mle <- optim(c(0,1/2),support))
1366 \end{Sinput}
1367 \end{Schunk}
1368
1369 <<print_mle,echo=FALSE,print=TRUE>>=
1370 mle
1371 @
1372
1373 Thus the maximum likelihood estimate for the sink is a distance of
1374 about~0.2 from the true position. The support at this point is
1375 about~3.9 units of likelihood:
1376
1377 <<support_of_mle,echo=TRUE,print=TRUE>>=
1378 support(mle)
1379 @
1380
1381 \subsubsection{Discussion of Bayesian statistical analysis}
1382
1383 The above example shows the ideas of KOH being applied
1384 straightforwardly, but with the novel twist of $\theta$ being
1385 interpreted as physical characteristics of a fluid flow. In this
1386 case~$\theta$ is the coordinates of the sink.
1387
1388 The MLE is better supported than the true position by about~3.9 units
1389 of likelihood: thus, in the language of~\cite{edwards1992}, the
1390 hypothesis of $\theta_\mathrm{true}=(0,0.5)$ would not be rejected if
1391 one accepted Edwards's 2 units of likelihood per degree of freedom.
1392
1393 The discrepancy between~$\hat{\theta}$ and~$\theta_\mathrm{true}$ (a
1394 distance of about 0.2) may be due to due to the coarseness of the form
1395 adopted for the basis functions, and better results might be obtained
1396 by using a more sophisticated system of model inadequacy than the
1397 simple linear form presented here.
1398
1399 The methods of KOH allow one to make statistically robust statements
1400 about the physical characteristics of an interesting flow that are
1401 difficult to make in any other way.
1402
1403 \section{Conclusions}
1404
1405 Elliptic functions are an interesting and instructive branch of
1406 complex analysis, and are frequently encountered in applied
1407 mathematics: here they were used to calculate a potential flow field
1408 in a rectangle.
1409
1410 This paper introduced the \proglang{R} package \pkg{elliptic}, which was then
1411 used in conjunction with Bayesian statistical methods (the \pkg{BACCO}
1412 bundle) to make statistically sound inferences about a flow with
1413 uncertain parameters: in this case the position of the sink was
1414 estimated from a sparse and noisy dataset.
1415
1416
1417 \subsection*{Acknowledgements}
1418 I would like to acknowledge the many stimulating and helpful comments
1419 made by the \proglang{R}-help list over the years.
1420
1421 \bibliography{elliptic}
1422 \end{document}