Provide a coordinate-thorn and symmetry-thorn independent way of

specifying the shape of the physical domain and the location of the
boundary points.  The advantage of that is that it is now much easier
to change the resolution.


git-svn-id: http://svn.cactuscode.org/arrangements/CactusBase/CoordBase/trunk@7 0337457d-221f-4ee6-a5f0-14255d5370d8

13 files changed, 1057 insertions, 0 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index b289d1b..ab06462 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -100,6 +100,11 @@
 CoordBase provides a mechanism for registering coordinate systems, and
 maintaining a database of coordinate systems and their coordinates,
 using key-value tables.
+
+CoordBase also provides a way for specifying the extent of the
+simulation domain that is independent of the actual coordinate and
+symmetry thorns, and for specifying the discretisation of the boundary
+that is independent of the actual boundary thorns.
 \end{abstract}
 
 
@@ -402,6 +407,190 @@ Even though another thorn has set a default for all 2D grid variables
 to something else, Coord\_GroupSystem() will always return the handle
 for sphere2d when called on this group.
 
+
+\section{Specifying the extent of the physical domain}
+\label{CactusBase:CoordBase:domain}
+
+CoordBase provides a way for specifying the extent of the simulation
+domain that is independent of the actual coordinate and symmetry
+thorns.  This is necessary because the size of the physical domain is
+not necessarily the same as the size of the computational grid, which
+is usually enlarged by symmetry zones and/or boundary zones.
+
+The physical domain is characterised by the location of its lower and
+upper boundary and by its grid spacing.  These quantities are related
+to the extent and the number of grid cells that span the domain.  The
+relation between the size of the domain and the size of the
+computational grid is defined in section
+{\ref{CactusBase:CoordBase:domain}} below.  The domain extent as
+defined in this section is the continuum extent and is independent of
+the actual discretisation.  This makes it possible to adapt the same
+domain specification for different resolutions by changing only a
+single parameter.
+
+The domain is specified in one of the following ways, which is
+selected by the keyword parameter {\texttt{domainsize}}:
+\begin{description}
+\item[{\texttt{minmax}}:]
+by the location of its lower and upper boundary
+\item[{\texttt{extent}}:]
+by its extent, i.e.\ its width
+\item[{\texttt{spacing}}:]
+by grid spacing and the number of grid cells
+\end{description}
+The domain specification uses the number of grid cells instead of the
+number of grid points because the latter can easily lead to one-off
+errors.
+
+The domain size in each dimension is specificied in equivalent ways.
+For example, the $x$-dimension is specified by a set of some of the
+following parameters:
+\begin{description}
+\item[{\texttt{zero\_origin\_x}} (boolean):]
+When the domain size is specified by extent or by spacing, then the
+origin (lower boundary) can either be located at $x=0$, which leads to
+the domain $x \in [0,L]$ with the extent $L$, or the domain can be
+symmetric with respect to $x=0$, which leads to $x \in [-L/2,L/2]$.
+\item[{\texttt{xmin}} and {\texttt{xmax}}:]
+When the domain is specified by the location of its lower and upper
+boundary, then these specify the locations.
+\item[{\texttt{xextent}}:]
+When the domain is specified by its extent, then this specifies the
+extent.
+\item[{\texttt{dx}} (real) and {\texttt{ncells\_x}} (int):]
+When the domain is specified by grid spacing and the number of grid
+cells, then these specify the grid spacing and the number of grid
+cells.
+\end{description}
+
+
+\section{Specifying the location of the boundary points}
+\label{CactusBase:CoordBase:boundary}
+
+CoordBase also provides a way for specifying the discretisation of the
+boundary that is independent of the actual boundary thorns.  This
+defines the locations of the boundary points and thus the extent of
+the computational grid.
+
+Each face of the grid is specified independently.  The specification
+does not depend on the resolution, so that it need not be adapted when
+the resolution is changed.  Figure
+{\ref{CactusBase:CoordBase:fig-domain}} shows a domain with several
+interior grid points and one boundary point.
+
+\begin{figure}
+\begin{center}
+\includegraphics[scale=0.75]{domain}
+\end{center}
+\caption{A domain (rectangle) with three interior points (empty
+circles) and one boundary point (full circle).}
+\label{CactusBase:CoordBase:fig-domain}
+\end{figure}
+
+While the physical boundary has a width of zero, the computational
+grid can have more than one boundary points.  This {\emph{boundary
+size}} is defined by the integer parameter
+{\texttt{boundary\_size\_x\_lower}} for the lower $x$ boundary (and
+similarly for the other boundaries).  Figure
+{\ref{CactusBase:CoordBase:fig-domain-external}} shows an example
+where there are two boundary points.  When it is necessary to increase
+the number of boundary points (e.g., to accommodate a larger stencil),
+then this is the only parameter that needs to be changed.
+
+\begin{figure}
+\begin{center}
+\includegraphics[scale=0.75]{domain-external}
+\end{center}
+\caption{A domain (rectangle) with three interior points (empty
+circles) and two boundary points (full circles).  This is an exterior
+boundary, i.e.\ the boundary points are located outside of the
+physical domain.}
+\label{CactusBase:CoordBase:fig-domain-external}
+\end{figure}
+
+Depending on the physical setup --- and depending on the personal
+taste --- the boundary points should be located either inside or
+outside of the physical boundary.  The boolean parameter
+{\texttt{boundary\_internal\_x\_lower}} specifies whether the boundary
+points extend inwards at the lower $x$ face.  Figure
+{\ref{CactusBase:CoordBase:fig-domain-internal}} shows the same
+example, but with internal boundary points.
+
+\begin{figure}
+\begin{center}
+\includegraphics[scale=0.75]{domain-internal}
+\end{center}
+\caption{A domain (rectangle) with two interior points (empty circles)
+and two boundary points (full circles).  This is an interior boundary,
+i.e.\ the boundary points are located inside of the physical domain.}
+\label{CactusBase:CoordBase:fig-domain-internal}
+\end{figure}
+
+Depending on the physical setup --- and depending on the personal
+taste --- the boundary points should either be staggered about the
+physical boundary, or the last boundary point should be located
+exactly on the physical boundary.  This is specified by the boolean
+parameter {\texttt{boundary\_staggered\_x\_lower}}.  Figures
+{\ref{CactusBase:CoordBase:fig-domain-external-staggered}} and
+{\ref{CactusBase:CoordBase:fig-domain-internal-staggered}} show
+exampled of external and internal staggered boundary points.
+
+\begin{figure}
+\begin{center}
+\includegraphics[scale=0.75]{domain-external-staggered}
+\end{center}
+\caption{A domain (rectangle) with three interior points (empty circles)
+and two boundary points (full circles) which are staggered about the
+physical boundary.  (This is an exterior boundary.)}
+\label{CactusBase:CoordBase:fig-domain-external-staggered}
+\end{figure}
+
+\begin{figure}
+\begin{center}
+\includegraphics[scale=0.75]{domain-internal-staggered}
+\end{center}
+\caption{A domain (rectangle) with two interior points (empty circles)
+and two boundary points (full circles) which are staggered about the
+physical boundary.  (This is an interior boundary.)}
+\label{CactusBase:CoordBase:fig-domain-internal-staggered}
+\end{figure}
+
+Finally, the integer parameter {\texttt{boundary\_shiftout\_x\_lower}}
+can be used to shift the boundary points outwards (or inwards with
+negative values) by multiples of the grid spacing.  Figure
+{\ref{CactusBase:CoordBase:fig-domain-external-shiftout}} shows an
+example of an exterior, non-staggered boundary with a shiftout of one.
+
+\begin{figure}
+\begin{center}
+\includegraphics[scale=0.75]{domain-external-shiftout}
+\end{center}
+\caption{A domain (rectangle) with four interior points (empty circles)
+and two boundary points (full circles) which are shifted outwards by
+one grid point.  (This is an exterior, non-staggered boundary.)}
+\label{CactusBase:CoordBase:fig-domain-external-shiftout}
+\end{figure}
+
+The following table gives examples for common situations:
+
+\begin{tabular}{l|ccc|l}
+Boundary condition & internal? & staggered? & shiftout & example \\\hline
+reflection symmetry, not staggered & no & no & 1
+   & figure {\ref{CactusBase:CoordBase:fig-domain-external-shiftout}} \\
+reflection symmetry, staggered & no & yes & 0
+   & figure {\ref{CactusBase:CoordBase:fig-domain-external-staggered}} \\
+periodicity, closed boundary & no & no & 1
+   & figure {\ref{CactusBase:CoordBase:fig-domain-external-shiftout}} \\
+periodicity, open boundary & no & no & 0
+   & figure {\ref{CactusBase:CoordBase:fig-domain-external}} \\
+periodicity, staggered boundary & no & yes & 0
+   & figure {\ref{CactusBase:CoordBase:fig-domain-external-staggered}}
+\end{tabular}
+
+For other boundary conditions such as Dirichlet or Robin, one can
+choose these parameters freely.
+
+
 % Do not delete next line
 % END CACTUS THORNGUIDE
 
diff --git a/doc/domain-external-shiftout.eps b/doc/domain-external-shiftout.eps
new file mode 100644
index 0000000..42003a1
--- /dev/null
+++ b/doc/domain-external-shiftout.eps
@@ -0,0 +1,133 @@
+%!PS-Adobe-2.0 EPSF-2.0
+%%Title: domain-external-shiftout.fig
+%%Creator: fig2dev Version 3.2 Patchlevel 4
+%%CreationDate: Mon Jan 19 23:46:16 2004
+%%For: eschnett@because (Erik Schnetter,AEI 2.27,+49 331 567 7357,)
+%%BoundingBox: 0 0 207 87
+%%Magnification: 1.0000
+%%EndComments
+/$F2psDict 200 dict def
+$F2psDict begin
+$F2psDict /mtrx matrix put
+/col-1 {0 setgray} bind def
+/col0 {0.000 0.000 0.000 srgb} bind def
+/col1 {0.000 0.000 1.000 srgb} bind def
+/col2 {0.000 1.000 0.000 srgb} bind def
+/col3 {0.000 1.000 1.000 srgb} bind def
+/col4 {1.000 0.000 0.000 srgb} bind def
+/col5 {1.000 0.000 1.000 srgb} bind def
+/col6 {1.000 1.000 0.000 srgb} bind def
+/col7 {1.000 1.000 1.000 srgb} bind def
+/col8 {0.000 0.000 0.560 srgb} bind def
+/col9 {0.000 0.000 0.690 srgb} bind def
+/col10 {0.000 0.000 0.820 srgb} bind def
+/col11 {0.530 0.810 1.000 srgb} bind def
+/col12 {0.000 0.560 0.000 srgb} bind def
+/col13 {0.000 0.690 0.000 srgb} bind def
+/col14 {0.000 0.820 0.000 srgb} bind def
+/col15 {0.000 0.560 0.560 srgb} bind def
+/col16 {0.000 0.690 0.690 srgb} bind def
+/col17 {0.000 0.820 0.820 srgb} bind def
+/col18 {0.560 0.000 0.000 srgb} bind def
+/col19 {0.690 0.000 0.000 srgb} bind def
+/col20 {0.820 0.000 0.000 srgb} bind def
+/col21 {0.560 0.000 0.560 srgb} bind def
+/col22 {0.690 0.000 0.690 srgb} bind def
+/col23 {0.820 0.000 0.820 srgb} bind def
+/col24 {0.500 0.190 0.000 srgb} bind def
+/col25 {0.630 0.250 0.000 srgb} bind def
+/col26 {0.750 0.380 0.000 srgb} bind def
+/col27 {1.000 0.500 0.500 srgb} bind def
+/col28 {1.000 0.630 0.630 srgb} bind def
+/col29 {1.000 0.750 0.750 srgb} bind def
+/col30 {1.000 0.880 0.880 srgb} bind def
+/col31 {1.000 0.840 0.000 srgb} bind def
+
+end
+save
+newpath 0 87 moveto 0 0 lineto 207 0 lineto 207 87 lineto closepath clip newpath
+-20.7 114.1 translate
+1 -1 scale
+
+/cp {closepath} bind def
+/ef {eofill} bind def
+/gr {grestore} bind def
+/gs {gsave} bind def
+/sa {save} bind def
+/rs {restore} bind def
+/l {lineto} bind def
+/m {moveto} bind def
+/rm {rmoveto} bind def
+/n {newpath} bind def
+/s {stroke} bind def
+/sh {show} bind def
+/slc {setlinecap} bind def
+/slj {setlinejoin} bind def
+/slw {setlinewidth} bind def
+/srgb {setrgbcolor} bind def
+/rot {rotate} bind def
+/sc {scale} bind def
+/sd {setdash} bind def
+/ff {findfont} bind def
+/sf {setfont} bind def
+/scf {scalefont} bind def
+/sw {stringwidth} bind def
+/tr {translate} bind def
+/tnt {dup dup currentrgbcolor
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
+  bind def
+/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
+  4 -2 roll mul srgb} bind def
+ /DrawEllipse {
+	/endangle exch def
+	/startangle exch def
+	/yrad exch def
+	/xrad exch def
+	/y exch def
+	/x exch def
+	/savematrix mtrx currentmatrix def
+	x y tr xrad yrad sc 0 0 1 startangle endangle arc
+	closepath
+	savematrix setmatrix
+	} def
+
+/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
+/$F2psEnd {$F2psEnteredState restore end} def
+
+$F2psBegin
+10 setmiterlimit
+0 slj 0 slc
+ 0.06299 0.06299 sc
+%
+% Fig objects follow
+%
+% 
+% here starts figure with depth 50
+% Ellipse
+7.500 slw
+n 1800 1125 113 113 0 360 DrawEllipse gs col0 s gr
+
+% Ellipse
+n 1350 1125 113 113 0 360 DrawEllipse gs col0 s gr
+
+% Ellipse
+n 450 1125 113 113 0 360 DrawEllipse gs 0.00 setgray ef gr gs col0 s gr
+
+% Ellipse
+n 2250 1125 113 113 0 360 DrawEllipse gs col0 s gr
+
+% Ellipse
+n 900 1125 113 113 0 360 DrawEllipse gs 0.00 setgray ef gr gs col0 s gr
+
+% Ellipse
+n 2700 1125 113 113 0 360 DrawEllipse gs col0 s gr
+
+% Polyline
+n 1350 450 m 3600 450 l 3600 1800 l 1350 1800 l
+ cp gs col0 s gr 
+% here ends figure;
+$F2psEnd
+rs
+showpage
diff --git a/doc/domain-external-shiftout.fig b/doc/domain-external-shiftout.fig
new file mode 100644
index 0000000..af2b20a
--- /dev/null
+++ b/doc/domain-external-shiftout.fig
@@ -0,0 +1,17 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 1800 1125 113 113 1800 1125 1913 1125
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 1350 1125 113 113 1350 1125 1463 1125
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 450 1125 113 113 450 1125 563 1125
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 2250 1125 113 113 2250 1125 2363 1125
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 900 1125 113 113 900 1125 1013 1125
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 2700 1125 113 113 2700 1125 2813 1125
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 1350 450 3600 450 3600 1800 1350 1800 1350 450
diff --git a/doc/domain-external-staggered.eps b/doc/domain-external-staggered.eps
new file mode 100644
index 0000000..d1a7437
--- /dev/null
+++ b/doc/domain-external-staggered.eps
@@ -0,0 +1,130 @@
+%!PS-Adobe-2.0 EPSF-2.0
+%%Title: domain-external-staggered.fig
+%%Creator: fig2dev Version 3.2 Patchlevel 4
+%%CreationDate: Mon Jan 19 23:42:21 2004
+%%For: eschnett@because (Erik Schnetter,AEI 2.27,+49 331 567 7357,)
+%%BoundingBox: 0 0 193 87
+%%Magnification: 1.0000
+%%EndComments
+/$F2psDict 200 dict def
+$F2psDict begin
+$F2psDict /mtrx matrix put
+/col-1 {0 setgray} bind def
+/col0 {0.000 0.000 0.000 srgb} bind def
+/col1 {0.000 0.000 1.000 srgb} bind def
+/col2 {0.000 1.000 0.000 srgb} bind def
+/col3 {0.000 1.000 1.000 srgb} bind def
+/col4 {1.000 0.000 0.000 srgb} bind def
+/col5 {1.000 0.000 1.000 srgb} bind def
+/col6 {1.000 1.000 0.000 srgb} bind def
+/col7 {1.000 1.000 1.000 srgb} bind def
+/col8 {0.000 0.000 0.560 srgb} bind def
+/col9 {0.000 0.000 0.690 srgb} bind def
+/col10 {0.000 0.000 0.820 srgb} bind def
+/col11 {0.530 0.810 1.000 srgb} bind def
+/col12 {0.000 0.560 0.000 srgb} bind def
+/col13 {0.000 0.690 0.000 srgb} bind def
+/col14 {0.000 0.820 0.000 srgb} bind def
+/col15 {0.000 0.560 0.560 srgb} bind def
+/col16 {0.000 0.690 0.690 srgb} bind def
+/col17 {0.000 0.820 0.820 srgb} bind def
+/col18 {0.560 0.000 0.000 srgb} bind def
+/col19 {0.690 0.000 0.000 srgb} bind def
+/col20 {0.820 0.000 0.000 srgb} bind def
+/col21 {0.560 0.000 0.560 srgb} bind def
+/col22 {0.690 0.000 0.690 srgb} bind def
+/col23 {0.820 0.000 0.820 srgb} bind def
+/col24 {0.500 0.190 0.000 srgb} bind def
+/col25 {0.630 0.250 0.000 srgb} bind def
+/col26 {0.750 0.380 0.000 srgb} bind def
+/col27 {1.000 0.500 0.500 srgb} bind def
+/col28 {1.000 0.630 0.630 srgb} bind def
+/col29 {1.000 0.750 0.750 srgb} bind def
+/col30 {1.000 0.880 0.880 srgb} bind def
+/col31 {1.000 0.840 0.000 srgb} bind def
+
+end
+save
+newpath 0 87 moveto 0 0 lineto 193 0 lineto 193 87 lineto closepath clip newpath
+-20.7 114.1 translate
+1 -1 scale
+
+/cp {closepath} bind def
+/ef {eofill} bind def
+/gr {grestore} bind def
+/gs {gsave} bind def
+/sa {save} bind def
+/rs {restore} bind def
+/l {lineto} bind def
+/m {moveto} bind def
+/rm {rmoveto} bind def
+/n {newpath} bind def
+/s {stroke} bind def
+/sh {show} bind def
+/slc {setlinecap} bind def
+/slj {setlinejoin} bind def
+/slw {setlinewidth} bind def
+/srgb {setrgbcolor} bind def
+/rot {rotate} bind def
+/sc {scale} bind def
+/sd {setdash} bind def
+/ff {findfont} bind def
+/sf {setfont} bind def
+/scf {scalefont} bind def
+/sw {stringwidth} bind def
+/tr {translate} bind def
+/tnt {dup dup currentrgbcolor
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
+  bind def
+/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
+  4 -2 roll mul srgb} bind def
+ /DrawEllipse {
+	/endangle exch def
+	/startangle exch def
+	/yrad exch def
+	/xrad exch def
+	/y exch def
+	/x exch def
+	/savematrix mtrx currentmatrix def
+	x y tr xrad yrad sc 0 0 1 startangle endangle arc
+	closepath
+	savematrix setmatrix
+	} def
+
+/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
+/$F2psEnd {$F2psEnteredState restore end} def
+
+$F2psBegin
+10 setmiterlimit
+0 slj 0 slc
+ 0.06299 0.06299 sc
+%
+% Fig objects follow
+%
+% 
+% here starts figure with depth 50
+% Ellipse
+7.500 slw
+n 1800 1125 113 113 0 360 DrawEllipse gs col0 s gr
+
+% Ellipse
+n 1350 1125 113 113 0 360 DrawEllipse gs col0 s gr
+
+% Ellipse
+n 450 1125 113 113 0 360 DrawEllipse gs 0.00 setgray ef gr gs col0 s gr
+
+% Ellipse
+n 2250 1125 113 113 0 360 DrawEllipse gs col0 s gr
+
+% Ellipse
+n 900 1125 113 113 0 360 DrawEllipse gs 0.00 setgray ef gr gs col0 s gr
+
+% Polyline
+n 1125 450 m 3375 450 l 3375 1800 l 1125 1800 l
+ cp gs col0 s gr 
+% here ends figure;
+$F2psEnd
+rs
+showpage
diff --git a/doc/domain-external-staggered.fig b/doc/domain-external-staggered.fig
new file mode 100644
index 0000000..b3e6aa8
--- /dev/null
+++ b/doc/domain-external-staggered.fig
@@ -0,0 +1,16 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 1800 1125 113 113 1800 1125 1913 1125
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 1350 1125 113 113 1350 1125 1463 1125
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 450 1125 113 113 450 1125 563 1125
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 2250 1125 113 113 2250 1125 2363 1125
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 900 1125 113 113 900 1125 1013 1125
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 1125 450 3375 450 3375 1800 1125 1800 1125 450
diff --git a/doc/domain-external.eps b/doc/domain-external.eps
new file mode 100644
index 0000000..d4a5284
--- /dev/null
+++ b/doc/domain-external.eps
@@ -0,0 +1,130 @@
+%!PS-Adobe-2.0 EPSF-2.0
+%%Title: domain-external.fig
+%%Creator: fig2dev Version 3.2 Patchlevel 4
+%%CreationDate: Mon Jan 19 23:36:11 2004
+%%For: eschnett@because (Erik Schnetter,AEI 2.27,+49 331 567 7357,)
+%%BoundingBox: 0 0 179 87
+%%Magnification: 1.0000
+%%EndComments
+/$F2psDict 200 dict def
+$F2psDict begin
+$F2psDict /mtrx matrix put
+/col-1 {0 setgray} bind def
+/col0 {0.000 0.000 0.000 srgb} bind def
+/col1 {0.000 0.000 1.000 srgb} bind def
+/col2 {0.000 1.000 0.000 srgb} bind def
+/col3 {0.000 1.000 1.000 srgb} bind def
+/col4 {1.000 0.000 0.000 srgb} bind def
+/col5 {1.000 0.000 1.000 srgb} bind def
+/col6 {1.000 1.000 0.000 srgb} bind def
+/col7 {1.000 1.000 1.000 srgb} bind def
+/col8 {0.000 0.000 0.560 srgb} bind def
+/col9 {0.000 0.000 0.690 srgb} bind def
+/col10 {0.000 0.000 0.820 srgb} bind def
+/col11 {0.530 0.810 1.000 srgb} bind def
+/col12 {0.000 0.560 0.000 srgb} bind def
+/col13 {0.000 0.690 0.000 srgb} bind def
+/col14 {0.000 0.820 0.000 srgb} bind def
+/col15 {0.000 0.560 0.560 srgb} bind def
+/col16 {0.000 0.690 0.690 srgb} bind def
+/col17 {0.000 0.820 0.820 srgb} bind def
+/col18 {0.560 0.000 0.000 srgb} bind def
+/col19 {0.690 0.000 0.000 srgb} bind def
+/col20 {0.820 0.000 0.000 srgb} bind def
+/col21 {0.560 0.000 0.560 srgb} bind def
+/col22 {0.690 0.000 0.690 srgb} bind def
+/col23 {0.820 0.000 0.820 srgb} bind def
+/col24 {0.500 0.190 0.000 srgb} bind def
+/col25 {0.630 0.250 0.000 srgb} bind def
+/col26 {0.750 0.380 0.000 srgb} bind def
+/col27 {1.000 0.500 0.500 srgb} bind def
+/col28 {1.000 0.630 0.630 srgb} bind def
+/col29 {1.000 0.750 0.750 srgb} bind def
+/col30 {1.000 0.880 0.880 srgb} bind def
+/col31 {1.000 0.840 0.000 srgb} bind def
+
+end
+save
+newpath 0 87 moveto 0 0 lineto 179 0 lineto 179 87 lineto closepath clip newpath
+-20.7 114.1 translate
+1 -1 scale
+
+/cp {closepath} bind def
+/ef {eofill} bind def
+/gr {grestore} bind def
+/gs {gsave} bind def
+/sa {save} bind def
+/rs {restore} bind def
+/l {lineto} bind def
+/m {moveto} bind def
+/rm {rmoveto} bind def
+/n {newpath} bind def
+/s {stroke} bind def
+/sh {show} bind def
+/slc {setlinecap} bind def
+/slj {setlinejoin} bind def
+/slw {setlinewidth} bind def
+/srgb {setrgbcolor} bind def
+/rot {rotate} bind def
+/sc {scale} bind def
+/sd {setdash} bind def
+/ff {findfont} bind def
+/sf {setfont} bind def
+/scf {scalefont} bind def
+/sw {stringwidth} bind def
+/tr {translate} bind def
+/tnt {dup dup currentrgbcolor
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
+  bind def
+/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
+  4 -2 roll mul srgb} bind def
+ /DrawEllipse {
+	/endangle exch def
+	/startangle exch def
+	/yrad exch def
+	/xrad exch def
+	/y exch def
+	/x exch def
+	/savematrix mtrx currentmatrix def
+	x y tr xrad yrad sc 0 0 1 startangle endangle arc
+	closepath
+	savematrix setmatrix
+	} def
+
+/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
+/$F2psEnd {$F2psEnteredState restore end} def
+
+$F2psBegin
+10 setmiterlimit
+0 slj 0 slc
+ 0.06299 0.06299 sc
+%
+% Fig objects follow
+%
+% 
+% here starts figure with depth 50
+% Ellipse
+7.500 slw
+n 1800 1125 113 113 0 360 DrawEllipse gs col0 s gr
+
+% Ellipse
+n 1350 1125 113 113 0 360 DrawEllipse gs col0 s gr
+
+% Ellipse
+n 450 1125 113 113 0 360 DrawEllipse gs 0.00 setgray ef gr gs col0 s gr
+
+% Ellipse
+n 2250 1125 113 113 0 360 DrawEllipse gs col0 s gr
+
+% Ellipse
+n 900 1125 113 113 0 360 DrawEllipse gs 0.00 setgray ef gr gs col0 s gr
+
+% Polyline
+n 900 450 m 3150 450 l 3150 1800 l 900 1800 l
+ cp gs col0 s gr 
+% here ends figure;
+$F2psEnd
+rs
+showpage
diff --git a/doc/domain-external.fig b/doc/domain-external.fig
new file mode 100644
index 0000000..bf40bae
--- /dev/null
+++ b/doc/domain-external.fig
@@ -0,0 +1,16 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 1800 1125 113 113 1800 1125 1913 1125
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 1350 1125 113 113 1350 1125 1463 1125
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 450 1125 113 113 450 1125 563 1125
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 2250 1125 113 113 2250 1125 2363 1125
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 900 1125 113 113 900 1125 1013 1125
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 900 450 3150 450 3150 1800 900 1800 900 450
diff --git a/doc/domain-internal-staggered.eps b/doc/domain-internal-staggered.eps
new file mode 100644
index 0000000..010e8a9
--- /dev/null
+++ b/doc/domain-internal-staggered.eps
@@ -0,0 +1,127 @@
+%!PS-Adobe-2.0 EPSF-2.0
+%%Title: domain-internal-staggered.fig
+%%Creator: fig2dev Version 3.2 Patchlevel 4
+%%CreationDate: Mon Jan 19 23:42:49 2004
+%%For: eschnett@because (Erik Schnetter,AEI 2.27,+49 331 567 7357,)
+%%BoundingBox: 0 0 144 87
+%%Magnification: 1.0000
+%%EndComments
+/$F2psDict 200 dict def
+$F2psDict begin
+$F2psDict /mtrx matrix put
+/col-1 {0 setgray} bind def
+/col0 {0.000 0.000 0.000 srgb} bind def
+/col1 {0.000 0.000 1.000 srgb} bind def
+/col2 {0.000 1.000 0.000 srgb} bind def
+/col3 {0.000 1.000 1.000 srgb} bind def
+/col4 {1.000 0.000 0.000 srgb} bind def
+/col5 {1.000 0.000 1.000 srgb} bind def
+/col6 {1.000 1.000 0.000 srgb} bind def
+/col7 {1.000 1.000 1.000 srgb} bind def
+/col8 {0.000 0.000 0.560 srgb} bind def
+/col9 {0.000 0.000 0.690 srgb} bind def
+/col10 {0.000 0.000 0.820 srgb} bind def
+/col11 {0.530 0.810 1.000 srgb} bind def
+/col12 {0.000 0.560 0.000 srgb} bind def
+/col13 {0.000 0.690 0.000 srgb} bind def
+/col14 {0.000 0.820 0.000 srgb} bind def
+/col15 {0.000 0.560 0.560 srgb} bind def
+/col16 {0.000 0.690 0.690 srgb} bind def
+/col17 {0.000 0.820 0.820 srgb} bind def
+/col18 {0.560 0.000 0.000 srgb} bind def
+/col19 {0.690 0.000 0.000 srgb} bind def
+/col20 {0.820 0.000 0.000 srgb} bind def
+/col21 {0.560 0.000 0.560 srgb} bind def
+/col22 {0.690 0.000 0.690 srgb} bind def
+/col23 {0.820 0.000 0.820 srgb} bind def
+/col24 {0.500 0.190 0.000 srgb} bind def
+/col25 {0.630 0.250 0.000 srgb} bind def
+/col26 {0.750 0.380 0.000 srgb} bind def
+/col27 {1.000 0.500 0.500 srgb} bind def
+/col28 {1.000 0.630 0.630 srgb} bind def
+/col29 {1.000 0.750 0.750 srgb} bind def
+/col30 {1.000 0.880 0.880 srgb} bind def
+/col31 {1.000 0.840 0.000 srgb} bind def
+
+end
+save
+newpath 0 87 moveto 0 0 lineto 144 0 lineto 144 87 lineto closepath clip newpath
+-41.8 114.1 translate
+1 -1 scale
+
+/cp {closepath} bind def
+/ef {eofill} bind def
+/gr {grestore} bind def
+/gs {gsave} bind def
+/sa {save} bind def
+/rs {restore} bind def
+/l {lineto} bind def
+/m {moveto} bind def
+/rm {rmoveto} bind def
+/n {newpath} bind def
+/s {stroke} bind def
+/sh {show} bind def
+/slc {setlinecap} bind def
+/slj {setlinejoin} bind def
+/slw {setlinewidth} bind def
+/srgb {setrgbcolor} bind def
+/rot {rotate} bind def
+/sc {scale} bind def
+/sd {setdash} bind def
+/ff {findfont} bind def
+/sf {setfont} bind def
+/scf {scalefont} bind def
+/sw {stringwidth} bind def
+/tr {translate} bind def
+/tnt {dup dup currentrgbcolor
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
+  bind def
+/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
+  4 -2 roll mul srgb} bind def
+ /DrawEllipse {
+	/endangle exch def
+	/startangle exch def
+	/yrad exch def
+	/xrad exch def
+	/y exch def
+	/x exch def
+	/savematrix mtrx currentmatrix def
+	x y tr xrad yrad sc 0 0 1 startangle endangle arc
+	closepath
+	savematrix setmatrix
+	} def
+
+/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
+/$F2psEnd {$F2psEnteredState restore end} def
+
+$F2psBegin
+10 setmiterlimit
+0 slj 0 slc
+ 0.06299 0.06299 sc
+%
+% Fig objects follow
+%
+% 
+% here starts figure with depth 50
+% Ellipse
+7.500 slw
+n 1800 1125 113 113 0 360 DrawEllipse gs col0 s gr
+
+% Ellipse
+n 2250 1125 113 113 0 360 DrawEllipse gs col0 s gr
+
+% Ellipse
+n 900 1125 113 113 0 360 DrawEllipse gs 0.00 setgray ef gr gs col0 s gr
+
+% Ellipse
+n 1350 1125 113 113 0 360 DrawEllipse gs 0.00 setgray ef gr gs col0 s gr
+
+% Polyline
+n 675 450 m 2925 450 l 2925 1800 l 675 1800 l
+ cp gs col0 s gr 
+% here ends figure;
+$F2psEnd
+rs
+showpage
diff --git a/doc/domain-internal-staggered.fig b/doc/domain-internal-staggered.fig
new file mode 100644
index 0000000..a862672
--- /dev/null
+++ b/doc/domain-internal-staggered.fig
@@ -0,0 +1,15 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 1800 1125 113 113 1800 1125 1913 1125
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 2250 1125 113 113 2250 1125 2363 1125
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 900 1125 113 113 900 1125 1013 1125
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 1350 1125 113 113 1350 1125 1463 1125
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 675 450 2925 450 2925 1800 675 1800 675 450
diff --git a/doc/domain-internal.eps b/doc/domain-internal.eps
new file mode 100644
index 0000000..4ad9095
--- /dev/null
+++ b/doc/domain-internal.eps
@@ -0,0 +1,127 @@
+%!PS-Adobe-2.0 EPSF-2.0
+%%Title: domain-internal.fig
+%%Creator: fig2dev Version 3.2 Patchlevel 4
+%%CreationDate: Mon Jan 19 23:36:48 2004
+%%For: eschnett@because (Erik Schnetter,AEI 2.27,+49 331 567 7357,)
+%%BoundingBox: 0 0 151 87
+%%Magnification: 1.0000
+%%EndComments
+/$F2psDict 200 dict def
+$F2psDict begin
+$F2psDict /mtrx matrix put
+/col-1 {0 setgray} bind def
+/col0 {0.000 0.000 0.000 srgb} bind def
+/col1 {0.000 0.000 1.000 srgb} bind def
+/col2 {0.000 1.000 0.000 srgb} bind def
+/col3 {0.000 1.000 1.000 srgb} bind def
+/col4 {1.000 0.000 0.000 srgb} bind def
+/col5 {1.000 0.000 1.000 srgb} bind def
+/col6 {1.000 1.000 0.000 srgb} bind def
+/col7 {1.000 1.000 1.000 srgb} bind def
+/col8 {0.000 0.000 0.560 srgb} bind def
+/col9 {0.000 0.000 0.690 srgb} bind def
+/col10 {0.000 0.000 0.820 srgb} bind def
+/col11 {0.530 0.810 1.000 srgb} bind def
+/col12 {0.000 0.560 0.000 srgb} bind def
+/col13 {0.000 0.690 0.000 srgb} bind def
+/col14 {0.000 0.820 0.000 srgb} bind def
+/col15 {0.000 0.560 0.560 srgb} bind def
+/col16 {0.000 0.690 0.690 srgb} bind def
+/col17 {0.000 0.820 0.820 srgb} bind def
+/col18 {0.560 0.000 0.000 srgb} bind def
+/col19 {0.690 0.000 0.000 srgb} bind def
+/col20 {0.820 0.000 0.000 srgb} bind def
+/col21 {0.560 0.000 0.560 srgb} bind def
+/col22 {0.690 0.000 0.690 srgb} bind def
+/col23 {0.820 0.000 0.820 srgb} bind def
+/col24 {0.500 0.190 0.000 srgb} bind def
+/col25 {0.630 0.250 0.000 srgb} bind def
+/col26 {0.750 0.380 0.000 srgb} bind def
+/col27 {1.000 0.500 0.500 srgb} bind def
+/col28 {1.000 0.630 0.630 srgb} bind def
+/col29 {1.000 0.750 0.750 srgb} bind def
+/col30 {1.000 0.880 0.880 srgb} bind def
+/col31 {1.000 0.840 0.000 srgb} bind def
+
+end
+save
+newpath 0 87 moveto 0 0 lineto 151 0 lineto 151 87 lineto closepath clip newpath
+-49.1 114.1 translate
+1 -1 scale
+
+/cp {closepath} bind def
+/ef {eofill} bind def
+/gr {grestore} bind def
+/gs {gsave} bind def
+/sa {save} bind def
+/rs {restore} bind def
+/l {lineto} bind def
+/m {moveto} bind def
+/rm {rmoveto} bind def
+/n {newpath} bind def
+/s {stroke} bind def
+/sh {show} bind def
+/slc {setlinecap} bind def
+/slj {setlinejoin} bind def
+/slw {setlinewidth} bind def
+/srgb {setrgbcolor} bind def
+/rot {rotate} bind def
+/sc {scale} bind def
+/sd {setdash} bind def
+/ff {findfont} bind def
+/sf {setfont} bind def
+/scf {scalefont} bind def
+/sw {stringwidth} bind def
+/tr {translate} bind def
+/tnt {dup dup currentrgbcolor
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
+  bind def
+/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
+  4 -2 roll mul srgb} bind def
+ /DrawEllipse {
+	/endangle exch def
+	/startangle exch def
+	/yrad exch def
+	/xrad exch def
+	/y exch def
+	/x exch def
+	/savematrix mtrx currentmatrix def
+	x y tr xrad yrad sc 0 0 1 startangle endangle arc
+	closepath
+	savematrix setmatrix
+	} def
+
+/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
+/$F2psEnd {$F2psEnteredState restore end} def
+
+$F2psBegin
+10 setmiterlimit
+0 slj 0 slc
+ 0.06299 0.06299 sc
+%
+% Fig objects follow
+%
+% 
+% here starts figure with depth 50
+% Ellipse
+7.500 slw
+n 1800 1125 113 113 0 360 DrawEllipse gs col0 s gr
+
+% Ellipse
+n 2250 1125 113 113 0 360 DrawEllipse gs col0 s gr
+
+% Ellipse
+n 900 1125 113 113 0 360 DrawEllipse gs 0.00 setgray ef gr gs col0 s gr
+
+% Ellipse
+n 1350 1125 113 113 0 360 DrawEllipse gs 0.00 setgray ef gr gs col0 s gr
+
+% Polyline
+n 900 450 m 3150 450 l 3150 1800 l 900 1800 l
+ cp gs col0 s gr 
+% here ends figure;
+$F2psEnd
+rs
+showpage
diff --git a/doc/domain-internal.fig b/doc/domain-internal.fig
new file mode 100644
index 0000000..475fa9a
--- /dev/null
+++ b/doc/domain-internal.fig
@@ -0,0 +1,15 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 1800 1125 113 113 1800 1125 1913 1125
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 2250 1125 113 113 2250 1125 2363 1125
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 900 1125 113 113 900 1125 1013 1125
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 1350 1125 113 113 1350 1125 1463 1125
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 900 450 3150 450 3150 1800 900 1800 900 450
diff --git a/doc/domain.eps b/doc/domain.eps
new file mode 100644
index 0000000..3f8b480
--- /dev/null
+++ b/doc/domain.eps
@@ -0,0 +1,127 @@
+%!PS-Adobe-2.0 EPSF-2.0
+%%Title: domain.fig
+%%Creator: fig2dev Version 3.2 Patchlevel 4
+%%CreationDate: Mon Jan 19 23:34:48 2004
+%%For: eschnett@because (Erik Schnetter,AEI 2.27,+49 331 567 7357,)
+%%BoundingBox: 0 0 151 87
+%%Magnification: 1.0000
+%%EndComments
+/$F2psDict 200 dict def
+$F2psDict begin
+$F2psDict /mtrx matrix put
+/col-1 {0 setgray} bind def
+/col0 {0.000 0.000 0.000 srgb} bind def
+/col1 {0.000 0.000 1.000 srgb} bind def
+/col2 {0.000 1.000 0.000 srgb} bind def
+/col3 {0.000 1.000 1.000 srgb} bind def
+/col4 {1.000 0.000 0.000 srgb} bind def
+/col5 {1.000 0.000 1.000 srgb} bind def
+/col6 {1.000 1.000 0.000 srgb} bind def
+/col7 {1.000 1.000 1.000 srgb} bind def
+/col8 {0.000 0.000 0.560 srgb} bind def
+/col9 {0.000 0.000 0.690 srgb} bind def
+/col10 {0.000 0.000 0.820 srgb} bind def
+/col11 {0.530 0.810 1.000 srgb} bind def
+/col12 {0.000 0.560 0.000 srgb} bind def
+/col13 {0.000 0.690 0.000 srgb} bind def
+/col14 {0.000 0.820 0.000 srgb} bind def
+/col15 {0.000 0.560 0.560 srgb} bind def
+/col16 {0.000 0.690 0.690 srgb} bind def
+/col17 {0.000 0.820 0.820 srgb} bind def
+/col18 {0.560 0.000 0.000 srgb} bind def
+/col19 {0.690 0.000 0.000 srgb} bind def
+/col20 {0.820 0.000 0.000 srgb} bind def
+/col21 {0.560 0.000 0.560 srgb} bind def
+/col22 {0.690 0.000 0.690 srgb} bind def
+/col23 {0.820 0.000 0.820 srgb} bind def
+/col24 {0.500 0.190 0.000 srgb} bind def
+/col25 {0.630 0.250 0.000 srgb} bind def
+/col26 {0.750 0.380 0.000 srgb} bind def
+/col27 {1.000 0.500 0.500 srgb} bind def
+/col28 {1.000 0.630 0.630 srgb} bind def
+/col29 {1.000 0.750 0.750 srgb} bind def
+/col30 {1.000 0.880 0.880 srgb} bind def
+/col31 {1.000 0.840 0.000 srgb} bind def
+
+end
+save
+newpath 0 87 moveto 0 0 lineto 151 0 lineto 151 87 lineto closepath clip newpath
+-20.7 114.1 translate
+1 -1 scale
+
+/cp {closepath} bind def
+/ef {eofill} bind def
+/gr {grestore} bind def
+/gs {gsave} bind def
+/sa {save} bind def
+/rs {restore} bind def
+/l {lineto} bind def
+/m {moveto} bind def
+/rm {rmoveto} bind def
+/n {newpath} bind def
+/s {stroke} bind def
+/sh {show} bind def
+/slc {setlinecap} bind def
+/slj {setlinejoin} bind def
+/slw {setlinewidth} bind def
+/srgb {setrgbcolor} bind def
+/rot {rotate} bind def
+/sc {scale} bind def
+/sd {setdash} bind def
+/ff {findfont} bind def
+/sf {setfont} bind def
+/scf {scalefont} bind def
+/sw {stringwidth} bind def
+/tr {translate} bind def
+/tnt {dup dup currentrgbcolor
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add
+  4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
+  bind def
+/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
+  4 -2 roll mul srgb} bind def
+ /DrawEllipse {
+	/endangle exch def
+	/startangle exch def
+	/yrad exch def
+	/xrad exch def
+	/y exch def
+	/x exch def
+	/savematrix mtrx currentmatrix def
+	x y tr xrad yrad sc 0 0 1 startangle endangle arc
+	closepath
+	savematrix setmatrix
+	} def
+
+/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
+/$F2psEnd {$F2psEnteredState restore end} def
+
+$F2psBegin
+10 setmiterlimit
+0 slj 0 slc
+ 0.06299 0.06299 sc
+%
+% Fig objects follow
+%
+% 
+% here starts figure with depth 50
+% Ellipse
+7.500 slw
+n 1800 1125 113 113 0 360 DrawEllipse gs col0 s gr
+
+% Ellipse
+n 1350 1125 113 113 0 360 DrawEllipse gs col0 s gr
+
+% Ellipse
+n 450 1125 113 113 0 360 DrawEllipse gs 0.00 setgray ef gr gs col0 s gr
+
+% Ellipse
+n 900 1125 113 113 0 360 DrawEllipse gs col0 s gr
+
+% Polyline
+n 450 450 m 2700 450 l 2700 1800 l 450 1800 l
+ cp gs col0 s gr 
+% here ends figure;
+$F2psEnd
+rs
+showpage
diff --git a/doc/domain.fig b/doc/domain.fig
new file mode 100644
index 0000000..566055a
--- /dev/null
+++ b/doc/domain.fig
@@ -0,0 +1,15 @@
+#FIG 3.2
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 1800 1125 113 113 1800 1125 1913 1125
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 1350 1125 113 113 1350 1125 1463 1125
+1 3 0 1 0 0 50 -1 20 0.000 1 0.0000 450 1125 113 113 450 1125 563 1125
+1 3 0 1 0 7 50 -1 -1 0.000 1 0.0000 900 1125 113 113 900 1125 1013 1125
+2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
+	 450 450 2700 450 2700 1800 450 1800 450 450